@lazco/pi-rules 0.7.0 → 0.9.0

package/README.md

@@ -17,6 +17,7 @@ It reads the same rule files, so you can switch without a change to your rules.
 
 - **Claude Code compatible.** Reads `.claude/rules/` and `.agents/rules/` next to `.pi/rules/`, so one set of files serves both tools.
 - **Rules for matching files.** A rule with `paths` loads only when the agent reads, edits, or writes a matching file.
+- **User rules for any file.** A rule in your home directory also loads for files outside the project, such as `/tmp/build.sh` or `~/.zshrc`.
 - **Rule before change.** An edit or a write to a matching file waits until the agent has the rule, then the agent tries again.
 - **Linked skills.** A rule can load full pi [skills](#skills) when it loads.
 - **Six sources in one list.** Project and user directories merge by file name, and the first source wins. See [Rule files](#rule-files).
@@ -86,6 +87,9 @@ pi-rules reads the injected rules from the messages that the model sees, so it s
 - resume a session, run `/reload`, or fork a session,
 - compact the session. The rules that the summary replaced load again when they are needed.
 
+When you change a rule file that already loaded, also only its frontmatter, the new version loads before the next model call, marked `(updated)`.
+When you delete it, the model gets a short notice that the rule no longer applies.
+
 ## Rule files
 
 A rule is a Markdown file.
@@ -119,7 +123,19 @@ A file without frontmatter is a rule for every session.
 | `events` | `tool_call: <tool>` or a list of tools | The rule loads only for these tools: `read`, `edit`, `write`. |
 | `skills` | a skill name or a list of names | These skills load with the rule. |
 
-Globs are relative to `<project>`, use `/`, and match dotfiles.
+Globs use `/` and match dotfiles.
+How a glob matches depends on the directory of the rule:
+
+| Rule in | Applies to | Glob |
+| --- | --- | --- |
+| a project directory (1 to 3) | files inside `<project>` | relative to `<project>` |
+| a user directory (4 to 6) | any file | `/…` is an absolute path. `~/…` starts at your home directory. Other globs match the path inside `<project>` or the absolute path. |
+
+For example, a user rule with `paths: "**/*.sh"` loads for `/tmp/build.sh` and for `scripts/build.sh` in any project.
+A user rule with `paths: "~/Projects/shop/**"` loads only for files of that project.
+
+When you start pi in your home directory, `.agents/rules/` and `~/.agents/rules/` are the same directory.
+Its rules then count as user rules.
 
 ### Tools
 
@@ -188,9 +204,8 @@ pi-rules reads `rules.json` when a session starts and after a compaction.
 
 ## Limitations
 
-- **Files outside the project.** A `read`, `edit`, or `write` of a file outside `<project>` does not load a rule, also a user rule.
+- **Project rules of other projects.** A file in another project loads only user rules, not the rules in the directories of that project.
 - **Shell commands.** A file that a `bash` command changes does not load a rule.
-- **Changed rules.** A rule that already loaded does not load again after you change its file, until the next compaction.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazco/pi-rules",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Pi extension: load Markdown rules into the agent context for the whole project or for matching files",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package/src/discovery.ts

@@ -5,7 +5,7 @@ import path from "node:path";
 import Type from "typebox";
 import { Compile } from "typebox/compile";
 import { parseDocument } from "yaml";
-import type { DiscoveryResult, Rule, RuleDiagnostic, RuleEvents, RuleToolName } from "./types.ts";
+import type { DiscoveryResult, Rule, RuleDiagnostic, RuleEvents, RuleScope, RuleToolName } from "./types.ts";
 
 const FRONTMATTER_RE = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 const RULE_TOOL_NAMES = new Set<RuleToolName>(["read", "edit", "write"]);
@@ -36,6 +36,7 @@ export const DEFAULT_RULE_SOURCES: RuleSource[] = [
 interface RuleRoot {
   directory: string;
   label: string;
+  scope: RuleScope;
 }
 
 interface DiscoveryOptions {
@@ -96,7 +97,9 @@ export async function loadRuleConfig(cwd: string, options: DiscoveryOptions = {}
 export async function discoverRules(cwd: string, options: DiscoveryOptions = {}): Promise<DiscoveryResult> {
   const home = options.home ?? os.homedir();
   const env = options.env ?? process.env;
-  const roots = (options.sources ?? DEFAULT_RULE_SOURCES).map((source) => resolveRuleRoot(source, cwd, env, home));
+  const roots = await withoutUserAliases(
+    (options.sources ?? DEFAULT_RULE_SOURCES).map((source) => resolveRuleRoot(source, cwd, env, home)),
+  );
 
   const rules: Rule[] = [];
   const diagnostics: RuleDiagnostic[] = [];
@@ -111,7 +114,7 @@ export async function discoverRules(cwd: string, options: DiscoveryOptions = {})
 
       const sourcePath = path.join(root.directory, ...relativePath.split("/"));
       const sourceLabel = `${root.label}/${relativePath}`;
-      const parsed = await parseRuleFile(sourcePath, sourceLabel);
+      const parsed = await parseRuleFile(sourcePath, sourceLabel, root.scope);
       if ("rule" in parsed) {
         rules.push(parsed.rule);
       } else {
@@ -123,7 +126,7 @@ export async function discoverRules(cwd: string, options: DiscoveryOptions = {})
   return { rules, diagnostics };
 }
 
-export async function parseRuleFile(sourcePath: string, sourceLabel: string): Promise<ParseResult> {
+export async function parseRuleFile(sourcePath: string, sourceLabel: string, scope: RuleScope): Promise<ParseResult> {
   let content: string;
   try {
     content = await readFile(sourcePath, "utf8");
@@ -138,7 +141,7 @@ export async function parseRuleFile(sourcePath: string, sourceLabel: string): Pr
       return { diagnostic: { sourceLabel, reason: "unclosed frontmatter" } };
     }
     const body = content.replace(/^\uFEFF/, "");
-    return { rule: { id: sourcePath, sourcePath, sourceLabel, body, hash: hashBody(body) } };
+    return { rule: { id: sourcePath, sourcePath, sourceLabel, scope, body, hash: hashContent(content) } };
   }
 
   let raw: unknown;
@@ -180,7 +183,7 @@ export async function parseRuleFile(sourcePath: string, sourceLabel: string): Pr
   }
 
   const body = content.slice(frontmatter[0].length);
-  const rule: Rule = { id: sourcePath, sourcePath, sourceLabel, body, hash: hashBody(body) };
+  const rule: Rule = { id: sourcePath, sourcePath, sourceLabel, scope, body, hash: hashContent(content) };
   if (paths) rule.paths = paths;
   if (events) rule.events = events;
   if (skills) rule.skills = skills;
@@ -234,19 +237,39 @@ function resolvePiCodingAgentDirectory(env: NodeJS.ProcessEnv, home: string): st
 
 function resolveRuleRoot(source: RuleSource, cwd: string, env: NodeJS.ProcessEnv, home: string): RuleRoot {
   if (source.scope === "repo") {
-    return { directory: path.join(cwd, `.${source.kind}`, "rules"), label: `.${source.kind}/rules` };
+    return { directory: path.join(cwd, `.${source.kind}`, "rules"), label: `.${source.kind}/rules`, scope: "repo" };
   }
 
   if (source.kind === "pi") {
     const directory = path.join(resolvePiCodingAgentDirectory(env, home), "rules");
-    return { directory, label: labelDirectory(directory, home) };
+    return { directory, label: labelDirectory(directory, home), scope: "user" };
   }
   if (source.kind === "agents") {
-    return { directory: path.join(home, ".agents", "rules"), label: "~/.agents/rules" };
+    return { directory: path.join(home, ".agents", "rules"), label: "~/.agents/rules", scope: "user" };
   }
 
   const directory = path.join(env.CLAUDE_CONFIG_DIR || path.join(home, ".claude"), "rules");
-  return { directory, label: labelDirectory(directory, home) };
+  return { directory, label: labelDirectory(directory, home), scope: "user" };
+}
+
+/**
+ * Drop a project root that is a user root, such as `.agents/rules` when pi starts in the home directory.
+ * Its rules then load once, from the user root, with user scope.
+ */
+async function withoutUserAliases(roots: RuleRoot[]): Promise<RuleRoot[]> {
+  const realDirectories = await Promise.all(roots.map((root) => realDirectory(root.directory)));
+  const userDirectories = new Set(
+    roots.flatMap((root, index) => (root.scope === "user" ? [realDirectories[index]] : [])),
+  );
+  return roots.filter((root, index) => root.scope === "user" || !userDirectories.has(realDirectories[index]));
+}
+
+async function realDirectory(directory: string): Promise<string> {
+  try {
+    return await realpath(directory);
+  } catch {
+    return path.resolve(directory);
+  }
 }
 
 function invalidConfig(configPath: string, sourceLabel: string, reason: string): RuleConfigResult {
@@ -306,8 +329,8 @@ function labelDirectory(directory: string, home: string): string {
   return directory.split(path.sep).join("/");
 }
 
-function hashBody(body: string): string {
-  return createHash("sha256").update(body).digest("hex").slice(0, 16);
+function hashContent(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, 16);
 }
 
 function getErrorCode(error: unknown): string {

package/src/index.ts

@@ -8,9 +8,9 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { DEFAULT_RULE_SOURCES, discoverRules, loadRuleConfig, type RuleSource } from "./discovery.ts";
-import { extractTarget, ruleMatchesTarget, ruleMatchesToolCallEvent } from "./matching.ts";
+import { extractTarget, ruleAppliesToTarget, ruleMatchesToolCallEvent, targetLabel } from "./matching.ts";
 import { addInjection, collectInjectedState, CUSTOM_MESSAGE_TYPE, type InjectedState } from "./state.ts";
-import type { PendingRule, Rule, RuleInjectionDetails } from "./types.ts";
+import type { DueRule, PendingRule, RemovedRule, Rule, RuleInjectionDetails } from "./types.ts";
 
 export { CUSTOM_MESSAGE_TYPE };
 
@@ -38,9 +38,19 @@ export function makeExtension() {
 
     pi.registerMessageRenderer<RuleInjectionDetails>(CUSTOM_MESSAGE_TYPE, (message, { expanded }, theme) => {
       const details = message.details;
-      const sourceLines = (details?.sources ?? ["(unknown)"]).map((source) => `↳ ${source}`).join("\n");
+      const updated = new Set(details?.updated ?? []);
+      const sourceLines = (details?.sources ?? ["(unknown)"])
+        .map((source) => `↳ ${source}${updated.has(source) ? " (updated)" : ""}`)
+        .join("\n");
       const skillLines = (details?.skills ?? []).map((skill) => `↳ ${skill}`).join("\n");
-      const summary = `Loaded rules:\n${sourceLines}${skillLines ? `\nLoaded skills:\n${skillLines}` : ""}`;
+      const removedLines = (details?.removed ?? []).map((rule) => `↳ ${rule.label}`).join("\n");
+      const summary = [
+        sourceLines ? `Loaded rules:\n${sourceLines}` : "",
+        skillLines ? `Loaded skills:\n${skillLines}` : "",
+        removedLines ? `Removed rules:\n${removedLines}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n");
       if (!expanded) {
         return new Text(theme.fg("muted", summary), 0, 0);
       }
@@ -48,15 +58,12 @@ export function makeExtension() {
       const targetLines = details?.sources
         .map((source) => {
           const targets = details.targets[source] ?? [];
-          return targets.length > 0 ? `${source} → ${targets.join(", ")}` : `${source} → unconditional`;
+          if (targets.length > 0) return `${source} → ${targets.join(", ")}`;
+          return `${source} → ${updated.has(source) ? "updated" : "unconditional"}`;
         })
         .join("\n");
       const content = typeof message.content === "string" ? message.content : JSON.stringify(message.content, null, 2);
-      return new Text(
-        `${theme.fg("accent", "Loaded rules:")}\n${theme.fg("muted", sourceLines)}\n\n${theme.fg("dim", targetLines ?? "")}\n\n${content}`,
-        0,
-        0,
-      );
+      return new Text(`${theme.fg("accent", summary)}\n\n${theme.fg("dim", targetLines ?? "")}\n\n${content}`, 0, 0);
     });
 
     const reloadConfig = async (cwd: string): Promise<void> => {
@@ -95,20 +102,42 @@ export function makeExtension() {
       return withInFlight(cachedBranch.state);
     };
 
-    // Takes the matches of this turn and adds every unconditional rule that the model does not have.
-    const takeDueRules = (state: InjectedState): PendingRule[] => {
-      const due = [...pendingRules.values()].filter((entry) => !state.rules.has(entry.rule.id));
+    /**
+     * Takes the matches of this turn, and adds every unconditional rule that the model does not have,
+     * every rule whose file changed after the model got it, and every rule whose file is gone.
+     */
+    const takeDueRules = (state: InjectedState): { due: DueRule[]; removed: RemovedRule[] } => {
+      // A rule file can change between the tool call and the end of the turn, so take the newest version.
+      const current = new Map(rules.map((rule) => [rule.id, rule]));
+      const due: DueRule[] = [];
+      for (const entry of pendingRules.values()) {
+        const rule = current.get(entry.rule.id);
+        if (rule && !state.rules.has(rule.id)) due.push({ rule, targets: entry.targets, updated: false });
+      }
       pendingRules.clear();
       for (const rule of rules) {
-        if (isScoped(rule) || state.rules.has(rule.id)) continue;
-        if (!due.some((entry) => entry.rule.id === rule.id)) due.push({ rule, targets: new Set<string>() });
+        if (due.some((entry) => entry.rule.id === rule.id)) continue;
+        const known = state.rules.get(rule.id);
+        if (known) {
+          if (known.hash !== rule.hash) due.push({ rule, targets: new Set<string>(), updated: true });
+        } else if (!isScoped(rule)) {
+          due.push({ rule, targets: new Set<string>(), updated: false });
+        }
       }
-      return due;
+      const discovered = new Set(rules.map((rule) => rule.id));
+      const removed = [...state.rules]
+        .filter(([id]) => !discovered.has(id))
+        .map(([id, known]) => ({ id, label: known.label }));
+      return { due, removed };
     };
 
-    const buildInjection = async (entries: PendingRule[], state: InjectedState): Promise<RuleInjection> => {
-      const skillBlocks = await loadSkillBlocks(entries, availableSkills, state.skills, reportWarning);
-      return createInjection(entries, skillBlocks);
+    const buildInjection = async (
+      { due, removed }: { due: DueRule[]; removed: RemovedRule[] },
+      state: InjectedState,
+    ): Promise<RuleInjection | undefined> => {
+      if (due.length === 0 && removed.length === 0) return undefined;
+      const skillBlocks = await loadSkillBlocks(due, availableSkills, state.skills, reportWarning);
+      return createInjection(due, skillBlocks, removed);
     };
 
     pi.on("session_start", async (_event, ctx) => {
@@ -133,9 +162,9 @@ export function makeExtension() {
       if (!config.enabled) return;
       rules = await reloadRules(ctx.cwd);
       const state = branchState(ctx);
-      const due = takeDueRules(state);
-      if (due.length === 0) return;
-      return { message: await buildInjection(due, state) };
+      const injection = await buildInjection(takeDueRules(state), state);
+      if (!injection) return;
+      return { message: injection };
     });
 
     pi.on("tool_call", async (event, ctx) => {
@@ -145,17 +174,18 @@ export function makeExtension() {
       rules = await reloadRules(ctx.cwd);
       const state = branchState(ctx);
 
+      const label = targetLabel(target);
       let shouldBlock = false;
       for (const rule of rules) {
         if (state.rules.has(rule.id)) continue;
-        if (rule.paths && !ruleMatchesTarget(rule, target)) continue;
+        if (!ruleAppliesToTarget(rule, target)) continue;
         if (!ruleMatchesToolCallEvent(rule, event.toolName)) continue;
         if (event.toolName !== "read") shouldBlock = true;
         const pending = pendingRules.get(rule.id);
         if (pending) {
-          if (isScoped(rule)) pending.targets.add(target);
+          if (isScoped(rule)) pending.targets.add(label);
         } else {
-          pendingRules.set(rule.id, { rule, targets: new Set(isScoped(rule) ? [target] : []) });
+          pendingRules.set(rule.id, { rule, targets: new Set(isScoped(rule) ? [label] : []) });
         }
       }
       if (!shouldBlock) return;
@@ -172,9 +202,8 @@ export function makeExtension() {
       rules = await reloadRules(ctx.cwd);
       // The preview already holds the entries that earlier handlers proposed for this boundary.
       const state = withInFlight(collectInjectedState(event.context.contextEntries, event.context.pendingMessages));
-      const due = takeDueRules(state);
-      if (due.length === 0) return;
-      const injection = await buildInjection(due, state);
+      const injection = await buildInjection(takeDueRules(state), state);
+      if (!injection) return;
       return { entries: [...event.entries, { type: "custom_message", ...injection }] };
     });
 
@@ -188,9 +217,8 @@ export function makeExtension() {
       rules = await reloadRules(ctx.cwd);
       // A compaction that retries the turn makes a model call before any turn boundary, so restore the rules now.
       const state = branchState(ctx);
-      const due = takeDueRules(state);
-      if (due.length === 0) return;
-      const injection = await buildInjection(due, state);
+      const injection = await buildInjection(takeDueRules(state), state);
+      if (!injection) return;
       inFlight.set(injection.details.injectionId, injection.details);
       pi.sendMessage(injection);
     });
@@ -207,23 +235,34 @@ interface SkillBlock {
   content: string;
 }
 
-export function createInjection(entries: PendingRule[], skillBlocks: SkillBlock[] = []): RuleInjection {
+export function createInjection(
+  entries: Array<PendingRule & { updated?: boolean }>,
+  skillBlocks: SkillBlock[] = [],
+  removed: RemovedRule[] = [],
+): RuleInjection {
   const sorted = [...entries].sort(comparePendingRules);
   const sources = sorted.map((entry) => entry.rule.sourceLabel);
   const targets = Object.fromEntries(sorted.map((entry) => [entry.rule.sourceLabel, [...entry.targets].sort()]));
-  const ruleBody = sorted
-    .map((entry) => `## Rule: ${entry.rule.sourceLabel}\n\n${entry.rule.body}`)
-    .join("\n\n---\n\n");
-  const skillBody = skillBlocks.map((skill) => skill.content).join("\n\n");
+  const blocks = [
+    ...sorted.map((entry) =>
+      entry.updated
+        ? `## Rule: ${entry.rule.sourceLabel} (updated)\n\nThis version replaces the earlier version of this rule.\n\n${entry.rule.body}`
+        : `## Rule: ${entry.rule.sourceLabel}\n\n${entry.rule.body}`,
+    ),
+    ...removed.map((rule) => `## Rule removed: ${rule.label}\n\nThis rule no longer applies. Stop following its earlier version.`),
+    ...skillBlocks.map((skill) => skill.content),
+  ];
 
   return {
     customType: CUSTOM_MESSAGE_TYPE,
-    content: skillBody ? `${ruleBody}\n\n---\n\n${skillBody}` : ruleBody,
+    content: blocks.join("\n\n---\n\n"),
     display: true,
     details: {
       injectionId: randomUUID(),
-      rules: sorted.map((entry) => ({ id: entry.rule.id, hash: entry.rule.hash })),
+      rules: sorted.map((entry) => ({ id: entry.rule.id, hash: entry.rule.hash, label: entry.rule.sourceLabel })),
+      removed,
       sources,
+      updated: sorted.filter((entry) => entry.updated).map((entry) => entry.rule.sourceLabel),
       targets,
       skills: skillBlocks.map((skill) => skill.name),
     },

package/src/matching.ts

@@ -1,41 +1,77 @@
+import os from "node:os";
 import path from "node:path";
 import picomatch from "picomatch";
-import type { ToolCallEvent, ToolResultEvent } from "@earendil-works/pi-coding-agent";
+import type { ToolCallEvent } from "@earendil-works/pi-coding-agent";
 import type { Rule } from "./types.ts";
 
 const FILE_TOOLS = new Set(["read", "edit", "write"]);
 
-export function extractTarget(event: ToolCallEvent | ToolResultEvent, cwd: string): string | undefined {
-  if (("isError" in event && event.isError) || !FILE_TOOLS.has(event.toolName)) return undefined;
+/** A file that a tool call reads or changes. */
+export interface ToolTarget {
+  /** Absolute path with `/` separators. */
+  absolutePath: string;
+  /** Path relative to the working directory, only when the file is inside it. */
+  relativePath?: string;
+}
+
+export function extractTarget(event: ToolCallEvent, cwd: string, home = os.homedir()): ToolTarget | undefined {
+  if (!FILE_TOOLS.has(event.toolName)) return undefined;
   const rawPath = (event.input as { path?: unknown }).path;
   if (typeof rawPath !== "string" || rawPath.trim().length === 0) return undefined;
-
   const withoutAt = rawPath.startsWith("@") ? rawPath.slice(1) : rawPath;
-  const absolutePath = path.resolve(cwd, withoutAt);
+  return resolveTarget(withoutAt, cwd, home);
+}
+
+export function resolveTarget(rawPath: string, cwd: string, home = os.homedir()): ToolTarget {
+  const expanded = rawPath === "~" || rawPath.startsWith("~/") ? path.join(home, rawPath.slice(1)) : rawPath;
+  const absolutePath = path.resolve(cwd, expanded);
   const relativePath = path.relative(cwd, absolutePath);
-  if (
-    relativePath.length === 0 ||
-    relativePath === ".." ||
-    relativePath.startsWith(`..${path.sep}`) ||
-    path.isAbsolute(relativePath)
-  ) {
-    return undefined;
-  }
-  return toPosixPath(relativePath);
+  const inside =
+    relativePath.length > 0 &&
+    relativePath !== ".." &&
+    !relativePath.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relativePath);
+  return inside
+    ? { absolutePath: toPosixPath(absolutePath), relativePath: toPosixPath(relativePath) }
+    : { absolutePath: toPosixPath(absolutePath) };
 }
 
-export function ruleMatchesTarget(rule: Rule, target: string): boolean {
-  if (!rule.paths) return false;
-  const patterns = rule.paths.map(normalizePattern);
-  return picomatch.isMatch(target, patterns, { dot: true });
+/** The text that the injection message shows for a target. */
+export function targetLabel(target: ToolTarget): string {
+  return target.relativePath ?? target.absolutePath;
+}
+
+/**
+ * A project rule applies only inside the working directory, and its globs are relative to it.
+ * A user rule applies to any file. Its globs can be absolute (`/…`), start at the home directory (`~/…`),
+ * or be relative: a relative glob matches the path inside the working directory or the absolute path.
+ */
+export function ruleAppliesToTarget(rule: Rule, target: ToolTarget, home = os.homedir()): boolean {
+  if (rule.scope === "repo" && target.relativePath === undefined) return false;
+  if (!rule.paths) return true;
+  return rule.paths.some((pattern) => patternMatches(pattern, rule, target, home));
 }
 
 export function ruleMatchesToolCallEvent(rule: Rule, toolName: string): boolean {
   return !rule.events || rule.events.tool_call.some((name) => name === toolName);
 }
 
-function normalizePattern(pattern: string): string {
-  return toPosixPath(pattern).replace(/^\.\//, "");
+function patternMatches(pattern: string, rule: Rule, target: ToolTarget, home: string): boolean {
+  const normalized = toPosixPath(pattern).replace(/^\.\//, "");
+  if (rule.scope === "repo") return isMatch(target.relativePath ?? "", normalized);
+  if (normalized.startsWith("/")) return isMatch(target.absolutePath, normalized);
+  if (normalized.startsWith("~/")) {
+    // Compare in `~/` form, so glob characters in the home path cannot change the pattern.
+    const homePrefix = `${toPosixPath(home)}/`;
+    if (!target.absolutePath.startsWith(homePrefix)) return false;
+    return isMatch(`~/${target.absolutePath.slice(homePrefix.length)}`, normalized);
+  }
+  if (target.relativePath !== undefined && isMatch(target.relativePath, normalized)) return true;
+  return isMatch(target.absolutePath.replace(/^\//, ""), normalized);
+}
+
+function isMatch(candidate: string, pattern: string): boolean {
+  return picomatch.isMatch(candidate, pattern, { dot: true });
 }
 
 function toPosixPath(value: string): string {

package/src/state.ts

@@ -1,12 +1,11 @@
 import type { ProjectedSessionEntry } from "@earendil-works/pi-coding-agent";
-import type { RuleInjectionDetails } from "./types.ts";
 
 export const CUSTOM_MESSAGE_TYPE = "pi-rules-injection";
 
 /** The rules and skills that the model can see now, read from the injection messages in its context. */
 export interface InjectedState {
-  /** Rule id to the hash of the body that the model has. */
-  rules: Map<string, string>;
+  /** Rule id to the version of the rule that the model has. */
+  rules: Map<string, { hash: string; label: string }>;
   skills: Set<string>;
   injectionIds: Set<string>;
 }
@@ -42,7 +41,11 @@ export function collectInjectedState(
 export function addInjection(state: InjectedState, details: unknown): void {
   if (!isInjectionDetails(details)) return;
   state.injectionIds.add(details.injectionId);
-  for (const rule of details.rules) state.rules.set(rule.id, rule.hash);
+  details.rules.forEach((rule, index) => {
+    // 0.7 and 0.8 stored the label only in `sources`, in the same order as `rules`.
+    state.rules.set(rule.id, { hash: rule.hash, label: rule.label ?? details.sources[index] ?? rule.id });
+  });
+  for (const rule of details.removed ?? []) state.rules.delete(rule.id);
   for (const skill of details.skills) state.skills.add(skill);
 }
 
@@ -57,13 +60,24 @@ function isInjectionMessage(message: unknown): message is { details: unknown } {
 }
 
 // Injections written by older versions have no rule list. They are ignored, so those rules load once more.
-function isInjectionDetails(details: unknown): details is RuleInjectionDetails {
+interface StoredInjectionDetails {
+  injectionId: string;
+  rules: Array<{ id: string; hash: string; label?: string }>;
+  removed?: Array<{ id: string }>;
+  sources: string[];
+  skills: string[];
+}
+
+function isInjectionDetails(details: unknown): details is StoredInjectionDetails {
   if (typeof details !== "object" || details === null) return false;
-  const candidate = details as Partial<RuleInjectionDetails>;
+  const candidate = details as Partial<StoredInjectionDetails>;
   return (
     typeof candidate.injectionId === "string" &&
     Array.isArray(candidate.rules) &&
     candidate.rules.every((rule) => typeof rule?.id === "string" && typeof rule.hash === "string") &&
+    (candidate.removed === undefined ||
+      (Array.isArray(candidate.removed) && candidate.removed.every((rule) => typeof rule?.id === "string"))) &&
+    Array.isArray(candidate.sources) &&
     Array.isArray(candidate.skills)
   );
 }

package/src/types.ts

@@ -1,5 +1,8 @@
 export type RuleToolName = "read" | "edit" | "write";
 
+/** `repo` rules come from the project and apply inside it. `user` rules come from the home directory and apply to any file. */
+export type RuleScope = "repo" | "user";
+
 export interface RuleEvents {
   tool_call: RuleToolName[];
 }
@@ -8,8 +11,9 @@ export interface Rule {
   id: string;
   sourcePath: string;
   sourceLabel: string;
+  scope: RuleScope;
   body: string;
-  /** Hash of the body, so a changed rule file can be told apart from the copy the model already has. */
+  /** Hash of the whole file, so a changed rule can be told apart from the version that the model has. */
   hash: string;
   paths?: string[];
   events?: RuleEvents;
@@ -29,16 +33,31 @@ export interface DiscoveryResult {
 export interface InjectedRule {
   id: string;
   hash: string;
+  label: string;
+}
+
+export interface RemovedRule {
+  id: string;
+  label: string;
 }
 
 export interface RuleInjectionDetails {
   injectionId: string;
+  /** Rules that this message loads, also new versions of rules that the model has. */
   rules: InjectedRule[];
+  /** Rules whose file is gone. The message tells the model to stop following them. */
+  removed: RemovedRule[];
   sources: string[];
+  /** The labels in `sources` that replace an earlier version. */
+  updated: string[];
   targets: Record<string, string[]>;
   skills: string[];
 }
 
+export interface DueRule extends PendingRule {
+  updated: boolean;
+}
+
 export interface PendingRule {
   rule: Rule;
   targets: Set<string>;