@rune-kit/rune 2.1.1

package/compiler/bin/rune.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+
+/**
+ * Rune CLI
+ *
+ * Commands:
+ *   rune init    — Interactive setup for a new project
+ *   rune build   — Compile skills for the configured platform
+ *   rune doctor  — Validate compiled output
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import { getAdapter, listPlatforms } from '../adapters/index.js';
+import { buildAll } from '../emitter.js';
+import { runDoctor, formatDoctorResults } from '../doctor.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const RUNE_ROOT = path.resolve(__dirname, '../..');
+
+const CONFIG_FILE = 'rune.config.json';
+
+// ─── Helpers ───
+
+function log(msg) { console.log(msg); }
+function logStep(icon, msg) { console.log(`  ${icon} ${msg}`); }
+
+async function readConfig(projectRoot) {
+  const configPath = path.join(projectRoot, CONFIG_FILE);
+  if (!existsSync(configPath)) return null;
+  return JSON.parse(await readFile(configPath, 'utf-8'));
+}
+
+async function writeConfig(projectRoot, config) {
+  const configPath = path.join(projectRoot, CONFIG_FILE);
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+function detectPlatform(projectRoot) {
+  if (existsSync(path.join(projectRoot, '.claude-plugin'))) return 'claude';
+  if (existsSync(path.join(projectRoot, '.cursor'))) return 'cursor';
+  if (existsSync(path.join(projectRoot, '.windsurf'))) return 'windsurf';
+  if (existsSync(path.join(projectRoot, '.agent'))) return 'antigravity';
+  if (existsSync(path.join(projectRoot, '.openclaw'))) return 'openclaw';
+  return null;
+}
+
+function discoverExtensions() {
+  const extDir = path.join(RUNE_ROOT, 'extensions');
+  if (!existsSync(extDir)) return [];
+  return [];
+}
+
+async function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// ─── Commands ───
+
+async function cmdInit(projectRoot, args) {
+  log('');
+  log('  ╭──────────────────────────────────────────╮');
+  log('  │  Rune — Less skills. Deeper connections.  │');
+  log('  ╰──────────────────────────────────────────╯');
+  log('');
+
+  // Platform detection / selection
+  let platform = args.platform || detectPlatform(projectRoot);
+
+  if (platform) {
+    logStep('→', `Detected: ${platform}`);
+  } else {
+    log('  Available platforms: ' + listPlatforms().join(', '));
+    const answer = await prompt('  ? Select platform: ');
+    platform = answer.toLowerCase();
+    if (!listPlatforms().includes(platform)) {
+      platform = 'generic';
+      logStep('→', `Unknown platform, using generic adapter`);
+    }
+  }
+
+  if (platform === 'claude') {
+    logStep('✓', 'Claude Code detected — Rune works as a native plugin. No compilation needed.');
+    log('');
+    return;
+  }
+
+  // Extension pack selection
+  const extensions = args.extensions
+    ? args.extensions.split(',')
+    : null; // null = all
+
+  // Build config
+  const config = {
+    $schema: 'https://rune-kit.github.io/rune/config-schema.json',
+    version: 1,
+    platform,
+    source: RUNE_ROOT,
+    skills: {
+      disabled: args.disable ? args.disable.split(',') : [],
+    },
+    extensions: {
+      enabled: extensions,
+    },
+    output: {
+      index: true,
+    },
+  };
+
+  await writeConfig(projectRoot, config);
+  logStep('✓', 'Created rune.config.json');
+
+  // Auto-build
+  const adapter = getAdapter(platform);
+  const stats = await buildAll({
+    runeRoot: RUNE_ROOT,
+    outputRoot: projectRoot,
+    adapter,
+    disabledSkills: config.skills.disabled,
+    enabledPacks: config.extensions.enabled,
+  });
+
+  logStep('✓', `Built ${stats.skillCount} skills + ${stats.packCount} extensions to ${adapter.outputDir}/`);
+
+  if (stats.errors.length > 0) {
+    for (const err of stats.errors) {
+      logStep('✗', `Error: ${err.file} — ${err.error}`);
+    }
+  }
+
+  log('');
+  log('  Next: Start coding. Rune skills are active in your AI assistant.');
+  log('');
+}
+
+async function cmdBuild(projectRoot, args) {
+  const config = await readConfig(projectRoot);
+
+  const platform = args.platform || config?.platform;
+  if (!platform) {
+    log('  ✗ No platform configured. Run `rune init` first.');
+    process.exit(1);
+  }
+
+  if (platform === 'claude') {
+    log('  Claude Code uses source SKILL.md files directly. No compilation needed.');
+    return;
+  }
+
+  const adapter = getAdapter(platform);
+  const runeRoot = config?.source || RUNE_ROOT;
+  const outputRoot = args.output || projectRoot;
+  const disabledSkills = config?.skills?.disabled || [];
+  const enabledPacks = config?.extensions?.enabled || null;
+
+  log('');
+  log(`  [parse]     Discovering skills...`);
+
+  const stats = await buildAll({
+    runeRoot,
+    outputRoot,
+    adapter,
+    disabledSkills,
+    enabledPacks,
+  });
+
+  log(`  [transform] Platform: ${stats.platform}`);
+  log(`  [transform] Resolved ${stats.crossRefsResolved} cross-references`);
+  log(`  [transform] Resolved ${stats.toolRefsResolved} tool-name references`);
+  log(`  [emit]      ${stats.skillCount} skills + ${stats.packCount} extensions`);
+
+  if (stats.skipped.length > 0) {
+    log(`  [skip]      ${stats.skipped.length} disabled: ${stats.skipped.join(', ')}`);
+  }
+
+  if (stats.errors.length > 0) {
+    for (const err of stats.errors) {
+      log(`  [error]     ${err.file}: ${err.error}`);
+    }
+  }
+
+  log('');
+  log(`  ✓ Built ${stats.files.length} files to ${adapter.outputDir}/`);
+  log('');
+}
+
+async function cmdDoctor(projectRoot, args) {
+  const config = await readConfig(projectRoot);
+
+  if (!config) {
+    log('  ✗ No rune.config.json found. Run `rune init` first.');
+    process.exit(1);
+  }
+
+  const platform = args.platform || config.platform;
+  const adapter = getAdapter(platform);
+  const runeRoot = config.source || RUNE_ROOT;
+
+  const results = await runDoctor({
+    outputRoot: projectRoot,
+    adapter,
+    config,
+    runeRoot,
+  });
+
+  log(formatDoctorResults(results));
+
+  if (!results.healthy) process.exit(1);
+}
+
+// ─── Arg Parsing ───
+
+function parseArgs(argv) {
+  const args = {};
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { command: positional[0], args };
+}
+
+// ─── Main ───
+
+async function main() {
+  const { command, args } = parseArgs(process.argv.slice(2));
+  const projectRoot = process.cwd();
+
+  switch (command) {
+    case 'init':
+      await cmdInit(projectRoot, args);
+      break;
+    case 'build':
+      await cmdBuild(projectRoot, args);
+      break;
+    case 'doctor':
+      await cmdDoctor(projectRoot, args);
+      break;
+    case 'help':
+    case '--help':
+    case undefined:
+      log('');
+      log('  Rune CLI — Skill mesh for AI coding assistants');
+      log('');
+      log('  Commands:');
+      log('    init     Interactive setup (auto-detects platform)');
+      log('    build    Compile skills for configured platform');
+      log('    doctor   Validate compiled output');
+      log('');
+      log('  Options:');
+      log('    --platform <name>   Override platform (cursor, windsurf, antigravity, openclaw, generic)');
+      log('    --output <dir>      Override output directory');
+      log('    --disable <skills>  Comma-separated skills to disable');
+      log('');
+      break;
+    default:
+      log(`  ✗ Unknown command: ${command}. Run \`rune help\` for usage.`);
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error('  ✗ Fatal:', err.message);
+  process.exit(1);
+});

package/compiler/doctor.js

@@ -0,0 +1,153 @@
+/**
+ * Doctor — Validates compiled output
+ *
+ * Checks: files exist, cross-references resolve, layer discipline, source freshness.
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Run doctor checks on compiled output
+ *
+ * @param {object} options
+ * @param {string} options.outputRoot - project root
+ * @param {object} options.adapter - platform adapter
+ * @param {object} options.config - rune.config.json contents
+ * @param {string} options.runeRoot - rune source root
+ * @returns {Promise<object>} doctor results
+ */
+export async function runDoctor({ outputRoot, adapter, config, runeRoot }) {
+  const results = {
+    platform: adapter.name,
+    checks: [],
+    warnings: [],
+    errors: [],
+    healthy: true,
+  };
+
+  // Check 1: Config exists
+  const configPath = path.join(outputRoot, 'rune.config.json');
+  if (existsSync(configPath)) {
+    results.checks.push({ name: 'Config file', status: 'pass' });
+  } else {
+    results.checks.push({ name: 'Config file', status: 'fail', detail: 'rune.config.json not found' });
+    results.errors.push('rune.config.json not found. Run `rune init` first.');
+    results.healthy = false;
+  }
+
+  // Check 2: Output directory exists
+  if (adapter.name === 'claude') {
+    results.checks.push({ name: 'Output directory', status: 'skip', detail: 'Claude Code uses source directly' });
+    return results;
+  }
+
+  const outputDir = path.join(outputRoot, adapter.outputDir);
+  if (existsSync(outputDir)) {
+    results.checks.push({ name: 'Output directory', status: 'pass', detail: outputDir });
+  } else {
+    results.checks.push({ name: 'Output directory', status: 'fail', detail: `${outputDir} not found` });
+    results.errors.push(`Output directory ${outputDir} not found. Run \`rune build\` first.`);
+    results.healthy = false;
+    return results;
+  }
+
+  // Check 3: Count skill files
+  const files = await readdir(outputDir);
+  const skillFiles = files.filter(f => f.startsWith('rune-') && f !== `rune-index${adapter.fileExtension}`);
+  const expectedSkillCount = 55 - (config.skills?.disabled?.length || 0);
+
+  if (skillFiles.length >= expectedSkillCount) {
+    results.checks.push({ name: 'Skill files', status: 'pass', detail: `${skillFiles.length}/${expectedSkillCount}` });
+  } else {
+    results.checks.push({ name: 'Skill files', status: 'warn', detail: `${skillFiles.length}/${expectedSkillCount} present` });
+    results.warnings.push(`Expected ${expectedSkillCount} skill files, found ${skillFiles.length}`);
+  }
+
+  // Check 4: Cross-reference integrity
+  const crossRefErrors = await checkCrossRefs(outputDir, skillFiles, adapter);
+  if (crossRefErrors.length === 0) {
+    results.checks.push({ name: 'Cross-references', status: 'pass' });
+  } else {
+    results.checks.push({ name: 'Cross-references', status: 'warn', detail: `${crossRefErrors.length} dangling` });
+    results.warnings.push(...crossRefErrors);
+  }
+
+  // Check 5: Index file exists
+  const indexFile = `rune-index${adapter.fileExtension}`;
+  if (files.includes(indexFile)) {
+    results.checks.push({ name: 'Index file', status: 'pass' });
+  } else {
+    results.checks.push({ name: 'Index file', status: 'warn', detail: 'Missing index file' });
+    results.warnings.push('Index file not found. Rebuild with `rune build`.');
+  }
+
+  // Check 6: Disabled skills warning
+  const disabled = config.skills?.disabled || [];
+  if (disabled.length > 0) {
+    results.warnings.push(`${disabled.length} skills disabled: ${disabled.join(', ')}`);
+  }
+
+  if (results.errors.length > 0) results.healthy = false;
+
+  return results;
+}
+
+/**
+ * Check that all cross-references in compiled files point to existing files
+ */
+async function checkCrossRefs(outputDir, files, adapter) {
+  const errors = [];
+  const fileSet = new Set(files);
+
+  for (const file of files) {
+    const content = await readFile(path.join(outputDir, file), 'utf-8');
+
+    // Look for references to other rune skills
+    const refPattern = /rune-([a-z][\w-]*)/g;
+    let match;
+    while ((match = refPattern.exec(content)) !== null) {
+      const refName = match[1];
+      const expectedFile = `rune-${refName}${adapter.fileExtension}`;
+      if (!fileSet.has(expectedFile) && refName !== 'index' && refName !== 'kit') {
+        errors.push(`${file}: references rune-${refName} but ${expectedFile} not found`);
+      }
+    }
+  }
+
+  return [...new Set(errors)]; // deduplicate
+}
+
+/**
+ * Format doctor results for console output
+ */
+export function formatDoctorResults(results) {
+  const lines = [];
+  lines.push(`\n  Platform: ${results.platform}`);
+
+  for (const check of results.checks) {
+    const icon = check.status === 'pass' ? '✓' : check.status === 'warn' ? '!' : '✗';
+    const detail = check.detail ? ` (${check.detail})` : '';
+    lines.push(`  [${icon}] ${check.name}${detail}`);
+  }
+
+  if (results.warnings.length > 0) {
+    lines.push('');
+    for (const w of results.warnings) {
+      lines.push(`  ⚠ ${w}`);
+    }
+  }
+
+  if (results.errors.length > 0) {
+    lines.push('');
+    for (const e of results.errors) {
+      lines.push(`  ✗ ${e}`);
+    }
+  }
+
+  lines.push('');
+  lines.push(results.healthy ? '  ✓ Rune installation healthy' : '  ✗ Rune installation has issues');
+
+  return lines.join('\n');
+}

package/compiler/emitter.js

@@ -0,0 +1,240 @@
+/**
+ * Emitter
+ *
+ * Writes transformed skill files to the platform's output directory.
+ * Handles file naming, directory creation, and index generation.
+ */
+
+import { readdir, readFile, mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseSkill, parsePack } from './parser.js';
+import { transformSkill } from './transformer.js';
+
+/**
+ * Discover all SKILL.md files in the skills directory
+ *
+ * @param {string} skillsDir - path to skills/ directory
+ * @returns {Promise<string[]>} array of SKILL.md file paths
+ */
+async function discoverSkills(skillsDir) {
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  const paths = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
+    if (existsSync(skillFile)) {
+      paths.push(skillFile);
+    }
+  }
+
+  return paths.sort();
+}
+
+/**
+ * Discover all PACK.md files in the extensions directory
+ *
+ * @param {string} extensionsDir - path to extensions/ directory
+ * @param {string[]} [enabledPacks] - list of enabled pack names (null = all)
+ * @returns {Promise<string[]>} array of PACK.md file paths
+ */
+async function discoverPacks(extensionsDir, enabledPacks = null) {
+  if (!existsSync(extensionsDir)) return [];
+
+  const entries = await readdir(extensionsDir, { withFileTypes: true });
+  const paths = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (enabledPacks && !enabledPacks.includes(entry.name) && !enabledPacks.includes(`@rune/${entry.name}`)) {
+      continue;
+    }
+    const packFile = path.join(extensionsDir, entry.name, 'PACK.md');
+    if (existsSync(packFile)) {
+      paths.push(packFile);
+    }
+  }
+
+  return paths.sort();
+}
+
+/**
+ * Generate output filename for a skill
+ */
+function outputFileName(skillName, adapter) {
+  return `${adapter.skillPrefix}${skillName}${adapter.skillSuffix}${adapter.fileExtension}`;
+}
+
+/**
+ * Build all skills for a target platform
+ *
+ * @param {object} options
+ * @param {string} options.runeRoot - root of the Rune repo
+ * @param {string} options.outputRoot - where to write output (project root or dist/)
+ * @param {object} options.adapter - platform adapter
+ * @param {string[]} [options.disabledSkills] - skills to skip
+ * @param {string[]} [options.enabledPacks] - extension packs to include (null = all)
+ * @returns {Promise<object>} build result stats
+ */
+export async function buildAll({ runeRoot, outputRoot, adapter, disabledSkills = [], enabledPacks = null }) {
+  // Claude Code = passthrough, no build needed
+  if (adapter.name === 'claude') {
+    return {
+      platform: 'claude',
+      message: 'Claude Code uses source SKILL.md files directly. No compilation needed.',
+      skillCount: 0,
+      packCount: 0,
+      files: [],
+    };
+  }
+
+  const skillsDir = path.join(runeRoot, 'skills');
+  const extensionsDir = path.join(runeRoot, 'extensions');
+  const outputDir = path.join(outputRoot, adapter.outputDir);
+
+  // Ensure output directory exists
+  await mkdir(outputDir, { recursive: true });
+
+  const skillPaths = await discoverSkills(skillsDir);
+  const packPaths = await discoverPacks(extensionsDir, enabledPacks);
+
+  const stats = {
+    platform: adapter.name,
+    skillCount: 0,
+    packCount: 0,
+    crossRefsResolved: 0,
+    toolRefsResolved: 0,
+    files: [],
+    skipped: [],
+    errors: [],
+  };
+
+  // Build skills
+  for (const skillPath of skillPaths) {
+    try {
+      const content = await readFile(skillPath, 'utf-8');
+      const parsed = parseSkill(content, skillPath);
+
+      // Check disabled
+      if (disabledSkills.includes(parsed.name)) {
+        stats.skipped.push(parsed.name);
+        continue;
+      }
+
+      const { header, body, footer } = transformSkill(parsed, adapter);
+      const output = [header, body, footer].filter(Boolean).join('\n');
+      const fileName = outputFileName(parsed.name, adapter);
+      const outputPath = path.join(outputDir, fileName);
+
+      await writeFile(outputPath, output, 'utf-8');
+
+      stats.skillCount++;
+      stats.crossRefsResolved += parsed.crossRefs.length;
+      stats.toolRefsResolved += parsed.toolRefs.length;
+      stats.files.push(fileName);
+    } catch (err) {
+      stats.errors.push({ file: skillPath, error: err.message });
+    }
+  }
+
+  // Build extension packs
+  for (const packPath of packPaths) {
+    try {
+      const content = await readFile(packPath, 'utf-8');
+      const parsed = parsePack(content, packPath);
+      const { header, body, footer } = transformSkill(parsed, adapter);
+      const output = [header, body, footer].filter(Boolean).join('\n');
+      const packName = path.basename(path.dirname(packPath));
+      const fileName = outputFileName(`ext-${packName}`, adapter);
+      const outputPath = path.join(outputDir, fileName);
+
+      await writeFile(outputPath, output, 'utf-8');
+
+      stats.packCount++;
+      stats.files.push(fileName);
+    } catch (err) {
+      stats.errors.push({ file: packPath, error: err.message });
+    }
+  }
+
+  // Generate index file
+  const indexContent = generateIndex(stats, adapter);
+  const indexFileName = outputFileName('index', adapter);
+  await writeFile(path.join(outputDir, indexFileName), indexContent, 'utf-8');
+  stats.files.push(indexFileName);
+
+  // OpenClaw adapter: generate manifest + TypeScript entry point
+  if (adapter.name === 'openclaw' && adapter.generateManifest && adapter.generateEntryPoint) {
+    const pluginJsonPath = path.join(runeRoot, '.claude-plugin', 'plugin.json');
+    let pluginJson = { version: '0.0.0' };
+    if (existsSync(pluginJsonPath)) {
+      pluginJson = JSON.parse(await readFile(pluginJsonPath, 'utf-8'));
+    }
+
+    // Collect parsed skills for manifest/entry generation
+    const parsedSkills = [];
+    for (const sp of skillPaths) {
+      try {
+        const c = await readFile(sp, 'utf-8');
+        parsedSkills.push(parseSkill(c, sp));
+      } catch { /* skip on error */ }
+    }
+
+    // Read skill-router content for system prompt injection
+    const routerPath = path.join(runeRoot, 'skills', 'skill-router', 'SKILL.md');
+    let routerContent = '';
+    if (existsSync(routerPath)) {
+      routerContent = await readFile(routerPath, 'utf-8');
+    }
+
+    // Write openclaw.plugin.json to parent of skills dir (.openclaw/rune/)
+    const openclawRoot = path.resolve(outputDir, '..');
+    const manifest = adapter.generateManifest(parsedSkills, pluginJson);
+    await writeFile(
+      path.join(openclawRoot, 'openclaw.plugin.json'),
+      JSON.stringify(manifest, null, 2) + '\n',
+      'utf-8',
+    );
+    stats.files.push('openclaw.plugin.json');
+
+    // Write src/index.ts entry point
+    const srcDir = path.join(openclawRoot, 'src');
+    await mkdir(srcDir, { recursive: true });
+    const entryPoint = adapter.generateEntryPoint(parsedSkills, routerContent);
+    await writeFile(path.join(srcDir, 'index.ts'), entryPoint, 'utf-8');
+    stats.files.push('src/index.ts');
+  }
+
+  return stats;
+}
+
+/**
+ * Generate an index file listing all compiled skills
+ */
+function generateIndex(stats, adapter) {
+  const lines = [
+    '# Rune Skill Index',
+    '',
+    `> Platform: ${adapter.name} | Skills: ${stats.skillCount} | Extensions: ${stats.packCount}`,
+    '',
+    '## Core Skills',
+    '',
+    ...stats.files
+      .filter(f => !f.includes('ext-') && !f.includes('index'))
+      .map(f => `- ${f}`),
+    '',
+  ];
+
+  const extFiles = stats.files.filter(f => f.includes('ext-'));
+  if (extFiles.length > 0) {
+    lines.push('## Extension Packs', '', ...extFiles.map(f => `- ${f}`), '');
+  }
+
+  lines.push(
+    '---',
+    '> Rune Skill Mesh — https://github.com/rune-kit/rune',
+  );
+
+  return lines.join('\n');
+}