@rune-kit/rune 2.12.0 → 2.12.2

package/compiler/__tests__/hooks-antigravity.test.js

@@ -4,12 +4,14 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
 import * as antigravity from '../adapters/hooks/antigravity.js';
 import { installHooks } from '../commands/hooks/install.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 
-const RUNE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNE_ROOT = path.resolve(__dirname, '..', '..');
 const RULES_DIR = '.antigravity/rules';
 
 let tmpRoot;

package/compiler/__tests__/hooks-cursor.test.js

@@ -4,12 +4,14 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
 import * as cursor from '../adapters/hooks/cursor.js';
 import { installHooks } from '../commands/hooks/install.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 
-const RUNE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNE_ROOT = path.resolve(__dirname, '..', '..');
 const RULES_DIR = '.cursor/rules';
 
 let tmpRoot;

package/compiler/__tests__/hooks-install.test.js

@@ -4,12 +4,14 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
 import { installHooks } from '../commands/hooks/install.js';
 import { SETTINGS_REL_PATH } from '../commands/hooks/presets.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 
-const RUNE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNE_ROOT = path.resolve(__dirname, '..', '..');
 
 let tmpRoot;
 

package/compiler/__tests__/hooks-tiers.test.js

@@ -18,18 +18,25 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
 import { installHooks } from '../commands/hooks/install.js';
 import { SETTINGS_REL_PATH } from '../commands/hooks/presets.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import {
+  _resetFreeVersionCache,
+  assertFreeVersionCompat,
   checkManifestRequires,
+  compareSemver,
+  getFreeVersion,
   loadTierManifest,
   locateTierManifest,
+  parseSemver,
   resolveTier,
   validateManifest,
 } from '../commands/hooks/tiers.js';
 
-const RUNE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNE_ROOT = path.resolve(__dirname, '..', '..');
 
 let tmpRoot;
 let tierRoot;
@@ -494,6 +501,100 @@ describe('review fixes: M3 overrides consumption', () => {
   });
 });
 
+describe('Gap 2: minFreeVersion version gate', () => {
+  test('parseSemver accepts x.y.z and ignores prerelease/build', () => {
+    assert.deepStrictEqual(parseSemver('2.12.0'), [2, 12, 0]);
+    assert.deepStrictEqual(parseSemver('2.12.0-rc.1'), [2, 12, 0]);
+    assert.deepStrictEqual(parseSemver('2.12.0+sha.abc'), [2, 12, 0]);
+    assert.strictEqual(parseSemver('not-a-version'), null);
+    assert.strictEqual(parseSemver(null), null);
+  });
+
+  test('compareSemver returns -1/0/1 ordering', () => {
+    assert.strictEqual(compareSemver('2.12.0', '2.12.0'), 0);
+    assert.strictEqual(compareSemver('2.11.9', '2.12.0'), -1);
+    assert.strictEqual(compareSemver('2.12.1', '2.12.0'), 1);
+    assert.strictEqual(compareSemver('3.0.0', '2.12.0'), 1);
+    assert.strictEqual(compareSemver('bogus', '2.12.0'), null);
+  });
+
+  test('validateManifest accepts optional minFreeVersion', () => {
+    const m = validateManifest({ ...PRO_MANIFEST_FIXTURE, minFreeVersion: '2.12.0' });
+    assert.strictEqual(m.minFreeVersion, '2.12.0');
+  });
+
+  test('validateManifest rejects non-semver minFreeVersion', () => {
+    assert.throws(
+      () => validateManifest({ ...PRO_MANIFEST_FIXTURE, minFreeVersion: 'latest' }),
+      /minFreeVersion.*must be semver/,
+    );
+  });
+
+  test('validateManifest rejects empty minFreeVersion string', () => {
+    assert.throws(() => validateManifest({ ...PRO_MANIFEST_FIXTURE, minFreeVersion: '' }), /minFreeVersion.*non-empty/);
+  });
+
+  test('assertFreeVersionCompat is a no-op when minFreeVersion unset', () => {
+    const m = validateManifest(PRO_MANIFEST_FIXTURE);
+    assert.doesNotThrow(() => assertFreeVersionCompat(m, '0.0.1'));
+  });
+
+  test('assertFreeVersionCompat passes when current >= minFreeVersion', () => {
+    const m = validateManifest({ ...PRO_MANIFEST_FIXTURE, minFreeVersion: '2.12.0' });
+    assert.doesNotThrow(() => assertFreeVersionCompat(m, '2.12.0'));
+    assert.doesNotThrow(() => assertFreeVersionCompat(m, '2.12.1'));
+    assert.doesNotThrow(() => assertFreeVersionCompat(m, '3.0.0'));
+  });
+
+  test('assertFreeVersionCompat throws helpful upgrade error when current < minFreeVersion', () => {
+    const m = validateManifest({ ...PRO_MANIFEST_FIXTURE, minFreeVersion: '2.12.0' });
+    assert.throws(
+      () => assertFreeVersionCompat(m, '2.11.0'),
+      (err) => {
+        assert.match(err.message, /requires Rune Free >= 2\.12\.0/);
+        assert.match(err.message, /installed compiler is 2\.11\.0/);
+        assert.match(err.message, /npm i -g @rune-kit\/rune@latest/);
+        assert.match(err.message, /--tier pro/);
+        return true;
+      },
+    );
+  });
+
+  test('resolveTier enforces minFreeVersion via assertFreeVersionCompat', async () => {
+    const futureManifest = { ...PRO_MANIFEST_FIXTURE, minFreeVersion: '999.0.0' };
+    await writeFile(path.join(tierRoot, 'hooks', 'manifest.json'), JSON.stringify(futureManifest, null, 2));
+    await assert.rejects(resolveTier('pro', tmpRoot), /requires Rune Free >= 999\.0\.0/);
+  });
+
+  test('getFreeVersion reads package.json semver', () => {
+    _resetFreeVersionCache();
+    const v = getFreeVersion();
+    assert.match(v, /^\d+\.\d+\.\d+/);
+  });
+});
+
+describe('Gap 3: actionable missing-manifest error', () => {
+  test('resolveTier error lists both env var and monorepo sibling path', async () => {
+    delete process.env.RUNE_PRO_ROOT;
+    await assert.rejects(resolveTier('pro', tmpRoot), (err) => {
+      assert.match(err.message, /RUNE_PRO_ROOT/);
+      assert.match(err.message, /monorepo sibling/);
+      assert.match(err.message, /Drop --tier pro/);
+      assert.match(err.message, /rune\.dev\/docs\/hooks/);
+      return true;
+    });
+  });
+
+  test('resolveTier error for unknown tier (no env var) still includes sibling + docs hint', async () => {
+    await assert.rejects(resolveTier('unknowntier', tmpRoot), (err) => {
+      assert.match(err.message, /monorepo sibling fallback/);
+      assert.match(err.message, /Drop --tier unknowntier/);
+      assert.match(err.message, /rune\.dev\/docs\/hooks/);
+      return true;
+    });
+  });
+});
+
 describe('regression: Pro+Claude parity', () => {
   test('Pro entries present BEFORE and AFTER migration produce equivalent settings.json shape', async () => {
     await mkdir(path.join(tmpRoot, '.claude'), { recursive: true });

package/compiler/__tests__/hooks-windsurf.test.js

@@ -3,12 +3,14 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
 import * as windsurf from '../adapters/hooks/windsurf.js';
 import { installHooks } from '../commands/hooks/install.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 
-const RUNE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNE_ROOT = path.resolve(__dirname, '..', '..');
 const WF_DIR = '.windsurf/workflows';
 const RULES_DIR = '.windsurf/rules';
 

package/compiler/commands/hooks/tiers.js

@@ -16,9 +16,10 @@
  * third-party) plugs in by shipping a manifest at a known path.
  */
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 /** Known tier env vars. Adding a new tier = add its env var here. */
 export const TIER_ENV_VARS = Object.freeze({
@@ -26,6 +27,56 @@ export const TIER_ENV_VARS = Object.freeze({
   business: 'RUNE_BUSINESS_ROOT',
 });
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Read Free compiler version from the bundled package.json. Cached after first read.
+ * @returns {string} semver string, e.g. "2.12.1"
+ */
+let _freeVersionCache = null;
+export function getFreeVersion() {
+  if (_freeVersionCache) return _freeVersionCache;
+  const pkgPath = path.resolve(__dirname, '..', '..', '..', 'package.json');
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    _freeVersionCache = typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+  } catch {
+    _freeVersionCache = '0.0.0';
+  }
+  return _freeVersionCache;
+}
+
+/** For test/override scenarios — resets the cache. */
+export function _resetFreeVersionCache() {
+  _freeVersionCache = null;
+}
+
+/**
+ * Parse a semver `x.y.z` (ignores pre-release/build) into a tuple. Returns null on malformed input.
+ * @param {string} v
+ * @returns {[number,number,number]|null}
+ */
+export function parseSemver(v) {
+  if (typeof v !== 'string') return null;
+  const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Compare two semver strings. Returns -1, 0, 1 or null if either is malformed.
+ */
+export function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] < pb[i]) return -1;
+    if (pa[i] > pb[i]) return 1;
+  }
+  return 0;
+}
+
 /** Valid event names a manifest entry may declare. */
 const VALID_EVENTS = new Set(['UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'statusLine']);
 
@@ -148,11 +199,23 @@ export function validateManifest(manifest, source = '<memory>') {
     };
   });
 
+  const minFreeVersion =
+    typeof manifest.minFreeVersion === 'string' && manifest.minFreeVersion.length > 0 ? manifest.minFreeVersion : null;
+  if (manifest.minFreeVersion !== undefined && minFreeVersion === null) {
+    throw new Error(`Manifest ${source}: 'minFreeVersion' must be a non-empty string if present`);
+  }
+  if (minFreeVersion && !parseSemver(minFreeVersion)) {
+    throw new Error(
+      `Manifest ${source}: 'minFreeVersion' must be semver x.y.z (got ${JSON.stringify(minFreeVersion)})`,
+    );
+  }
+
   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',
+    minFreeVersion,
     requires: Array.isArray(manifest.requires) ? [...manifest.requires] : [],
     entries,
     overrides: manifest.overrides && typeof manifest.overrides === 'object' ? { ...manifest.overrides } : {},
@@ -160,6 +223,29 @@ export function validateManifest(manifest, source = '<memory>') {
   };
 }
 
+/**
+ * Assert the current Free compiler satisfies a manifest's `minFreeVersion`.
+ * Throws with an actionable upgrade message when the local Free is too old.
+ *
+ * @param {import('./tiers.js').TierManifest} manifest
+ * @param {string} [currentFreeVersion] — defaults to `getFreeVersion()`. Override for tests.
+ */
+export function assertFreeVersionCompat(manifest, currentFreeVersion) {
+  if (!manifest || !manifest.minFreeVersion) return;
+  const current = currentFreeVersion ?? getFreeVersion();
+  const cmp = compareSemver(current, manifest.minFreeVersion);
+  if (cmp === null) {
+    // Malformed input — surface but don't block (defensive).
+    return;
+  }
+  if (cmp < 0) {
+    throw new Error(
+      `Tier '${manifest.tier}' requires Rune Free >= ${manifest.minFreeVersion} but the installed compiler is ${current}. ` +
+        `Upgrade Free first: \`npm i -g @rune-kit/rune@latest\` (or \`npx @rune-kit/rune@latest hooks install --tier ${manifest.tier}\`).`,
+    );
+  }
+}
+
 /**
  * Check whether a manifest's `requires` list is satisfied by current env.
  * Returns { ok, missing }.
@@ -180,16 +266,32 @@ export function checkManifestRequires(manifest) {
 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 envVar = TIER_ENV_VARS[tier];
+    const capitalized = tier.charAt(0).toUpperCase() + tier.slice(1);
+    const siblingPath = path.resolve(projectRoot, '..', capitalized, 'hooks', 'manifest.json');
+    const lines = [`Could not locate '${tier}' tier manifest. Rune looked in:`];
+    if (envVar) {
+      lines.push(`  1. $${envVar}/hooks/manifest.json  (env var — set this if ${capitalized} is installed elsewhere)`);
+      lines.push(`  2. ${siblingPath}  (monorepo sibling fallback)`);
+    } else {
+      lines.push(`  • ${siblingPath}  (monorepo sibling fallback)`);
+    }
+    lines.push('');
+    lines.push(`Fix one of:`);
+    if (envVar) {
+      lines.push(`  • export ${envVar}=/path/to/${capitalized}   # point at your ${tier} install`);
+    }
+    lines.push(`  • Clone ${capitalized} next to Free so the sibling path resolves`);
+    lines.push(`  • Drop --tier ${tier} to install Free-only hooks`);
+    lines.push('');
+    lines.push(`See https://rune.dev/docs/hooks#tiers for details.`);
+    throw new Error(lines.join('\n'));
   }
   const manifest = await loadTierManifest(manifestPath);
   if (manifest.tier !== tier) {
     throw new Error(`Manifest at ${manifestPath} declares tier='${manifest.tier}' but was requested as '${tier}'`);
   }
+  assertFreeVersionCompat(manifest);
   return manifest;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.12.0",
+  "version": "2.12.2",
   "description": "62-skill mesh for AI coding assistants — runtime auto-discipline via native hooks (Claude/Cursor/Windsurf/Antigravity), 5-layer architecture, 215+ connections, multi-platform compiler.",
   "type": "module",
   "bin": {

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

@@ -19,12 +19,14 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { detectInvariants, renderInvariants } from './detect-invariants.js';
 import { applyInvariantsPointer } from './inject-claude-md.js';
 
 const AUTO_HEADER = '## Auto-detected (new)';
 const TEMPLATE_REL_PATH = '../references/invariants-template.md';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 /**
  * Locate the next `## `-level section boundary in `text`, ignoring any `##`
@@ -60,7 +62,7 @@ function findNextSectionOffset(text) {
 }
 
 export async function loadTemplate(templatePath) {
-  const resolved = templatePath ?? path.resolve(import.meta.dirname, TEMPLATE_REL_PATH);
+  const resolved = templatePath ?? path.resolve(__dirname, TEMPLATE_REL_PATH);
   return readFile(resolved, 'utf8');
 }