@rulemetric/cli 0.1.1 → 0.2.0

package/dist/lib/mirror-writer.d.ts

@@ -0,0 +1,35 @@
+import type { Job } from 'graphile-worker';
+/**
+ * Lifecycle events emitted by graphile-worker for a job.
+ *
+ * - `job:start` — worker has picked up the job and begun execution
+ * - `job:success` — task handler resolved without throwing
+ * - `job:error` — task handler threw, but the job has retries remaining
+ *   (Graphile will requeue automatically; we record the error but keep status)
+ * - `job:failed` — task handler threw and the job has exhausted its attempts
+ */
+export type MirrorEvent = 'job:start' | 'job:success' | 'job:error' | 'job:failed';
+/**
+ * Patch applied to the mirror row that tracks a graphile job's lifecycle.
+ *
+ * `mirrorId` routes the update; the rest are partial fields. `status` is
+ * deliberately omitted on `job:error` so Graphile's retry semantics own
+ * the running/queued state — we only flip to `failed` once attempts are
+ * exhausted.
+ */
+export interface MirrorUpdate {
+    mirrorId: string;
+    status?: 'running' | 'completed' | 'failed';
+    attempts: number;
+    graphileJobId: number;
+    error?: string;
+}
+/**
+ * Pure mapping from a graphile-worker lifecycle event + job to the patch
+ * we apply to the corresponding mirror row.
+ *
+ * Pure: no I/O, no clock reads, no DB writes. The caller is responsible
+ * for executing the resulting update against the mirror table.
+ */
+export declare function jobToMirrorUpdate(event: MirrorEvent, job: Job): MirrorUpdate;
+//# sourceMappingURL=mirror-writer.d.ts.map

package/dist/lib/mirror-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror-writer.d.ts","sourceRoot":"","sources":["../../src/lib/mirror-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,aAAa,GAAG,WAAW,GAAG,YAAY,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,GAAG,YAAY,CAmB5E"}

package/dist/lib/mirror-writer.js

@@ -0,0 +1,27 @@
+/**
+ * Pure mapping from a graphile-worker lifecycle event + job to the patch
+ * we apply to the corresponding mirror row.
+ *
+ * Pure: no I/O, no clock reads, no DB writes. The caller is responsible
+ * for executing the resulting update against the mirror table.
+ */
+export function jobToMirrorUpdate(event, job) {
+    const mirrorId = job.payload.mirrorId;
+    const base = {
+        mirrorId,
+        attempts: job.attempts,
+        graphileJobId: Number(job.id),
+    };
+    switch (event) {
+        case 'job:start':
+            return { ...base, status: 'running' };
+        case 'job:success':
+            return { ...base, status: 'completed' };
+        case 'job:error':
+            // Don't flip status — Graphile will requeue the job for retry.
+            return { ...base, error: job.last_error ?? undefined };
+        case 'job:failed':
+            return { ...base, status: 'failed', error: job.last_error ?? undefined };
+    }
+}
+//# sourceMappingURL=mirror-writer.js.map

package/dist/lib/mirror-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror-writer.js","sourceRoot":"","sources":["../../src/lib/mirror-writer.ts"],"names":[],"mappings":"AA6BA;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAkB,EAAE,GAAQ;IAC5D,MAAM,QAAQ,GAAI,GAAG,CAAC,OAAgC,CAAC,QAAQ,CAAC;IAChE,MAAM,IAAI,GAAiB;QACzB,QAAQ;QACR,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;KAC9B,CAAC;IAEF,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,WAAW;YACd,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACxC,KAAK,aAAa;YAChB,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAC1C,KAAK,WAAW;YACd,+DAA+D;YAC/D,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,UAAU,IAAI,SAAS,EAAE,CAAC;QACzD,KAAK,YAAY;YACf,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,UAAU,IAAI,SAAS,EAAE,CAAC;IAC7E,CAAC;AACH,CAAC"}

package/dist/lib/mirror-writer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mirror-writer.test.d.ts.map

package/dist/lib/mirror-writer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror-writer.test.d.ts","sourceRoot":"","sources":["../../src/lib/mirror-writer.test.ts"],"names":[],"mappings":""}

package/dist/lib/mirror-writer.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { jobToMirrorUpdate } from './mirror-writer.js';
+const baseJob = (overrides = {}) => ({
+    id: 1,
+    task_identifier: 'process_eval',
+    payload: { mirrorId: '11111111-1111-1111-1111-111111111111' },
+    attempts: 0,
+    max_attempts: 3,
+    last_error: null,
+    // ...other Job fields filled with sensible defaults
+    ...overrides,
+});
+describe('jobToMirrorUpdate', () => {
+    it('start event marks running with attempt count', () => {
+        const update = jobToMirrorUpdate('job:start', baseJob({ attempts: 1 }));
+        expect(update).toEqual({
+            mirrorId: '11111111-1111-1111-1111-111111111111',
+            status: 'running',
+            attempts: 1,
+            graphileJobId: 1,
+        });
+    });
+    it('success event marks completed', () => {
+        const update = jobToMirrorUpdate('job:success', baseJob({ attempts: 2 }));
+        expect(update).toMatchObject({ status: 'completed', attempts: 2 });
+    });
+    it('error event records last error but keeps status running (will retry)', () => {
+        const update = jobToMirrorUpdate('job:error', baseJob({ attempts: 1, last_error: 'ECONNRESET' }));
+        expect(update).toMatchObject({ error: 'ECONNRESET', attempts: 1 });
+        expect(update.status).toBeUndefined(); // do not flip status — Graphile will requeue
+    });
+    it('failed event marks failed permanently with final error', () => {
+        const update = jobToMirrorUpdate('job:failed', baseJob({ attempts: 3, last_error: 'fatal' }));
+        expect(update).toEqual({
+            mirrorId: '11111111-1111-1111-1111-111111111111',
+            status: 'failed',
+            attempts: 3,
+            error: 'fatal',
+            graphileJobId: 1,
+        });
+    });
+    it('mirrorId is extracted from payload for routing the update', () => {
+        const update = jobToMirrorUpdate('job:start', baseJob());
+        expect(update.mirrorId).toBe('11111111-1111-1111-1111-111111111111');
+    });
+});
+//# sourceMappingURL=mirror-writer.test.js.map

package/dist/lib/mirror-writer.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror-writer.test.js","sourceRoot":"","sources":["../../src/lib/mirror-writer.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD,MAAM,OAAO,GAAG,CAAC,YAA0B,EAAE,EAAO,EAAE,CAAC,CAAC;IACtD,EAAE,EAAE,CAAC;IACL,eAAe,EAAE,cAAc;IAC/B,OAAO,EAAE,EAAE,QAAQ,EAAE,sCAAsC,EAAE;IAC7D,QAAQ,EAAE,CAAC;IACX,YAAY,EAAE,CAAC;IACf,UAAU,EAAE,IAAI;IAChB,oDAAoD;IACpD,GAAG,SAAS;CACM,CAAA,CAAC;AAErB,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,MAAM,GAAG,iBAAiB,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACxE,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC;YACrB,QAAQ,EAAE,sCAAsC;YAChD,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,CAAC;YACX,aAAa,EAAE,CAAC;SACjB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,MAAM,GAAG,iBAAiB,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1E,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sEAAsE,EAAE,GAAG,EAAE;QAC9E,MAAM,MAAM,GAAG,iBAAiB,CAC9B,WAAW,EACX,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CACnD,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;QACnE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,6CAA6C;IACtF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAChE,MAAM,MAAM,GAAG,iBAAiB,CAC9B,YAAY,EACZ,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAC9C,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC;YACrB,QAAQ,EAAE,sCAAsC;YAChD,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE,CAAC;YACX,KAAK,EAAE,OAAO;YACd,aAAa,EAAE,CAAC;SACjB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,MAAM,GAAG,iBAAiB,CAAC,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;QACzD,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/lib/permanent-job-error.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Sentinel error class for handler outcomes that retry is guaranteed not to
+ * help with — e.g. "no eval cases defined for target", "session has too few
+ * events to analyze". The runner intercepts these in graphile-worker-runner
+ * and tells Graphile to skip remaining attempts (via `permanently_fail_jobs`)
+ * instead of running the same handler N more times against the same data.
+ *
+ * Use ONLY for genuinely deterministic failures. Transient errors (LLM
+ * timeout, network, tool-CLI flakiness) should remain plain Error so Graphile
+ * retries them.
+ */
+export declare class PermanentJobError extends Error {
+    readonly __isPermanentJobError = true;
+    constructor(message: string);
+}
+export declare function isPermanentJobError(err: unknown): err is PermanentJobError;
+//# sourceMappingURL=permanent-job-error.d.ts.map

package/dist/lib/permanent-job-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permanent-job-error.d.ts","sourceRoot":"","sources":["../../src/lib/permanent-job-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,qBAAqB,QAAQ;gBAE1B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,iBAAiB,CAK1E"}

package/dist/lib/permanent-job-error.js

@@ -0,0 +1,23 @@
+/**
+ * Sentinel error class for handler outcomes that retry is guaranteed not to
+ * help with — e.g. "no eval cases defined for target", "session has too few
+ * events to analyze". The runner intercepts these in graphile-worker-runner
+ * and tells Graphile to skip remaining attempts (via `permanently_fail_jobs`)
+ * instead of running the same handler N more times against the same data.
+ *
+ * Use ONLY for genuinely deterministic failures. Transient errors (LLM
+ * timeout, network, tool-CLI flakiness) should remain plain Error so Graphile
+ * retries them.
+ */
+export class PermanentJobError extends Error {
+    __isPermanentJobError = true;
+    constructor(message) {
+        super(message);
+        this.name = 'PermanentJobError';
+    }
+}
+export function isPermanentJobError(err) {
+    return (err instanceof Error &&
+        err.__isPermanentJobError === true);
+}
+//# sourceMappingURL=permanent-job-error.js.map

package/dist/lib/permanent-job-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permanent-job-error.js","sourceRoot":"","sources":["../../src/lib/permanent-job-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,qBAAqB,GAAG,IAAI,CAAC;IAEtC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,CACL,GAAG,YAAY,KAAK;QACnB,GAA2C,CAAC,qBAAqB,KAAK,IAAI,CAC5E,CAAC;AACJ,CAAC"}

package/dist/lib/permanent-job-error.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=permanent-job-error.test.d.ts.map

package/dist/lib/permanent-job-error.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permanent-job-error.test.d.ts","sourceRoot":"","sources":["../../src/lib/permanent-job-error.test.ts"],"names":[],"mappings":""}

package/dist/lib/permanent-job-error.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { PermanentJobError, isPermanentJobError } from './permanent-job-error.js';
+describe('PermanentJobError', () => {
+    it('is an Error subclass with the expected name + message', () => {
+        const err = new PermanentJobError('boom');
+        expect(err).toBeInstanceOf(Error);
+        expect(err.name).toBe('PermanentJobError');
+        expect(err.message).toBe('boom');
+    });
+    it('is detected by isPermanentJobError', () => {
+        expect(isPermanentJobError(new PermanentJobError('x'))).toBe(true);
+    });
+    it('does not match plain errors', () => {
+        expect(isPermanentJobError(new Error('plain'))).toBe(false);
+        expect(isPermanentJobError(new TypeError('typed'))).toBe(false);
+    });
+    it('does not match non-Error values', () => {
+        expect(isPermanentJobError('string')).toBe(false);
+        expect(isPermanentJobError(null)).toBe(false);
+        expect(isPermanentJobError(undefined)).toBe(false);
+        expect(isPermanentJobError({ message: 'plain object' })).toBe(false);
+    });
+    it('still detects subclasses of PermanentJobError', () => {
+        class MyPermanent extends PermanentJobError {
+        }
+        expect(isPermanentJobError(new MyPermanent('x'))).toBe(true);
+    });
+});
+//# sourceMappingURL=permanent-job-error.test.js.map

package/dist/lib/permanent-job-error.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permanent-job-error.test.js","sourceRoot":"","sources":["../../src/lib/permanent-job-error.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAElF,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,MAAM,GAAG,GAAG,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,CAAC,mBAAmB,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACrC,MAAM,CAAC,mBAAmB,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5D,MAAM,CAAC,mBAAmB,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClD,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnD,MAAM,CAAC,mBAAmB,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,WAAY,SAAQ,iBAAiB;SAAG;QAC9C,MAAM,CAAC,mBAAmB,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/lib/version-check.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Fetches latest version from the API in the background and refreshes the
+ * cache if the entry is missing or older than TTL_MS. Never throws.
+ */
+export declare function refreshVersionCacheInBackground(): void;
+/**
+ * Returns a one-line upgrade banner if a newer version is cached, else null.
+ * Designed to be printed to stderr by the CLI's BaseCommand on launch.
+ */
+export declare function getUpgradeBanner(currentVersion: string): string | null;
+//# sourceMappingURL=version-check.d.ts.map

package/dist/lib/version-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.d.ts","sourceRoot":"","sources":["../../src/lib/version-check.ts"],"names":[],"mappings":"AAqEA;;;GAGG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAuBtD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKtE"}

package/dist/lib/version-check.js

@@ -0,0 +1,106 @@
+// CLI version-check banner. Every command kicks off an async fetch to
+// /api/cli/latest-version (cached for an hour) and prints a one-line
+// notice on the next invocation if the cached version is newer than the
+// currently-running CLI.
+//
+// Design notes:
+// - Fire-and-forget: we never block command execution on the network.
+// - Cache: ~/.config/rulemetric/version-check.json, TTL 1h. Stored on disk
+//   so the check survives between CLI invocations (each invocation is a
+//   fresh process — in-memory cache wouldn't help).
+// - "Newer" uses semver-naive numeric comparison split on dots — fine for
+//   our 0.x line; tightening this is a follow-up if/when we adopt semver
+//   pre-releases.
+// - We DO NOT have an `upgrade` command yet; the banner just says "version
+//   X.Y.Z available" and trusts the user to know how they installed.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const CONFIG_DIR = join(homedir(), '.config', 'rulemetric');
+const CACHE_FILE = join(CONFIG_DIR, 'version-check.json');
+const TTL_MS = 60 * 60 * 1000; // 1h
+function readCache() {
+    try {
+        const data = JSON.parse(readFileSync(CACHE_FILE, 'utf-8'));
+        if (typeof data.latest === 'string' && typeof data.fetchedAtMs === 'number') {
+            return data;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(entry) {
+    try {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        writeFileSync(CACHE_FILE, JSON.stringify(entry));
+    }
+    catch {
+        // Best-effort: a write failure just means we'll re-fetch next time.
+    }
+}
+function compareVersions(a, b) {
+    const parse = (v) => v.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const pa = parse(a);
+    const pb = parse(b);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const ai = pa[i] ?? 0;
+        const bi = pb[i] ?? 0;
+        if (ai < bi)
+            return -1;
+        if (ai > bi)
+            return 1;
+    }
+    return 0;
+}
+function getApiUrl() {
+    const env = process.env.RULEMETRIC_API_URL;
+    if (env)
+        return env.replace(/\/$/, '');
+    return 'https://rulemetric.com';
+}
+/**
+ * Fetches latest version from the API in the background and refreshes the
+ * cache if the entry is missing or older than TTL_MS. Never throws.
+ */
+export function refreshVersionCacheInBackground() {
+    const cached = readCache();
+    if (cached && Date.now() - cached.fetchedAtMs < TTL_MS)
+        return;
+    // Fire-and-forget — explicitly catch every failure mode so an unhandled
+    // rejection can never reach the user. AbortController guards against
+    // hanging connections (3s budget).
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3000);
+    globalThis
+        .fetch(`${getApiUrl()}/api/cli/latest-version`, { signal: controller.signal })
+        .then(async (res) => {
+        clearTimeout(timer);
+        if (!res.ok)
+            return;
+        const data = (await res.json());
+        if (typeof data.latest !== 'string')
+            return;
+        writeCache({ latest: data.latest, fetchedAtMs: Date.now() });
+    })
+        .catch(() => {
+        clearTimeout(timer);
+        // Network error, timeout, malformed JSON — silently ignore. Banner
+        // is purely a nicety; we never want it to surface failures.
+    });
+}
+/**
+ * Returns a one-line upgrade banner if a newer version is cached, else null.
+ * Designed to be printed to stderr by the CLI's BaseCommand on launch.
+ */
+export function getUpgradeBanner(currentVersion) {
+    const cached = readCache();
+    if (!cached)
+        return null;
+    if (compareVersions(cached.latest, currentVersion) <= 0)
+        return null;
+    return `RuleMetric ${cached.latest} available — you're on ${currentVersion}.`;
+}
+//# sourceMappingURL=version-check.js.map

package/dist/lib/version-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../src/lib/version-check.ts"],"names":[],"mappings":"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"}