@rune-kit/rune 2.11.0 → 2.12.0

package/compiler/commands/hooks/presets.js

@@ -0,0 +1,116 @@
+/**
+ * Hook preset definitions for `rune hooks install`.
+ *
+ * Presets:
+ *   - strict  — dispatcher blocks on BLOCK verdict (returns non-zero exit)
+ *   - gentle  — dispatcher warns only (always exits 0), adds --gentle flag
+ *   - off     — no hooks installed (uninstall semantics)
+ *
+ * Each hook command is `rune hook-dispatch <skill>` so the dispatcher owns
+ * skill→command mapping. Commands carry the RUNE_MANAGED signature so we can
+ * detect and cleanly replace them without comment markers (settings.json is JSON).
+ */
+
+export const RUNE_MANAGED_SIGNATURE = 'rune hook-dispatch';
+
+/** Shared relative path to avoid per-file duplication. */
+export const SETTINGS_REL_PATH = '.claude/settings.json';
+
+const DISPATCH_CMD = 'npx --yes @rune-kit/rune hook-dispatch';
+
+/**
+ * Regex that matches the exact dispatch invocation Rune writes.
+ * Matches: `npx [--yes] @rune-kit/rune hook-dispatch` or
+ *          `node ... @rune-kit/rune hook-dispatch` as word boundary.
+ * Does NOT match arbitrary strings that merely contain those words.
+ */
+const RUNE_DISPATCH_RE = /(^|\s)npx(\s+--yes)?\s+@rune-kit\/rune\s+hook-dispatch\b/;
+
+/**
+ * Regex that matches tier-emitted commands — they substitute a tier env var
+ * (e.g. `${RUNE_PRO_ROOT}`, `${RUNE_BUSINESS_ROOT}`). These are Rune-managed
+ * because only `rune hooks install --tier <name>` writes them.
+ */
+const RUNE_TIER_RE = /\$\{RUNE_[A-Z][A-Z0-9_]*_ROOT\}/;
+
+/**
+ * Build a preset hooks block for merging into `.claude/settings.json`.
+ *
+ * @param {'strict'|'gentle'} preset
+ * @returns {Object} — { hooks: { PreToolUse: [...], PostToolUse: [...], Stop: [...] } }
+ */
+export function buildPreset(preset) {
+  if (preset !== 'strict' && preset !== 'gentle') {
+    throw new Error(`Unknown preset: ${preset}. Use 'strict' or 'gentle'.`);
+  }
+
+  const flag = preset === 'gentle' ? ' --gentle' : '';
+
+  return {
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: 'Edit|Write',
+          hooks: [
+            {
+              type: 'command',
+              command: `${DISPATCH_CMD} preflight${flag}`,
+              async: preset === 'gentle',
+            },
+          ],
+        },
+        {
+          matcher: 'Bash',
+          hooks: [
+            {
+              type: 'command',
+              command: `${DISPATCH_CMD} sentinel${flag}`,
+              async: false,
+            },
+          ],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: 'Edit|Write',
+          hooks: [
+            {
+              type: 'command',
+              command: `${DISPATCH_CMD} dependency-doctor${flag}`,
+              async: true,
+            },
+          ],
+        },
+      ],
+      Stop: [
+        {
+          matcher: '.*',
+          hooks: [
+            {
+              type: 'command',
+              command: `${DISPATCH_CMD} completion-gate${flag}`,
+              async: false,
+            },
+          ],
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * Skills wired by presets — used by `rune hooks status` to verify skill existence.
+ */
+export const WIRED_SKILLS = ['preflight', 'sentinel', 'dependency-doctor', 'completion-gate'];
+
+/**
+ * Detect if a hook command entry is Rune-managed.
+ * Matches only the exact `npx [--yes] @rune-kit/rune hook-dispatch` invocation
+ * to avoid false-positives on user commands that merely contain those words.
+ *
+ * @param {Object} entry — single hook entry { type, command, ... }
+ */
+export function isRuneManaged(entry) {
+  if (!entry || typeof entry.command !== 'string') return false;
+  return RUNE_DISPATCH_RE.test(entry.command) || RUNE_TIER_RE.test(entry.command);
+}

package/compiler/commands/hooks/status.js

@@ -0,0 +1,112 @@
+/**
+ * `rune hooks status [--platform <name>|all]`
+ *
+ * For each detected (or requested) platform, reports:
+ *   - installed (boolean)
+ *   - preset (gentle | strict | mixed | null)
+ *   - wired skills
+ *   - missing skills (present-in-project-but-not-wired)
+ *   - per-platform notes
+ *
+ * Claude Code adapter additionally returns `events` for hook-level detail.
+ */
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { ADAPTERS, CAPABILITIES, detectPlatforms, getAdapter, PLATFORM_KEYS } from '../../adapters/hooks/index.js';
+import { WIRED_SKILLS } from './presets.js';
+import { checkManifestRequires, locateTierManifest, resolveTier } from './tiers.js';
+
+/**
+ * @param {string} projectRoot
+ * @param {string} runeRoot
+ * @param {{platform?: string|string[], tier?: string|string[]}} args
+ */
+export async function hookStatus(projectRoot, runeRoot, args = {}) {
+  const platforms = resolvePlatforms(projectRoot, args.platform);
+  const missingInRepo = findMissingSkills(runeRoot, WIRED_SKILLS);
+  const tiers = await resolveRequestedTiers(projectRoot, args.tier);
+
+  if (platforms.length === 0) {
+    return {
+      platforms: [],
+      results: [],
+      tiers,
+      missingInRepo,
+      notes: [
+        'No target platform detected. Create `.claude/`, `.cursor/`, `.windsurf/`, or `.antigravity/` first, or pass `--platform <name>`.',
+      ],
+    };
+  }
+
+  const results = [];
+  for (const id of platforms) {
+    const adapter = getAdapter(id);
+    const info = await adapter.status(projectRoot);
+    results.push({
+      platform: id,
+      capability: CAPABILITIES[id] ?? null,
+      ...info,
+    });
+  }
+
+  return { platforms, results, tiers, missingInRepo, notes: [] };
+}
+
+async function resolveRequestedTiers(projectRoot, requested) {
+  if (!requested) return [];
+  const list = Array.isArray(requested) ? requested : [requested];
+  const out = [];
+  for (const tier of Array.from(new Set(list))) {
+    const loc = locateTierManifest(tier, projectRoot);
+    if (!loc) {
+      out.push({ tier, found: false, manifestPath: null, requiresOk: false, requiresMissing: [], entries: 0 });
+      continue;
+    }
+    try {
+      const manifest = await resolveTier(tier, projectRoot);
+      const req = checkManifestRequires(manifest);
+      out.push({
+        tier,
+        found: true,
+        manifestPath: loc,
+        requiresOk: req.ok,
+        requiresMissing: req.missing,
+        entries: manifest.entries.length,
+        version: manifest.version,
+      });
+    } catch (err) {
+      out.push({
+        tier,
+        found: false,
+        manifestPath: loc,
+        error: err.message,
+        requiresOk: false,
+        requiresMissing: [],
+        entries: 0,
+      });
+    }
+  }
+  return out;
+}
+
+function resolvePlatforms(projectRoot, requested) {
+  if (!requested) return detectPlatforms(projectRoot);
+  const list = Array.isArray(requested) ? requested : [requested];
+  const expanded = [];
+  for (const item of list) {
+    if (item === 'all') {
+      expanded.push(...PLATFORM_KEYS);
+    } else if (ADAPTERS[item]) {
+      expanded.push(item);
+    } else {
+      throw new Error(`Unknown platform: ${item}. Choose from: ${PLATFORM_KEYS.join(', ')}, all`);
+    }
+  }
+  return Array.from(new Set(expanded));
+}
+
+function findMissingSkills(runeRoot, skills) {
+  const skillsDir = path.join(runeRoot, 'skills');
+  return skills.filter((skill) => !existsSync(path.join(skillsDir, skill, 'SKILL.md')));
+}

package/compiler/commands/hooks/tiers.js

@@ -0,0 +1,221 @@
+/**
+ * Tier manifest loader for `rune hooks install/uninstall/status`.
+ *
+ * The Free compiler is tier-agnostic. Tiers (Pro / Business / custom) ship
+ * their own `hooks/manifest.json` files following the schema described in
+ * `docs/HOOKS.md`. This module resolves a `--tier` flag (or explicit path)
+ * into a loaded manifest.
+ *
+ * Resolution order for `--tier pro`:
+ *   1. `$RUNE_PRO_ROOT/hooks/manifest.json` (env var — primary)
+ *   2. `<projectRoot>/../Pro/hooks/manifest.json` (monorepo sibling)
+ *   3. Fails with a helpful upgrade message.
+ *
+ * For `--tier-manifest <path>` we load the file directly. This keeps the
+ * compiler side free of hardcoded tier logic — any future tier (Business,
+ * third-party) plugs in by shipping a manifest at a known path.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/** Known tier env vars. Adding a new tier = add its env var here. */
+export const TIER_ENV_VARS = Object.freeze({
+  pro: 'RUNE_PRO_ROOT',
+  business: 'RUNE_BUSINESS_ROOT',
+});
+
+/** Valid event names a manifest entry may declare. */
+const VALID_EVENTS = new Set(['UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'statusLine']);
+
+/** Tier names must be simple lowercase identifiers. Blocks `../../etc` and similar traversal. */
+const TIER_NAME_RE = /^[a-z][a-z0-9-]{0,31}$/;
+
+/**
+ * Assert a tier name is safe to use as a path segment.
+ * @param {string} tier
+ */
+function assertSafeTierName(tier) {
+  if (typeof tier !== 'string' || !TIER_NAME_RE.test(tier)) {
+    throw new Error(
+      `Invalid tier name: ${JSON.stringify(tier)}. Tier must be a lowercase identifier (a-z, 0-9, dash).`,
+    );
+  }
+}
+
+/**
+ * Locate a tier manifest by tier name.
+ *
+ * @param {string} tier — 'pro' | 'business' | custom
+ * @param {string} projectRoot — the user project root (used for monorepo fallback)
+ * @returns {string|null} absolute path if found, else null
+ */
+export function locateTierManifest(tier, projectRoot) {
+  assertSafeTierName(tier);
+  const envVar = TIER_ENV_VARS[tier];
+  if (envVar && process.env[envVar]) {
+    // Resolve + re-anchor so that env var values can't traverse out via `..`.
+    const root = path.resolve(process.env[envVar]);
+    const candidate = path.join(root, 'hooks', 'manifest.json');
+    if (existsSync(candidate)) return candidate;
+  }
+  // Monorepo fallback: <projectRoot>/../<Tier>/hooks/manifest.json (capitalized tier).
+  // tier is pre-validated against TIER_NAME_RE so no traversal is possible here.
+  const capitalized = tier.charAt(0).toUpperCase() + tier.slice(1);
+  const fallback = path.resolve(projectRoot, '..', capitalized, 'hooks', 'manifest.json');
+  if (existsSync(fallback)) return fallback;
+  return null;
+}
+
+/**
+ * Load + validate a tier manifest JSON file.
+ *
+ * @param {string} manifestPath
+ * @returns {Promise<TierManifest>}
+ */
+export async function loadTierManifest(manifestPath) {
+  if (!existsSync(manifestPath)) {
+    throw new Error(`Tier manifest not found: ${manifestPath}`);
+  }
+  const raw = await readFile(manifestPath, 'utf-8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Tier manifest ${manifestPath} is not valid JSON: ${err.message}`);
+  }
+  return validateManifest(parsed, manifestPath);
+}
+
+/**
+ * Validate manifest shape + normalize to internal form.
+ * Throws with a specific error on any violation so users get actionable output.
+ */
+export function validateManifest(manifest, source = '<memory>') {
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error(`Manifest ${source}: expected top-level object`);
+  }
+  if (typeof manifest.tier !== 'string' || !manifest.tier) {
+    throw new Error(`Manifest ${source}: missing required string field 'tier'`);
+  }
+  if (!Array.isArray(manifest.entries)) {
+    throw new Error(`Manifest ${source}: 'entries' must be an array`);
+  }
+
+  const seenIds = new Set();
+  const entries = manifest.entries.map((raw, i) => {
+    const where = `${source} entries[${i}]`;
+    if (!raw || typeof raw !== 'object') {
+      throw new Error(`${where}: expected object`);
+    }
+    if (typeof raw.id !== 'string' || !raw.id) {
+      throw new Error(`${where}: missing required string 'id'`);
+    }
+    if (seenIds.has(raw.id)) {
+      throw new Error(`${where}: duplicate entry id '${raw.id}'`);
+    }
+    seenIds.add(raw.id);
+    if (typeof raw.event !== 'string' || !VALID_EVENTS.has(raw.event)) {
+      throw new Error(
+        `${where}: 'event' must be one of ${[...VALID_EVENTS].join(', ')} (got ${JSON.stringify(raw.event)})`,
+      );
+    }
+    if (typeof raw.command !== 'string' || !raw.command) {
+      throw new Error(`${where}: missing required string 'command'`);
+    }
+    if (raw.matcher !== undefined && typeof raw.matcher !== 'string') {
+      throw new Error(`${where}: 'matcher' must be a string if present`);
+    }
+    if (raw.event !== 'statusLine' && raw.event !== 'Stop' && !raw.matcher) {
+      throw new Error(`${where}: '${raw.event}' requires a 'matcher' string (e.g. 'Edit|Write' or '.*')`);
+    }
+    if (raw.globs !== undefined && !Array.isArray(raw.globs)) {
+      throw new Error(`${where}: 'globs' must be an array of strings if present`);
+    }
+    return {
+      id: raw.id,
+      skill: typeof raw.skill === 'string' && raw.skill ? raw.skill : raw.id,
+      event: raw.event,
+      matcher: raw.matcher ?? null,
+      command: raw.command,
+      async: raw.async === true,
+      padding: typeof raw.padding === 'number' ? raw.padding : undefined,
+      claudeOnly: raw.claudeOnly === true,
+      description: typeof raw.description === 'string' ? raw.description : '',
+      globs: Array.isArray(raw.globs) ? [...raw.globs] : null,
+      platforms: raw.platforms && typeof raw.platforms === 'object' ? { ...raw.platforms } : {},
+    };
+  });
+
+  return {
+    name: typeof manifest.name === 'string' ? manifest.name : `Rune ${manifest.tier} Hooks`,
+    description: typeof manifest.description === 'string' ? manifest.description : '',
+    tier: manifest.tier,
+    version: typeof manifest.version === 'string' ? manifest.version : '0.0.0',
+    requires: Array.isArray(manifest.requires) ? [...manifest.requires] : [],
+    entries,
+    overrides: manifest.overrides && typeof manifest.overrides === 'object' ? { ...manifest.overrides } : {},
+    source,
+  };
+}
+
+/**
+ * Check whether a manifest's `requires` list is satisfied by current env.
+ * Returns { ok, missing }.
+ */
+export function checkManifestRequires(manifest) {
+  const missing = (manifest.requires || []).filter((name) => !process.env[name]);
+  return { ok: missing.length === 0, missing };
+}
+
+/**
+ * Resolve a tier request (`--tier pro`) into a loaded, validated manifest,
+ * or throw with a helpful upgrade/missing-env message.
+ *
+ * @param {string} tier
+ * @param {string} projectRoot
+ * @returns {Promise<TierManifest>}
+ */
+export async function resolveTier(tier, projectRoot) {
+  const manifestPath = locateTierManifest(tier, projectRoot);
+  if (!manifestPath) {
+    const envHint = TIER_ENV_VARS[tier] ? ` Set $${TIER_ENV_VARS[tier]} to your ${tier} install dir.` : '';
+    throw new Error(
+      `Could not locate '${tier}' tier manifest.${envHint}` +
+        ` See https://rune.dev/docs/hooks#tiers for install instructions.`,
+    );
+  }
+  const manifest = await loadTierManifest(manifestPath);
+  if (manifest.tier !== tier) {
+    throw new Error(`Manifest at ${manifestPath} declares tier='${manifest.tier}' but was requested as '${tier}'`);
+  }
+  return manifest;
+}
+
+/**
+ * @typedef TierManifestEntry
+ * @property {string} id
+ * @property {string} skill
+ * @property {'UserPromptSubmit'|'PreToolUse'|'PostToolUse'|'Stop'|'statusLine'} event
+ * @property {string|null} matcher
+ * @property {string} command
+ * @property {boolean} async
+ * @property {number|undefined} padding
+ * @property {boolean} claudeOnly
+ * @property {string} description
+ * @property {string[]|null} globs
+ * @property {Record<string, string>} platforms
+ */
+
+/**
+ * @typedef TierManifest
+ * @property {string} name
+ * @property {string} description
+ * @property {string} tier
+ * @property {string} version
+ * @property {string[]} requires
+ * @property {TierManifestEntry[]} entries
+ * @property {Record<string, string>} overrides
+ * @property {string} source
+ */

package/compiler/commands/hooks/uninstall.js

@@ -0,0 +1,94 @@
+/**
+ * `rune hooks uninstall [--platform <name>|all]`
+ *
+ * Removes all Rune-managed hook/rule/workflow entries for one or more platforms,
+ * leaving user entries intact. If no platform artifacts exist, no-op.
+ */
+
+import { existsSync } from 'node:fs';
+import { unlink, writeFile } from 'node:fs/promises';
+import { ADAPTERS, detectPlatforms, getAdapter, PLATFORM_KEYS } from '../../adapters/hooks/index.js';
+import { resolveTier } from './tiers.js';
+
+/**
+ * @param {string} projectRoot
+ * @param {{dry?: boolean, platform?: string|string[], tier?: string|string[]}} args
+ */
+export async function uninstallHooks(projectRoot, args = {}) {
+  const platforms = resolvePlatforms(projectRoot, args.platform);
+  const tiers = await resolveTierManifests(projectRoot, args.tier);
+  if (platforms.length === 0) {
+    return {
+      platforms: [],
+      results: [],
+      tiers: tiers.map((m) => m.tier),
+      written: false,
+      notes: ['no target platform detected'],
+    };
+  }
+
+  const results = [];
+  let totalWrites = 0;
+  for (const id of platforms) {
+    const adapter = getAdapter(id);
+    const plan = await adapter.uninstall({ projectRoot, tierManifests: tiers });
+    let platformWrites = 0;
+    if (!args.dry) {
+      for (const file of plan.files) {
+        if (file.content === null) {
+          if (existsSync(file.path)) {
+            await unlink(file.path);
+            platformWrites += 1;
+          }
+        } else {
+          await writeFile(file.path, file.content, 'utf-8');
+          platformWrites += 1;
+        }
+      }
+    }
+    totalWrites += platformWrites;
+    results.push({
+      platform: id,
+      files: plan.files.map((f) => ({ path: f.path, deleted: f.content === null })),
+      notes: plan.notes,
+      writes: platformWrites,
+    });
+  }
+
+  return {
+    platforms,
+    tiers: tiers.map((m) => m.tier),
+    results,
+    written: !args.dry && totalWrites > 0,
+    notes: totalWrites === 0 && !args.dry ? ['no Rune-managed entries found'] : [],
+  };
+}
+
+async function resolveTierManifests(projectRoot, requested) {
+  if (!requested) return [];
+  const list = Array.isArray(requested) ? requested : [requested];
+  const unique = Array.from(new Set(list.filter((t) => typeof t === 'string' && t.length > 0)));
+  const manifests = [];
+  for (const tier of unique) {
+    manifests.push(await resolveTier(tier, projectRoot));
+  }
+  return manifests;
+}
+
+function resolvePlatforms(projectRoot, requested) {
+  if (!requested) return detectPlatforms(projectRoot);
+  const list = Array.isArray(requested) ? requested : [requested];
+  const expanded = [];
+  for (const item of list) {
+    if (item === 'all') {
+      // Uninstall `all` walks detected platforms only. Named platforms still work
+      // even with no directory — adapter uninstall() returns empty for missing dirs.
+      expanded.push(...detectPlatforms(projectRoot));
+    } else if (ADAPTERS[item]) {
+      expanded.push(item);
+    } else {
+      throw new Error(`Unknown platform: ${item}. Choose from: ${PLATFORM_KEYS.join(', ')}, all`);
+    }
+  }
+  return Array.from(new Set(expanded));
+}