rulereceipt 0.1.43 → 0.1.45

package/dist/cli.js

@@ -21,11 +21,13 @@ import { runHook } from "./hook.js";
 import { runGuard } from "./guard.js";
 import { runJudgmentChecks } from "./checks/judgmentChecks.js";
 import { generateReport, generateMarkdownReport } from "./report/generateReport.js";
+import { gateOffer, hookIsInstalled } from "./report/gateOffer.js";
 import { generateHtmlReport } from "./report/generateHtmlReport.js";
 import { verifySessionHash } from "./verifyHash.js";
 import { saveEmailConfig, loadEmailConfig, detectSmtpHost, isValidEmail } from "./emailConfig.js";
 import { sendReportEmail } from "./sendReport.js";
 import { appendHistory, readHistorySince } from "./history.js";
+import { maybeShowWhatsNew } from "./whatsNew.js";
 import { generateDigest } from "./digest.js";
 import { enableSchedule, disableSchedule, scheduleStatus } from "./schedule.js";
 import { findSplitBrainConflicts } from "./checks/splitBrain.js";
@@ -259,6 +261,16 @@ async function runCheck(opts) {
     const meta = { sessionFilePath, ruleCount: results.length };
     const reportText = markdown ? generateMarkdownReport(results, meta) : generateReport(results, meta);
     console.log(reportText);
+    // Shown only to someone who has just read their own broken rules, and only
+    // if they have not already wired it up. See report/gateOffer.ts.
+    if (!markdown) {
+        const offer = gateOffer({
+            failures: results.filter((r) => r.status === "FAIL").length,
+            hookInstalled: hookIsInstalled(cwd),
+        });
+        if (offer)
+            console.log(`\n${offer}`);
+    }
     // Written before --share/--email so that a failure to send something
     // never costs the user the local artifact they explicitly asked for.
     if (html !== false) {
@@ -308,6 +320,12 @@ async function runCheck(opts) {
         console.log(`\n(${stale.length} saved correction${stale.length === 1 ? "" : "s"} no longer match any rule in this project — the rule was probably reworded. Run \`rulereceipt rules --list\` to see them.)`);
     }
     appendHistory(results, sessionFilePath);
+    // A once-per-update footer so a returning user sees the tool improved and
+    // comes back. Offline (notes ship in the package), fails open, and never
+    // on --markdown (that output is meant to be pasted into a PR/Slack).
+    if (!markdown) {
+        maybeShowWhatsNew(pkg.version);
+    }
     if (share) {
         await shareResults(results);
     }

package/dist/report/gateOffer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Is a RuleReceipt hook already wired into this project or this machine?
+ *
+ * Read-only, and deliberately forgiving: an unreadable or malformed settings
+ * file means "assume not installed" rather than an error. A missing settings
+ * file is the normal case, not a problem.
+ */
+export declare function hookIsInstalled(cwd: string): boolean;
+/**
+ * The line offering enforcement, or null when it should not be shown.
+ *
+ * The site describes the Stop hook to someone deciding whether to adopt the
+ * tool at all. This speaks to someone who has already run it and is looking
+ * at rules that were broken — which is the moment the offer is a consequence
+ * of what they just read rather than an advertisement.
+ *
+ * Three conditions, and each is a way of not nagging:
+ *
+ *   - Only when something actually failed. On a clean report there is
+ *     nothing to enforce and the line would be a pitch.
+ *   - Never when the hook is already installed. Telling someone to do what
+ *     they have already done is how a tool gets muted.
+ *   - One line, no config block. A terminal report is not documentation, and
+ *     pasting JSON into it would bury the findings it sits under.
+ */
+export declare function gateOffer(state: {
+    failures: number;
+    hookInstalled: boolean;
+}): string | null;

package/dist/report/gateOffer.js

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Is a RuleReceipt hook already wired into this project or this machine?
+ *
+ * Read-only, and deliberately forgiving: an unreadable or malformed settings
+ * file means "assume not installed" rather than an error. A missing settings
+ * file is the normal case, not a problem.
+ */
+export function hookIsInstalled(cwd) {
+    const candidates = [
+        join(cwd, ".claude", "settings.json"),
+        join(cwd, ".claude", "settings.local.json"),
+        join(homedir(), ".claude", "settings.json"),
+    ];
+    for (const path of candidates) {
+        if (!existsSync(path))
+            continue;
+        try {
+            // Matched as text rather than by walking the hook schema: the shape of
+            // that config has changed before, and a rename of one field should not
+            // make this start nagging someone who already installed it.
+            if (/rulereceipt\s+(hook|guard)/.test(readFileSync(path, "utf-8")))
+                return true;
+        }
+        catch {
+            // unreadable settings file — treat as not installed
+        }
+    }
+    return false;
+}
+/**
+ * The line offering enforcement, or null when it should not be shown.
+ *
+ * The site describes the Stop hook to someone deciding whether to adopt the
+ * tool at all. This speaks to someone who has already run it and is looking
+ * at rules that were broken — which is the moment the offer is a consequence
+ * of what they just read rather than an advertisement.
+ *
+ * Three conditions, and each is a way of not nagging:
+ *
+ *   - Only when something actually failed. On a clean report there is
+ *     nothing to enforce and the line would be a pitch.
+ *   - Never when the hook is already installed. Telling someone to do what
+ *     they have already done is how a tool gets muted.
+ *   - One line, no config block. A terminal report is not documentation, and
+ *     pasting JSON into it would bury the findings it sits under.
+ */
+export function gateOffer(state) {
+    if (state.failures === 0)
+        return null;
+    if (state.hookInstalled)
+        return null;
+    const n = state.failures;
+    return (`This report is after the fact. \`rulereceipt hook\` runs as a Claude Code Stop hook and\n` +
+        `refuses to let a session end on ${n === 1 ? "a broken rule" : "a broken rule"} — see the README for the four lines to add.`);
+}

package/dist/whatsNew.d.ts

@@ -0,0 +1,41 @@
+export interface Release {
+    version: string;
+    highlights: string[];
+}
+/**
+ * User-facing release highlights, newest first.
+ *
+ * This is NOT the internal CHANGELOG (developer/business-facing, never
+ * shipped). It is the short, plain "here is what got better" note a user
+ * sees once, the first time they run a new version. Add ONE entry at the
+ * top on each release: what changed, in a sentence, honest, no marketing.
+ *
+ * The whole point: someone who bounced off an early version sees the tool
+ * is improving and comes back. So keep it truthful — a highlight that
+ * overstates is the exact failure this tool exists to catch.
+ */
+export declare const RELEASES: Release[];
+export declare function readLastSeen(): string | null;
+export declare function writeLastSeen(version: string): void;
+/**
+ * Numeric dotted-version compare: <0 if a<b, 0 if equal, >0 if a>b.
+ * Numeric per segment, so 0.1.9 < 0.1.10 (not lexical). Junk gives 0, which
+ * makes the caller show nothing rather than guess.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Releases strictly newer than lastSeen and no newer than current, newest
+ * first. A null lastSeen (first run ever) yields nothing on purpose: a
+ * first-timer should see their report, not a changelog.
+ */
+export declare function highlightsBetween(lastSeen: string | null, current: string, releases?: Release[]): Release[];
+export declare function renderWhatsNew(releases: Release[], current: string): string;
+/**
+ * Prints the "what's new" note once per new version, then records the
+ * current version so it never repeats for that version.
+ *
+ * Fails open, always: any error here must never affect the report the user
+ * actually ran for, and there is no network call — the notes ship inside
+ * the package, so the tool stays true to "nothing leaves your machine".
+ */
+export declare function maybeShowWhatsNew(current: string, log?: (s: string) => void): void;

package/dist/whatsNew.js

@@ -0,0 +1,112 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * User-facing release highlights, newest first.
+ *
+ * This is NOT the internal CHANGELOG (developer/business-facing, never
+ * shipped). It is the short, plain "here is what got better" note a user
+ * sees once, the first time they run a new version. Add ONE entry at the
+ * top on each release: what changed, in a sentence, honest, no marketing.
+ *
+ * The whole point: someone who bounced off an early version sees the tool
+ * is improving and comes back. So keep it truthful — a highlight that
+ * overstates is the exact failure this tool exists to catch.
+ */
+export const RELEASES = [
+    { version: "0.1.45", highlights: ["The tool now shows what's improved since you last ran it, like this note."] },
+    { version: "0.1.44", highlights: ["The report now offers to install enforcement, but only when a rule was actually broken."] },
+    { version: "0.1.43", highlights: ["New check: a claim to have read or verified something, with nothing in the session behind it."] },
+    { version: "0.1.41", highlights: ["Emoji rules are checked properly now (Unicode properties, not a hand-written list)."] },
+    { version: "0.1.39", highlights: ["You can mark which clause in a rule is the actual prohibition, so only that blocks."] },
+    { version: "0.1.36", highlights: ["Enforcement arrives: the tool can act on a broken rule with a hook, not just report it."] },
+];
+function stateDir() {
+    return join(homedir(), ".rulereceipt");
+}
+function lastSeenPath() {
+    return join(stateDir(), "last-seen-version");
+}
+export function readLastSeen() {
+    try {
+        const v = readFileSync(lastSeenPath(), "utf-8").trim();
+        return v.length > 0 ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeLastSeen(version) {
+    try {
+        const dir = stateDir();
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(lastSeenPath(), version, "utf-8");
+    }
+    catch {
+        // best-effort; a run that cannot persist this just shows the note again
+    }
+}
+/**
+ * Numeric dotted-version compare: <0 if a<b, 0 if equal, >0 if a>b.
+ * Numeric per segment, so 0.1.9 < 0.1.10 (not lexical). Junk gives 0, which
+ * makes the caller show nothing rather than guess.
+ */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10));
+    const pb = b.split(".").map((n) => parseInt(n, 10));
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (Number.isNaN(x) || Number.isNaN(y))
+            return 0;
+        if (x !== y)
+            return x - y;
+    }
+    return 0;
+}
+/**
+ * Releases strictly newer than lastSeen and no newer than current, newest
+ * first. A null lastSeen (first run ever) yields nothing on purpose: a
+ * first-timer should see their report, not a changelog.
+ */
+export function highlightsBetween(lastSeen, current, releases = RELEASES) {
+    if (!lastSeen)
+        return [];
+    return releases.filter((r) => compareVersions(r.version, lastSeen) > 0 && compareVersions(r.version, current) <= 0);
+}
+export function renderWhatsNew(releases, current) {
+    const lines = [];
+    lines.push(`\n✨ What's new since you last ran rulereceipt (you're on v${current}):`);
+    for (const r of releases) {
+        for (const h of r.highlights) {
+            lines.push(`  • v${r.version}  ${h}`);
+        }
+    }
+    lines.push(`\nThis note shows once per update. To stay current: npx rulereceipt@latest`);
+    return lines.join("\n");
+}
+/**
+ * Prints the "what's new" note once per new version, then records the
+ * current version so it never repeats for that version.
+ *
+ * Fails open, always: any error here must never affect the report the user
+ * actually ran for, and there is no network call — the notes ship inside
+ * the package, so the tool stays true to "nothing leaves your machine".
+ */
+export function maybeShowWhatsNew(current, log = console.log) {
+    try {
+        const lastSeen = readLastSeen();
+        const news = highlightsBetween(lastSeen, current, RELEASES);
+        if (news.length > 0)
+            log(renderWhatsNew(news, current));
+        // Record current even on the first run and even when nothing showed, so
+        // the next update is measured from here.
+        if (lastSeen !== current)
+            writeLastSeen(current);
+    }
+    catch {
+        // never let a footer break the run
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",
@@ -46,7 +46,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@anthropic-ai/sdk": "~0.32.1",
+    "@anthropic-ai/sdk": "~0.126.0",
     "commander": "~15.0.0",
     "nodemailer": "~10.0.1"
   },
@@ -57,6 +57,6 @@
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.68.0",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   }
 }