@syv-ai/rulecast 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as Adapter, D as Delivery, a as DetectorRuleInput, b as DetectorRun, M as Match, c as Detector, d as AnyDetector, e as AdapterInput, E as Event } from './types-C8b7hrnG.js';
-export { f as AdapterInstall, C as Cache, g as ChangeSet, h as CheckResult, i as CompiledDetector, j as CompiledRule, k as DeliveredReference, l as DetectorCheck, m as DetectorEvent, n as DetectorRegistry, o as DetectorResult, p as DetectorRule, q as DetectorSettings, r as DetectorWarm, s as EventKind, F as Finding, I as InstallScope, L as LLM_PROVIDERS, t as LlmFinding, u as LlmProvider, v as LlmProviderName, w as LlmRequest, x as LlmSettings, y as LlmUnavailableError, O as Omitted, R as ReferenceMode, z as ResolvedReference, B as RuleScope, S as Severity, T as TouchRule, W as WriteIntent, G as createRegistry, H as defaultDetectorSettings, J as emptyDelivery, K as isDetectorRule } from './types-C8b7hrnG.js';
+import { A as Adapter, e as Delivery, g as DetectorRun, h as DetectorRuleInput, M as Match, i as Detector, j as AnyDetector, k as AdapterInput, E as Event } from './types-D5y_IokF.js';
+export { l as AdapterInstall, m as Cache, n as ChangeSet, b as CheckResult, o as CompiledDetector, a as CompiledRule, p as ContentSource, q as DeliveredReference, s as DetectorCheck, t as DetectorEvent, D as DetectorRegistry, u as DetectorResult, d as DetectorRule, c as DetectorSettings, v as DetectorWarm, w as EventKind, F as Finding, I as InstallScope, x as LLM_PROVIDERS, y as LlmFinding, f as LlmProvider, L as LlmProviderName, z as LlmRequest, B as LlmSettings, G as LlmUnavailableError, O as Omitted, H as ReferenceMode, J as ReferenceSpec, K as RenderOptions, N as ResolvedReference, P as RuleExample, Q as RuleExamples, T as RuleScope, U as Severity, S as Stage, V as TouchRule, W as WriteIntent, X as createRegistry, Y as defaultDetectorSettings, Z as emptyDelivery, _ as isDetectorRule, r as renderAgentText } from './types-D5y_IokF.js';
 import 'zod';
 
 declare const claudeCodeAdapter: Adapter;
@@ -38,17 +38,88 @@ interface BacklogSummary {
 declare function summarise(delivery: Delivery): BacklogSummary;
 declare function renderBacklog(summary: BacklogSummary, options: {
     topFiles: number;
+    note?: boolean;
 }): string;
 
 /** Every agent adapter rulecast ships. */
 declare const ADAPTERS: readonly Adapter[];
 declare function adapterByName(name: string): Adapter | undefined;
 
+/**
+ * A path an external tool reported, made repo-relative with forward slashes.
+ *
+ * Two things a tool does that naive relativisation gets wrong. SARIF requires `uri` to be
+ * percent-encoded, so a `file://` URI has to be decoded rather than sliced. And resolving a path —
+ * Python's `Path.resolve()`, eslint — follows symlinks, so a project under a symlinked root, which
+ * is every macOS temp directory and plenty of real checkouts, comes back as a realpath that does
+ * not sit under `cwd`. Either way the finding would be attributed to a path no rule selected and
+ * silently dropped, so the realpath of the root is tried before giving up.
+ *
+ * `command` and `linter` each carried a byte-identical copy of the root-and-realpath half of this.
+ *
+ * A factory, because the realpath is a filesystem call: a tool that reports thousands of findings
+ * resolves its root once, not once per finding.
+ */
+declare function repoRelativeTo(cwd: string): (file: string) => string;
+/** One path; for many from the same tool, take `repoRelativeTo(cwd)` once. */
+declare function repoRelative(file: string, cwd: string): string;
+
+/**
+ * Whether this error is the clock rather than the rule.
+ *
+ * It decides which of two very different things a detector reports. Rethrowing lets the core record
+ * a timeout, which is logged and tried again at the next verify; swallowing it into
+ * `DetectorResult.errors` is a rule error, which disables the rule for the whole session (§14).
+ *
+ * The signal alone cannot tell the two apart. Its abort timer only runs when the event loop is free,
+ * and synchronous work — `ast-grep` parses in native code that no timeout interrupts — is what keeps
+ * it busy. So the wall clock is the authority, and every detector that catches its own errors has to
+ * ask this rather than `signal.aborted`.
+ */
+declare function pastDeadline(error: unknown, input: Pick<DetectorRun<unknown>, "signal" | "deadlineAt">): boolean;
 /** Turns a per-rule function into a detector run; an error in one rule does not affect the others. */
 declare function perRule<Config>(detect: (rule: DetectorRuleInput<Config>, input: DetectorRun<Config>) => Promise<Match[]>): Detector<Config>["run"];
+/**
+ * Reads each file at most once for the life of the returned function, for a detector that hands
+ * paths to another program and reads the files only to quote them (`{{text}}`, a prompt).
+ *
+ * Not for a detector that declares `guards`: those read only through `DetectorRun.read`, which is
+ * what lets them judge content the agent proposed and that is not on disk (docs/conventions.md).
+ * `linter` and `llm` each carried a byte-identical copy of this.
+ */
+declare function sourceReader(cwd: string): (file: string) => Promise<string | null>;
+
+declare function lineStarts(text: string): number[];
+/** 1-based line and column of a string offset. */
+declare function positionAt(starts: number[], offset: number): {
+    line: number;
+    column: number;
+};
+/** String offset of a 1-based line and column, clamped to a file of `length` characters. */
+declare function offsetAt(starts: number[], line: number, column: number, length: number): number;
+
+/**
+ * Runs a checker and returns what it printed.
+ *
+ * A non-zero exit is not a failure: a linter or a command rule exits non-zero precisely when it
+ * found something, and the output is the answer. What is a failure is a binary that is not there —
+ * reported as `notFound`, which the caller words for its own user — and an error that carries no
+ * output at all, such as a permission failure. An abort is rethrown untouched, so the caller can tell the clock from
+ * the rule (`pastDeadline`).
+ *
+ * `command` and `linter` each carried a copy of this, `maxBuffer` and comment included. `llm`'s CLI
+ * providers do not use it: they write a prompt to stdin, keep stderr and the exit code, and a
+ * missing binary is a whole-run `LlmUnavailableError` there rather than a rule error.
+ */
+declare function runTool(command: string, args: readonly string[], options: {
+    cwd: string;
+    signal: AbortSignal;
+    notFound: string;
+    stdin?: string;
+}): Promise<string>;
 
 /** The running rulecast version. test/core/version.test.ts keeps it equal to package.json. */
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.5.0";
 
 declare const builtinDetectors: readonly AnyDetector[];
 
@@ -107,4 +178,4 @@ interface DetectorFixture {
  */
 declare function detectorContract(detector: AnyDetector, fixture: DetectorFixture): ContractCase[];
 
-export { ADAPTERS, Adapter, type AdapterFixture, AdapterInput, AnyDetector, type BacklogSummary, type ContractCase, Delivery, Detector, type DetectorFixture, DetectorRuleInput, DetectorRun, Event, Match, VERSION, adapterByName, adapterContract, builtinDetectors, claudeCodeAdapter, detectorContract, perRule, renderBacklog, summarise };
+export { ADAPTERS, Adapter, type AdapterFixture, AdapterInput, AnyDetector, type BacklogSummary, type ContractCase, Delivery, Detector, type DetectorFixture, DetectorRuleInput, DetectorRun, Event, Match, VERSION, adapterByName, adapterContract, builtinDetectors, claudeCodeAdapter, detectorContract, lineStarts, offsetAt, pastDeadline, perRule, positionAt, renderBacklog, repoRelative, repoRelativeTo, runTool, sourceReader, summarise };

package/dist/index.js

@@ -5,18 +5,27 @@ import {
   claudeCodeAdapter,
   createRegistry,
   renderBacklog,
+  repoRelative,
+  repoRelativeTo,
+  runTool,
   summarise
-} from "./chunk-KOUHBT7F.js";
+} from "./chunk-MB4F7ZXC.js";
 import {
   LlmUnavailableError,
   VERSION,
   defaultDetectorSettings,
   emptyDelivery,
   isDetectorRule,
+  lineStarts,
   memoryCache,
+  offsetAt,
+  pastDeadline,
   perRule,
-  readSourceFile
-} from "./chunk-HZUATJ53.js";
+  positionAt,
+  readSourceFile,
+  renderAgentText,
+  sourceReader
+} from "./chunk-4XS34SYW.js";
 
 // src/testing/adapter-contract.ts
 import assert from "assert/strict";
@@ -70,7 +79,7 @@ function adapterContract(adapter, fixture) {
           if (!event) continue;
           assert.ok(event.cwd.length > 0, `${name}: event.cwd must not be empty`);
           for (const file of event.files) assert.equal(typeof file, "string", `${name}: files must be strings`);
-          if (event.kind === "prompt" || event.kind === "reset") {
+          if (["prompt", "reset", "start", "shell-before", "shell-after"].includes(event.kind)) {
             assert.deepEqual(event.files, [], `${name}: ${event.kind} carries no files`);
           }
         }
@@ -120,6 +129,16 @@ function adapterContract(adapter, fixture) {
             const twice = install.merge(structuredClone(once.settings), command, 5e3);
             assert.deepEqual(twice.settings, once.settings, "merging twice must change nothing");
             assert.deepEqual(twice.added, [], "merging twice must add nothing");
+            if (twice.updated !== void 0) assert.deepEqual(twice.updated, [], "merging twice must update nothing");
+            const upgraded = install.merge(structuredClone(once.settings), install.command(true), 5e3);
+            assert.deepEqual(upgraded.added, [], "merging another command over installed hooks must add nothing");
+            if (upgraded.updated !== void 0) {
+              assert.deepEqual(
+                [...upgraded.updated].sort(),
+                [...once.added].sort(),
+                "merging another command must report every hook it rewrote"
+              );
+            }
             const removed = install.remove(structuredClone(once.settings));
             assert.deepEqual(removed.settings, original, "remove must return the settings merge was given");
             assert.deepEqual([...removed.removed].sort(), [...once.added].sort(), "remove must name what merge added");
@@ -299,7 +318,16 @@ export {
   detectorContract,
   emptyDelivery,
   isDetectorRule,
+  lineStarts,
+  offsetAt,
+  pastDeadline,
   perRule,
+  positionAt,
+  renderAgentText,
   renderBacklog,
+  repoRelative,
+  repoRelativeTo,
+  runTool,
+  sourceReader,
   summarise
 };

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
-import { n as DetectorRegistry, N as Config, j as CompiledRule, D as Delivery, h as CheckResult, q as DetectorSettings, E as Event, v as LlmProviderName, u as LlmProvider } from './types-C8b7hrnG.js';
-export { P as RuleEntry, Q as Stage } from './types-C8b7hrnG.js';
+import { D as DetectorRegistry, C as Config, a as CompiledRule, b as CheckResult, c as DetectorSettings, d as DetectorRule, M as Match, E as Event, e as Delivery, L as LlmProviderName, f as LlmProvider } from './types-D5y_IokF.js';
+export { R as RuleEntry, S as Stage, r as renderAgentText } from './types-D5y_IokF.js';
 import 'zod';
 
 type Checkout = {
@@ -47,7 +47,7 @@ interface CompileOptions {
 /** The project config and the manifests of its pinned repos → ready rules plus diagnostics (spec §5). */
 declare function compile(options: CompileOptions): Promise<CompiledProject>;
 /** A manifest on its own (validate, the init catalog): references resolve against `dir`. */
-declare function compileManifest(dir: string, registry: DetectorRegistry): Promise<{
+declare function compileManifest(dir: string, registry: DetectorRegistry, file?: string): Promise<{
     rules: CompiledRule[];
     diagnostics: Diagnostic[];
 }>;
@@ -55,11 +55,6 @@ declare function compileManifest(dir: string, registry: DetectorRegistry): Promi
 declare const CONFIG_FILE = ".rulecast-config.yaml";
 declare const MANIFEST_FILE = ".rulecast-rules.yaml";
 
-interface RenderOptions {
-    maxMatchesPerRule: number;
-}
-declare function renderAgentText(delivery: Delivery, options: RenderOptions): string;
-
 interface CheckOptions {
     project: CompiledProject;
     registry: DetectorRegistry;
@@ -89,6 +84,12 @@ declare function cacheHome(env: Env): string;
  */
 declare function projectStateDir(home: string, root: string): string;
 
+interface IgnoredFinding {
+    rule: DetectorRule;
+    match: Match;
+    reason: string;
+}
+
 interface PipelineOptions {
     /** Compiled by the caller: hooks never fetch rule repos, the CLI does (spec §4). */
     project: CompiledProject;
@@ -100,7 +101,7 @@ interface PipelineOptions {
     maxContextChars: number | null;
     /** Recently accessed files the agent re-attaches after compaction (adapter.restoredFiles); reset re-delivers their touch context. */
     restoredFiles?: number;
-    /** Detector kinds to skip entirely (run --no-llm). */
+    /** Detector kinds to skip entirely: the metered ones, for a staged run or --no-llm (commands/run.ts). */
     skipDetectorKinds?: ReadonlySet<string>;
     /** Run only these rules (rulecast run RULE_ID); touch rules are unaffected. */
     onlyRules?: ReadonlySet<string>;
@@ -115,6 +116,8 @@ interface PipelineResult {
     failed: boolean;
     /** Detector kinds whose results were dropped at the edit deadline (§13). */
     deadlineMissed: string[];
+    /** Findings a `rulecast-ignore` comment dropped (core/suppress.ts); absent when nothing was detected. */
+    ignored?: IgnoredFinding[];
 }
 declare function runPipeline(options: PipelineOptions): Promise<PipelineResult>;
 
@@ -133,4 +136,4 @@ declare function resolveModel(model: string, provider: LlmProviderName): string
  */
 declare function providerByName(name: LlmProviderName): LlmProvider;
 
-export { CONFIG_FILE, type Checkout, type CompileOptions, type CompiledProject, Config, type Diagnostic, type Env, type KindCheckResult, MANIFEST_FILE, MODEL_ALIASES, type PipelineOptions, type PipelineResult, type RepoProvider, cacheHome, cachedRepos, checkDetectors, checkableKinds, compile, compileManifest, fetchingRepos, fixedRepo, projectStateDir, providerByName, renderAgentText, resolveModel, runPipeline };
+export { CONFIG_FILE, type Checkout, type CompileOptions, type CompiledProject, Config, type Diagnostic, type Env, type KindCheckResult, MANIFEST_FILE, MODEL_ALIASES, type PipelineOptions, type PipelineResult, type RepoProvider, cacheHome, cachedRepos, checkDetectors, checkableKinds, compile, compileManifest, fetchingRepos, fixedRepo, projectStateDir, providerByName, resolveModel, runPipeline };

package/dist/internal.js

@@ -11,13 +11,13 @@ import {
   fixedRepo,
   projectStateDir,
   runPipeline
-} from "./chunk-7KUPYT35.js";
+} from "./chunk-Y3FXJRZB.js";
 import {
   MODEL_ALIASES,
   providerByName,
   renderAgentText,
   resolveModel
-} from "./chunk-HZUATJ53.js";
+} from "./chunk-4XS34SYW.js";
 export {
   CONFIG_FILE,
   MANIFEST_FILE,

package/dist/{types-C8b7hrnG.d.ts → types-D5y_IokF.d.ts}

@@ -1,6 +1,10 @@
 import { ZodType, ZodTypeDef, z } from 'zod';
 
-type EventKind = "touch" | "edit" | "verify" | "prompt" | "reset" | "guard";
+/**
+ * `start`: the session began or resumed. `shell-before` / `shell-after`: around one call of the
+ * agent's shell tool, whose writes rulecast finds by comparing the working tree (session/tree.ts).
+ */
+type EventKind = "touch" | "edit" | "verify" | "prompt" | "reset" | "guard" | "start" | "shell-before" | "shell-after";
 type DetectorEvent = "edit" | "verify";
 type Severity = "error" | "warning";
 type ReferenceMode = "inject" | "read";
@@ -19,16 +23,35 @@ interface WriteIntent {
         all: boolean;
     };
 }
+/**
+ * Where a run reads the current content of a file from. The working tree for every hook; the index
+ * for `rulecast run` on staged files, so a commit is judged as it will be committed; a commit for
+ * `--to-ref`, so a push is judged as it will be pushed.
+ */
+type ContentSource = {
+    kind: "worktree";
+} | {
+    kind: "index";
+} | {
+    kind: "commit";
+    ref: string;
+};
 interface Event {
     kind: EventKind;
-    /** Repo-relative paths (adapters may give absolute ones; the hook command converts them). Empty for prompt and reset. */
+    /** Repo-relative paths (adapters may give absolute ones; the hook command converts them). Empty for prompt, reset, start and shell events. */
     files: string[];
+    /** shell events: pairs a call's before and after states when the agent's payloads carry an id. */
+    toolUseId?: string;
+    /** shell-after: the command exited non-zero. It may still have written files; an adapter may answer it differently. */
+    failed?: boolean;
     /** guard only: what the agent is about to write to `files[0]`. */
     intent?: WriteIntent;
     /** touch from a read: the whole file was read. */
     completeRead?: boolean;
     /** verify from the CLI: the commit the baseline is read from (the merge base for --from-ref). */
     baseCommit?: string;
+    /** verify from the CLI: where current content is read from. Absent: the working tree. */
+    content?: ContentSource;
     session?: {
         id: string;
         agentId?: string;
@@ -88,6 +111,12 @@ interface DetectorRun<Config> {
      * is not on disk and never will be if the write is refused.
      */
     read(file: string): Promise<string | null>;
+    /**
+     * False when the files are not as they are on disk — a staged run reads the index, `--to-ref` a
+     * commit — and this detector declared `takesContent`: it must read through `read` and hand the
+     * text to its tool under the file's path, never let the tool open the path. Absent: true.
+     */
+    fromDisk?: boolean;
     /** File absent = no baseline, the whole file is new. */
     changes: ReadonlyMap<string, ChangeSet>;
     cache: Cache;
@@ -158,6 +187,40 @@ interface Detector<Config> {
      * not on disk, so ruff, eslint, ast-grep's CLI or a `command` script would judge the old one.
      */
     guards?: boolean;
+    /**
+     * Each file costs money or a third party sees it (§6, Consent). The core never preselects such a
+     * rule in `init`, never runs it as a side effect — no fingerprint run on `touch`, no `doctor` dry
+     * run, no `rulecast test` without a rule id — and budgets the files it is given per event.
+     *
+     * The core asks this rather than a kind name, the way it asks `guards`, so a second metered
+     * detector needs no edit to the core.
+     */
+    metered?: boolean;
+    /** For `init`'s consent line: what one rule of this kind costs and where the file goes. */
+    cost?(config: Config): string;
+    /**
+     * Most files this detector is given in one verify; the most recently edited are kept (§6).
+     * `setting` names the config key that raises it, because a warning that does not name its lever
+     * leaves nobody knowing what to do.
+     */
+    fileBudget?(settings: DetectorSettings): {
+        max: number;
+        setting: string;
+    };
+    /** Added to a verify timeout's warning, when this kind can legitimately need far longer. */
+    timeoutHint?: string;
+    /**
+     * A match is the whole file rather than a range in it, so any write to a matching file is
+     * evidence for `refuse_write`, not only a write that inserts the matched text.
+     */
+    wholeFile?: boolean;
+    /**
+     * This rule's tool can be handed a file's content under its real path (ruff `--stdin-filename`,
+     * a model prompt). When the content is not the working tree, such a rule is run with
+     * `fromDisk: false`; one that cannot is given a scratch copy instead, which configuration keyed
+     * on the file's path no longer matches (spec §12).
+     */
+    takesContent?(config: Config): boolean;
     run(input: DetectorRun<Config>): Promise<DetectorResult>;
     /** Optional: build expensive caches ahead of events (rulecast warm, §13). */
     warm?(input: DetectorWarm<Config>): Promise<void>;
@@ -191,6 +254,7 @@ interface Omitted {
         rule: string;
         count: number;
         files: number;
+        swept?: true;
     }[];
     /** Rules dropped whole, with their findings: only when the floor itself did not fit. */
     rules: number;
@@ -212,6 +276,28 @@ interface Delivery {
     omitted: Omitted;
     /** Absolute path of the untrimmed delivery, written when even the floor did not fit; null when it did. */
     overflowPath: string | null;
+    /** The findings are in files the agent's shell command changed: the title says so. Absent: an edit tool. */
+    via?: "shell";
+    /**
+     * Files with findings that changed outside the agent's tool calls (spec §9, Shell edits): printed
+     * under their own heading, after the agent's own, and never blocking. Set at a stop.
+     */
+    swept?: string[];
+    /**
+     * Findings of `refuse_write` rules in files the agent changed with its shell (spec §9, Shell
+     * edits): the write could not be refused before it happened, so the agent is told to revert it.
+     * `dirtyAtStart`: the file had the user's uncommitted changes, so reverting the whole file is wrong.
+     */
+    refused?: {
+        file: string;
+        rule: string;
+        dirtyAtStart: boolean;
+    }[];
+    /**
+     * For the user, not the agent (spec §9, Oversight): the config changed this session, ignores were
+     * added. Attached after the budget is spent and never part of agent context under a hook adapter.
+     */
+    notices?: string[];
 }
 interface AdapterInput {
     /** The agent's directory; the project root is found from it. */
@@ -232,9 +318,14 @@ interface AdapterInstall {
     }[];
     /** The hook command; local: rulecast is installed in the project's node_modules. */
     command(local: boolean): string;
+    /**
+     * Adds the hooks. `updated` (optional, for adapters that can tell): the adapter's own hooks whose
+     * command differed from `command` and were rewritten — an older install upgraded in place.
+     */
     merge(settings: unknown, command: string, verifyMs: number): {
         settings: unknown;
         added: string[];
+        updated?: string[];
     };
     remove(settings: unknown): {
         settings: unknown;
@@ -308,6 +399,8 @@ declare const overrideSchema: z.ZodObject<{
      */
     scope: z.ZodOptional<z.ZodEnum<["instance", "container"]>>;
     refuse_write: z.ZodOptional<z.ZodBoolean>;
+    /** false: compiled and listed, selected for nothing. The way to switch a catalog rule off without deleting it. */
+    enabled: z.ZodOptional<z.ZodBoolean>;
     detect: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnknown>, Record<string, unknown>, Record<string, unknown>>>;
     message: z.ZodOptional<z.ZodString>;
     context: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
@@ -364,8 +457,8 @@ declare const overrideSchema: z.ZodObject<{
     id: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     id: string;
-    name?: string | undefined;
     message?: string | undefined;
+    name?: string | undefined;
     alias?: string | undefined;
     description?: string | undefined;
     files?: string | undefined;
@@ -378,6 +471,7 @@ declare const overrideSchema: z.ZodObject<{
     severity?: "error" | "warning" | undefined;
     scope?: "instance" | "container" | undefined;
     refuse_write?: boolean | undefined;
+    enabled?: boolean | undefined;
     detect?: Record<string, unknown> | undefined;
     context?: (string | {
         path: string;
@@ -395,8 +489,8 @@ declare const overrideSchema: z.ZodObject<{
     } | undefined;
 }, {
     id: string;
-    name?: string | undefined;
     message?: string | undefined;
+    name?: string | undefined;
     alias?: string | undefined;
     description?: string | undefined;
     files?: string | undefined;
@@ -409,6 +503,7 @@ declare const overrideSchema: z.ZodObject<{
     severity?: "error" | "warning" | undefined;
     scope?: "instance" | "container" | undefined;
     refuse_write?: boolean | undefined;
+    enabled?: boolean | undefined;
     detect?: Record<string, unknown> | undefined;
     context?: (string | {
         path: string;
@@ -671,7 +766,14 @@ interface CompiledRule {
     scope: RuleScope;
     /** Refuse the agent's write when this rule fires on what it is writing (spec §9, Guard). */
     refuseWrite: boolean;
+    /** false: switched off with `enabled: false`; never selected for an event (spec §4). */
+    enabled: boolean;
     stages: Stage[];
+    /** The rule's own `files` and `exclude`, as written, for `rulecast list`; `matches` is what decides. */
+    patterns: {
+        files: string;
+        exclude: string;
+    };
     matches(file: string): boolean;
     detector: CompiledDetector | null;
     message: string | null;
@@ -698,6 +800,23 @@ type TouchRule = CompiledRule & {
 /** Whether this rule runs a detector, as a type guard so the narrowing survives a filter. */
 declare function isDetectorRule(rule: CompiledRule): rule is DetectorRule;
 
+interface RenderOptions {
+    maxMatchesPerRule: number;
+    /**
+     * Print `delivery.notices` (default true). A hook adapter passes false and shows them to the user
+     * itself; `--format agent` serves agents without hooks, where nobody else would see them. Notices
+     * are attached after the budget is spent, so they are never priced: no budgeted delivery has any.
+     */
+    notices?: boolean;
+    /**
+     * Print `delivery.warnings` (default true). Rule and detector problems are the human's to fix; a
+     * hook adapter that can reach the user passes false and shows them there. Not printing them only
+     * ever spends less than the budget reserved for them.
+     */
+    warnings?: boolean;
+}
+declare function renderAgentText(delivery: Delivery, options: RenderOptions): string;
+
 /** What the model is asked to answer with (spec §6). */
 declare const responseSchema: z.ZodObject<{
     findings: z.ZodArray<z.ZodObject<{
@@ -773,4 +892,4 @@ interface LlmProvider {
     }): Promise<LlmAvailability>;
 }
 
-export { type Adapter as A, type RuleScope as B, type Cache as C, type Delivery as D, type Event as E, type Finding as F, createRegistry as G, defaultDetectorSettings as H, type InstallScope as I, emptyDelivery as J, isDetectorRule as K, LLM_PROVIDERS as L, type Match as M, type Config as N, type Omitted as O, type RuleEntry as P, type Stage as Q, type ReferenceMode as R, type Severity as S, type TouchRule as T, type WriteIntent as W, type DetectorRuleInput as a, type DetectorRun as b, type Detector as c, type AnyDetector as d, type AdapterInput as e, type AdapterInstall as f, type ChangeSet as g, type CheckResult as h, type CompiledDetector as i, type CompiledRule as j, type DeliveredReference as k, type DetectorCheck as l, type DetectorEvent as m, type DetectorRegistry as n, type DetectorResult as o, type DetectorRule as p, type DetectorSettings as q, type DetectorWarm as r, type EventKind as s, type LlmFinding as t, type LlmProvider as u, type LlmProviderName as v, type LlmRequest as w, type LlmSettings as x, LlmUnavailableError as y, type ResolvedReference as z };
+export { type Adapter as A, type LlmSettings as B, type Config as C, type DetectorRegistry as D, type Event as E, type Finding as F, LlmUnavailableError as G, type ReferenceMode as H, type InstallScope as I, type ReferenceSpec as J, type RenderOptions as K, type LlmProviderName as L, type Match as M, type ResolvedReference as N, type Omitted as O, type RuleExample as P, type RuleExamples as Q, type RuleEntry as R, type Stage as S, type RuleScope as T, type Severity as U, type TouchRule as V, type WriteIntent as W, createRegistry as X, defaultDetectorSettings as Y, emptyDelivery as Z, isDetectorRule as _, type CompiledRule as a, type CheckResult as b, type DetectorSettings as c, type DetectorRule as d, type Delivery as e, type LlmProvider as f, type DetectorRun as g, type DetectorRuleInput as h, type Detector as i, type AnyDetector as j, type AdapterInput as k, type AdapterInstall as l, type Cache as m, type ChangeSet as n, type CompiledDetector as o, type ContentSource as p, type DeliveredReference as q, renderAgentText as r, type DetectorCheck as s, type DetectorEvent as t, type DetectorResult as u, type DetectorWarm as v, type EventKind as w, LLM_PROVIDERS as x, type LlmFinding as y, type LlmRequest as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syv-ai/rulecast",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Deliver project conventions to coding agents at the moment they matter.",
   "keywords": [
     "claude-code",
@@ -35,7 +35,8 @@
     "./internal": {
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js"
-    }
+    },
+    "./cli": "./dist/cli.js"
   },
   "files": [
     "dist"