@lazco/pi-rules 0.7.0 → 0.8.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).
@@ -119,7 +120,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,7 +201,7 @@ 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazco/pi-rules",
-  "version": "0.7.0",
+  "version": "0.8.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: hashBody(body) } };
   }
 
   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: hashBody(body) };
   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 {

package/src/index.ts

@@ -8,7 +8,7 @@ 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";
 
@@ -145,17 +145,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;

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/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,6 +11,7 @@ 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: string;