@lazco/pi-rules 0.0.0-stage → 0.8.0

package/src/index.ts

@@ -0,0 +1,272 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import {
+  stripFrontmatter,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type Skill,
+} 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, 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";
+
+export { CUSTOM_MESSAGE_TYPE };
+
+export interface RuleInjection {
+  customType: typeof CUSTOM_MESSAGE_TYPE;
+  content: string;
+  display: true;
+  details: RuleInjectionDetails;
+}
+
+export function makeExtension() {
+  return (pi: ExtensionAPI): void => {
+    let config: { enabled: boolean; sources: RuleSource[] } = { enabled: true, sources: DEFAULT_RULE_SOURCES };
+    let rules: Rule[] = [];
+    let reportWarning = (message: string): void => {
+      process.stderr.write(`${message}\n`);
+    };
+    const availableSkills = new Map<string, Skill>();
+    // Matches from the tool calls of the current turn. They load when the turn ends.
+    const pendingRules = new Map<string, PendingRule>();
+    // Injections sent with pi.sendMessage that pi has not written to the session yet.
+    const inFlight = new Map<string, RuleInjectionDetails>();
+    // Building the projection walks the whole branch, and parallel tool calls share one leaf.
+    let cachedBranch: { leafId: string | null; state: InjectedState } | undefined;
+
+    pi.registerMessageRenderer<RuleInjectionDetails>(CUSTOM_MESSAGE_TYPE, (message, { expanded }, theme) => {
+      const details = message.details;
+      const sourceLines = (details?.sources ?? ["(unknown)"]).map((source) => `↳ ${source}`).join("\n");
+      const skillLines = (details?.skills ?? []).map((skill) => `↳ ${skill}`).join("\n");
+      const summary = `Loaded rules:\n${sourceLines}${skillLines ? `\nLoaded skills:\n${skillLines}` : ""}`;
+      if (!expanded) {
+        return new Text(theme.fg("muted", summary), 0, 0);
+      }
+
+      const targetLines = details?.sources
+        .map((source) => {
+          const targets = details.targets[source] ?? [];
+          return targets.length > 0 ? `${source} → ${targets.join(", ")}` : `${source} → 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,
+      );
+    });
+
+    const reloadConfig = async (cwd: string): Promise<void> => {
+      const result = await loadRuleConfig(cwd);
+      config = { enabled: result.enabled, sources: result.sources };
+      if (result.diagnostic) {
+        reportWarning(`[pi-rules] invalid config ${result.diagnostic.sourceLabel}: ${result.diagnostic.reason}`);
+      }
+    };
+
+    const reloadRules = async (cwd: string): Promise<Rule[]> => {
+      const discovery = await discoverRules(cwd, { sources: config.sources });
+      for (const diagnostic of discovery.diagnostics) {
+        reportWarning(`[pi-rules] skipped ${diagnostic.sourceLabel}: ${diagnostic.reason}`);
+      }
+      return discovery.rules;
+    };
+
+    const withInFlight = (base: InjectedState): InjectedState => {
+      for (const injectionId of base.injectionIds) inFlight.delete(injectionId);
+      if (inFlight.size === 0) return base;
+      const merged: InjectedState = {
+        rules: new Map(base.rules),
+        skills: new Set(base.skills),
+        injectionIds: new Set(base.injectionIds),
+      };
+      for (const details of inFlight.values()) addInjection(merged, details);
+      return merged;
+    };
+
+    const branchState = (ctx: ExtensionContext): InjectedState => {
+      const leafId = ctx.sessionManager.getLeafId();
+      if (cachedBranch?.leafId !== leafId) {
+        cachedBranch = { leafId, state: collectInjectedState(ctx.sessionManager.buildSessionProjection().entries) };
+      }
+      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));
+      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>() });
+      }
+      return due;
+    };
+
+    const buildInjection = async (entries: PendingRule[], state: InjectedState): Promise<RuleInjection> => {
+      const skillBlocks = await loadSkillBlocks(entries, availableSkills, state.skills, reportWarning);
+      return createInjection(entries, skillBlocks);
+    };
+
+    pi.on("session_start", async (_event, ctx) => {
+      reportWarning = ctx.hasUI
+        ? (message) => ctx.ui.notify(message, "warning")
+        : (message) => process.stderr.write(`${message}\n`);
+      await reloadConfig(ctx.cwd);
+      rules = config.enabled ? await reloadRules(ctx.cwd) : [];
+      availableSkills.clear();
+      pendingRules.clear();
+      inFlight.clear();
+      cachedBranch = undefined;
+    });
+
+    pi.on("session_tree", () => {
+      pendingRules.clear();
+    });
+
+    pi.on("before_agent_start", async (event, ctx) => {
+      availableSkills.clear();
+      for (const skill of event.systemPromptOptions?.skills ?? []) availableSkills.set(skill.name, skill);
+      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) };
+    });
+
+    pi.on("tool_call", async (event, ctx) => {
+      if (!config.enabled) return;
+      const target = extractTarget(event, ctx.cwd);
+      if (!target) return;
+      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 (!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(label);
+        } else {
+          pendingRules.set(rule.id, { rule, targets: new Set(isScoped(rule) ? [label] : []) });
+        }
+      }
+      if (!shouldBlock) return;
+
+      // Reads can finish before the next model call. Edits and writes pause, because their arguments are already final.
+      return { block: true, reason: `[pi-rules] Tool \`${event.toolName}\` paused so Pi can load matching rules. Review them, adjust the change if needed, then retry.` };
+    });
+
+    pi.on("turn_end", async (event, ctx) => {
+      if (!config.enabled) {
+        pendingRules.clear();
+        return;
+      }
+      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);
+      return { entries: [...event.entries, { type: "custom_message", ...injection }] };
+    });
+
+    pi.on("session_compact", async (_event, ctx) => {
+      pendingRules.clear();
+      await reloadConfig(ctx.cwd);
+      if (!config.enabled) {
+        rules = [];
+        return;
+      }
+      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);
+      inFlight.set(injection.details.injectionId, injection.details);
+      pi.sendMessage(injection);
+    });
+
+    pi.on("agent_settled", () => {
+      // By now pi has written every queued message or dropped it.
+      inFlight.clear();
+    });
+  };
+}
+
+interface SkillBlock {
+  name: string;
+  content: string;
+}
+
+export function createInjection(entries: PendingRule[], skillBlocks: SkillBlock[] = []): 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");
+
+  return {
+    customType: CUSTOM_MESSAGE_TYPE,
+    content: skillBody ? `${ruleBody}\n\n---\n\n${skillBody}` : ruleBody,
+    display: true,
+    details: {
+      injectionId: randomUUID(),
+      rules: sorted.map((entry) => ({ id: entry.rule.id, hash: entry.rule.hash })),
+      sources,
+      targets,
+      skills: skillBlocks.map((skill) => skill.name),
+    },
+  };
+}
+
+async function loadSkillBlocks(
+  entries: PendingRule[],
+  availableSkills: Map<string, Skill>,
+  injectedSkills: ReadonlySet<string>,
+  reportWarning: (message: string) => void,
+): Promise<SkillBlock[]> {
+  const names = [...new Set(entries.flatMap((entry) => entry.rule.skills ?? []))]
+    .filter((name) => !injectedSkills.has(name))
+    .sort();
+  const blocks: SkillBlock[] = [];
+  for (const name of names) {
+    const skill = availableSkills.get(name);
+    if (!skill) {
+      reportWarning(`[pi-rules] skill not found: ${name}`);
+      continue;
+    }
+    try {
+      const body = stripFrontmatter(await readFile(skill.filePath, "utf8")).trim();
+      blocks.push({
+        name,
+        content: `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`,
+      });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      reportWarning(`[pi-rules] failed to load skill ${name}: ${reason}`);
+    }
+  }
+  return blocks;
+}
+
+function isScoped(rule: Rule): boolean {
+  return Boolean(rule.paths || rule.events);
+}
+
+function comparePendingRules(left: PendingRule, right: PendingRule): number {
+  return left.rule.sourceLabel.localeCompare(right.rule.sourceLabel);
+}
+
+export default makeExtension();

package/src/matching.ts

@@ -0,0 +1,79 @@
+import os from "node:os";
+import path from "node:path";
+import picomatch from "picomatch";
+import type { ToolCallEvent } from "@earendil-works/pi-coding-agent";
+import type { Rule } from "./types.ts";
+
+const FILE_TOOLS = new Set(["read", "edit", "write"]);
+
+/** 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;
+  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);
+  const inside =
+    relativePath.length > 0 &&
+    relativePath !== ".." &&
+    !relativePath.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relativePath);
+  return inside
+    ? { absolutePath: toPosixPath(absolutePath), relativePath: toPosixPath(relativePath) }
+    : { absolutePath: toPosixPath(absolutePath) };
+}
+
+/** 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 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 {
+  return value.split(path.sep).join("/");
+}

package/src/state.ts

@@ -0,0 +1,69 @@
+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>;
+  skills: Set<string>;
+  injectionIds: Set<string>;
+}
+
+export function emptyInjectedState(): InjectedState {
+  return { rules: new Map(), skills: new Set(), injectionIds: new Set() };
+}
+
+/**
+ * Collect the injections that reach the model.
+ * `contextEntries` must be the compaction-aware projection of the current branch,
+ * so injections on other branches, before a compaction, or removed by a context edit do not count.
+ * `pendingMessages` are messages that pi queued for the next model call but has not written yet.
+ */
+export function collectInjectedState(
+  contextEntries: readonly ProjectedSessionEntry[],
+  pendingMessages: readonly unknown[] = [],
+): InjectedState {
+  const state = emptyInjectedState();
+  for (const entry of contextEntries) {
+    if (entry.messages.length === 0) continue;
+    const source = entry.sourceEntry;
+    if (source.type !== "custom_message" || source.customType !== CUSTOM_MESSAGE_TYPE) continue;
+    addInjection(state, source.details);
+  }
+  for (const message of pendingMessages) {
+    if (!isInjectionMessage(message)) continue;
+    addInjection(state, message.details);
+  }
+  return state;
+}
+
+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);
+  for (const skill of details.skills) state.skills.add(skill);
+}
+
+function isInjectionMessage(message: unknown): message is { details: unknown } {
+  return (
+    typeof message === "object" &&
+    message !== null &&
+    "customType" in message &&
+    message.customType === CUSTOM_MESSAGE_TYPE &&
+    "details" in message
+  );
+}
+
+// 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 {
+  if (typeof details !== "object" || details === null) return false;
+  const candidate = details as Partial<RuleInjectionDetails>;
+  return (
+    typeof candidate.injectionId === "string" &&
+    Array.isArray(candidate.rules) &&
+    candidate.rules.every((rule) => typeof rule?.id === "string" && typeof rule.hash === "string") &&
+    Array.isArray(candidate.skills)
+  );
+}

package/src/types.ts

@@ -0,0 +1,49 @@
+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[];
+}
+
+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;
+  paths?: string[];
+  events?: RuleEvents;
+  skills?: string[];
+}
+
+export interface RuleDiagnostic {
+  sourceLabel: string;
+  reason: string;
+}
+
+export interface DiscoveryResult {
+  rules: Rule[];
+  diagnostics: RuleDiagnostic[];
+}
+
+export interface InjectedRule {
+  id: string;
+  hash: string;
+}
+
+export interface RuleInjectionDetails {
+  injectionId: string;
+  rules: InjectedRule[];
+  sources: string[];
+  targets: Record<string, string[]>;
+  skills: string[];
+}
+
+export interface PendingRule {
+  rule: Rule;
+  targets: Set<string>;
+}