@lazco/pi-rules 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# pi-rules
+
+Pi extension: load Markdown rules into the agent context, for the whole project or only for matching files.
+
+[![npm](https://img.shields.io/npm/v/@lazco/pi-rules)](https://www.npmjs.com/package/@lazco/pi-rules) [![License](https://img.shields.io/npm/l/@lazco/pi-rules)](LICENSE)
+
+[Installation](#installation) · [Usage](#usage) · [Rule files](#rule-files) · [Frontmatter](#frontmatter) · [Configuration](#configuration) · [Limitations](#limitations)
+
+</div>
+
+`@lazco/pi-rules` is a fork of [`tigorlazuardi/pi-rules`](https://github.com/tigorlazuardi/pi-rules), maintained by Lazco Corporation.
+It reads the same rule files, so you can switch without a change to your rules.
+
+## Highlights
+
+- **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.
+- **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).
+
+## Installation
+
+You need [pi](https://github.com/earendil-works/pi) and Node.js 22.19.0 or later.
+
+```sh
+pi install npm:@lazco/pi-rules
+```
+
+Then run `/reload` in pi.
+To check the install, run `pi list`.
+The list of user packages shows `npm:@lazco/pi-rules`.
+
+If you use `npm:@tigorhutasuhut/pi-rules`, remove it first:
+
+```sh
+pi remove npm:@tigorhutasuhut/pi-rules
+```
+
+If pi loads both packages, every rule loads twice.
+
+## Usage
+
+Create `.pi/rules/project.md` in your project:
+
+```md
+Run the focused tests after you change production code.
+Never commit secrets or build output.
+```
+
+Start pi in the project and send a message.
+Before the first model call, the rule loads, and the chat shows:
+
+```text
+Loaded rules:
+↳ .pi/rules/project.md
+```
+
+Press the expand key on the message to see the full rule text and the files that matched.
+
+### Rules for some files
+
+Add `paths` frontmatter when a rule applies only to part of the project:
+
+```md
+---
+paths:
+  - "src/**/*.ts"
+  - "test/**/*.ts"
+---
+Use strict TypeScript.
+Keep tests next to the behavior they check.
+```
+
+| The agent calls | What happens |
+| --- | --- |
+| `read` on a matching file | The read runs. The rule loads before the next model call. |
+| `edit` or `write` on a matching file | The call stops before it runs. The rule loads, and the agent tries the call again. |
+
+Each rule loads once on the current branch of the conversation.
+pi-rules reads the injected rules from the messages that the model sees, so it stays correct when you:
+
+- go back to an earlier message with `/tree`, or send a message again after you stop an answer,
+- resume a session, run `/reload`, or fork a session,
+- compact the session. The rules that the summary replaced load again when they are needed.
+
+## Rule files
+
+A rule is a Markdown file.
+pi-rules reads every `.md` file in these directories, also in subdirectories:
+
+| Order | Directory | Scope |
+| --- | --- | --- |
+| 1 | `<project>/.pi/rules/` | project |
+| 2 | `<project>/.agents/rules/` | project |
+| 3 | `<project>/.claude/rules/` | project |
+| 4 | `~/.pi/agent/rules/` | user |
+| 5 | `~/.agents/rules/` | user |
+| 6 | `~/.claude/rules/` | user |
+
+`<project>` is the directory where you start pi.
+The file name without `.md` is the rule name.
+When two files have the same rule name, only the file from the first directory in the table loads.
+pi-rules follows symbolic links to files and directories.
+
+`PI_CODING_AGENT_DIR` or `PI_CONFIG_DIR` changes directory 4.
+`CLAUDE_CONFIG_DIR` changes directory 6.
+
+## Frontmatter
+
+All frontmatter fields are optional.
+A file without frontmatter is a rule for every session.
+
+| Field | Value | Effect |
+| --- | --- | --- |
+| `paths` | a glob or a list of globs | The rule loads only for matching files. |
+| `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.
+
+### Tools
+
+Use `events` to load a rule for some tools only:
+
+```md
+---
+paths: "docs/**/*.md"
+events:
+  tool_call: read
+---
+Check the facts in the docs against the code.
+```
+
+This rule loads after a read of a matching file, but not for an edit or a write.
+
+### Skills
+
+Use `skills` to load full pi skills with a rule:
+
+```md
+---
+paths: "src/frontend/**"
+skills:
+  - frontend-design
+---
+Follow the linked frontend workflow.
+```
+
+pi-rules finds the skill by name in the skills that pi found.
+The skill loads even when its frontmatter sets `disable-model-invocation: true`.
+A missing skill shows a warning, and the rule still loads.
+
+## Configuration
+
+A `rules.json` file turns pi-rules off or changes the directory list.
+pi-rules reads the first file that exists:
+
+1. `<project>/.pi/rules.json`
+2. `~/.pi/agent/rules.json`
+
+The two files do not merge.
+
+```json
+{
+  "enabled": true,
+  "sources": [
+    { "scope": "repo", "kind": "pi" },
+    { "scope": "repo", "kind": "agents" },
+    { "scope": "repo", "kind": "claude" },
+    { "scope": "user", "kind": "pi" },
+    { "scope": "user", "kind": "agents" },
+    { "scope": "user", "kind": "claude" }
+  ]
+}
+```
+
+| Field | Default | Effect |
+| --- | --- | --- |
+| `enabled` | `true` | `false` turns off all rules. |
+| `sources` | the six directories above | The directories to read, in order. `scope` is `repo` or `user`. `kind` is `pi`, `agents`, or `claude`. |
+
+To turn off the rules in one project, put `{ "enabled": false, "sources": [] }` in `<project>/.pi/rules.json`.
+An invalid file shows a warning, and no rule loads.
+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.
+- **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
+
+Report bugs and ask questions in [GitHub issues](https://github.com/Lazco-Corporation/pi-rules/issues).
+Pull requests are welcome.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the setup and the tests.
+
+## License
+
+[AGPL-3.0-or-later](LICENSE).
+The code from the original project is under the MIT License. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,34 @@
+# Third-party notices
+
+`@lazco/pi-rules` is a fork of [`tigorlazuardi/pi-rules`](https://github.com/tigorlazuardi/pi-rules).
+The fork is released under `AGPL-3.0-or-later`. See [LICENSE](LICENSE).
+The code that comes from the original project was released under the MIT License below.
+Releases of the original project stay under the MIT License.
+
+## pi-rules
+
+Source: <https://github.com/tigorlazuardi/pi-rules>
+
+```text
+MIT License
+
+Copyright (c) 2026 Tigor Hutasuhut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@lazco/pi-rules",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.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",
+  "author": "Lazco Corporation (拉資科科技有限公司)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lazco-Corporation/pi-rules.git"
+  },
+  "homepage": "https://github.com/Lazco-Corporation/pi-rules#readme",
+  "bugs": {
+    "url": "https://github.com/Lazco-Corporation/pi-rules/issues"
+  },
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "coding-agent",
+    "rules",
+    "claude-code"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.5.2",
+    "@earendil-works/pi-tui": "1.5.2",
+    "@types/node": "^22.20.1",
+    "@types/picomatch": "4.0.2",
+    "typebox": "1.4.6",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test --experimental-strip-types test/*.test.ts",
+    "release": "bash scripts/release.sh"
+  },
+  "dependencies": {
+    "picomatch": "4.0.7",
+    "yaml": "2.9.1"
+  }
+}

package/src/discovery.ts

@@ -0,0 +1,318 @@
+import { createHash } from "node:crypto";
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import os from "node:os";
+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";
+
+const FRONTMATTER_RE = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const RULE_TOOL_NAMES = new Set<RuleToolName>(["read", "edit", "write"]);
+
+const RULE_SOURCE_SCHEMA = Type.Object({
+  scope: Type.Union([Type.Literal("repo"), Type.Literal("user")]),
+  kind: Type.Union([Type.Literal("pi"), Type.Literal("agents"), Type.Literal("claude")]),
+});
+
+const RULE_CONFIG_SCHEMA = Type.Object({
+  enabled: Type.Optional(Type.Boolean()),
+  sources: Type.Array(RULE_SOURCE_SCHEMA),
+});
+
+const RULE_CONFIG_VALIDATOR = Compile(RULE_CONFIG_SCHEMA);
+
+export type RuleSource = Type.Static<typeof RULE_SOURCE_SCHEMA>;
+
+export const DEFAULT_RULE_SOURCES: RuleSource[] = [
+  { scope: "repo", kind: "pi" },
+  { scope: "repo", kind: "agents" },
+  { scope: "repo", kind: "claude" },
+  { scope: "user", kind: "pi" },
+  { scope: "user", kind: "agents" },
+  { scope: "user", kind: "claude" },
+];
+
+interface RuleRoot {
+  directory: string;
+  label: string;
+}
+
+interface DiscoveryOptions {
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  sources?: RuleSource[];
+}
+
+export interface RuleConfigResult {
+  enabled: boolean;
+  sources: RuleSource[];
+  configPath?: string;
+  diagnostic?: RuleDiagnostic;
+}
+
+type ParseResult = { rule: Rule } | { diagnostic: RuleDiagnostic };
+
+export async function loadRuleConfig(cwd: string, options: DiscoveryOptions = {}): Promise<RuleConfigResult> {
+  const home = options.home ?? os.homedir();
+  const env = options.env ?? process.env;
+  const piCodingAgentDirectory = resolvePiCodingAgentDirectory(env, home);
+  const candidates = [path.join(cwd, ".pi", "rules.json"), path.join(piCodingAgentDirectory, "rules.json")];
+
+  for (const configPath of candidates) {
+    let content: string;
+    try {
+      content = await readFile(configPath, "utf8");
+    } catch (error) {
+      const code = getErrorCode(error);
+      if (code === "ENOENT") continue;
+      return invalidConfig(configPath, labelPath(configPath, cwd, home), `unreadable: ${code}`);
+    }
+
+    let value: unknown;
+    try {
+      value = JSON.parse(content);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return invalidConfig(configPath, labelPath(configPath, cwd, home), `invalid JSON: ${message}`);
+    }
+
+    if (!RULE_CONFIG_VALIDATOR.Check(value)) {
+      const [first] = RULE_CONFIG_VALIDATOR.Errors(value);
+      const reason = first ? `${first.instancePath || "/"}: ${first.message}` : "schema validation failed";
+      return invalidConfig(configPath, labelPath(configPath, cwd, home), reason);
+    }
+
+    return {
+      enabled: value.enabled ?? true,
+      sources: value.sources,
+      configPath,
+    };
+  }
+
+  return { enabled: true, sources: DEFAULT_RULE_SOURCES };
+}
+
+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 rules: Rule[] = [];
+  const diagnostics: RuleDiagnostic[] = [];
+  const names = new Set<string>();
+
+  for (const root of roots) {
+    const files = await findMarkdownFiles(root.directory);
+    for (const relativePath of files) {
+      const name = path.basename(relativePath, ".md");
+      if (names.has(name)) continue;
+      names.add(name);
+
+      const sourcePath = path.join(root.directory, ...relativePath.split("/"));
+      const sourceLabel = `${root.label}/${relativePath}`;
+      const parsed = await parseRuleFile(sourcePath, sourceLabel);
+      if ("rule" in parsed) {
+        rules.push(parsed.rule);
+      } else {
+        diagnostics.push(parsed.diagnostic);
+      }
+    }
+  }
+
+  return { rules, diagnostics };
+}
+
+export async function parseRuleFile(sourcePath: string, sourceLabel: string): Promise<ParseResult> {
+  let content: string;
+  try {
+    content = await readFile(sourcePath, "utf8");
+  } catch (error) {
+    const code = getErrorCode(error);
+    return { diagnostic: { sourceLabel, reason: `unreadable: ${code}` } };
+  }
+
+  const frontmatter = content.match(FRONTMATTER_RE);
+  if (!frontmatter) {
+    if (/^\uFEFF?---(?:\r?\n|$)/.test(content)) {
+      return { diagnostic: { sourceLabel, reason: "unclosed frontmatter" } };
+    }
+    const body = content.replace(/^\uFEFF/, "");
+    return { rule: { id: sourcePath, sourcePath, sourceLabel, body, hash: hashBody(body) } };
+  }
+
+  let raw: unknown;
+  try {
+    const document = parseDocument(frontmatter[1] ?? "", { logLevel: "silent" });
+    if (document.errors.length > 0) {
+      return {
+        diagnostic: {
+          sourceLabel,
+          reason: `invalid YAML: ${document.errors[0]?.message ?? "unknown error"}`,
+        },
+      };
+    }
+    raw = document.toJS();
+  } catch (error) {
+    return {
+      diagnostic: {
+        sourceLabel,
+        reason: `invalid YAML: ${error instanceof Error ? error.message : String(error)}`,
+      },
+    };
+  }
+  if (raw !== null && (typeof raw !== "object" || Array.isArray(raw))) {
+    return { diagnostic: { sourceLabel, reason: "frontmatter must be a mapping" } };
+  }
+
+  const record = (raw ?? {}) as Record<string, unknown>;
+  const paths = normalizeStringList(record.paths, "paths", "glob");
+  if (paths && "reason" in paths) {
+    return { diagnostic: { sourceLabel, reason: paths.reason } };
+  }
+  const events = normalizeRuleEvents(record.events);
+  if (events && "reason" in events) {
+    return { diagnostic: { sourceLabel, reason: events.reason } };
+  }
+  const skills = normalizeStringList(record.skills, "skills", "skill name");
+  if (skills && "reason" in skills) {
+    return { diagnostic: { sourceLabel, reason: skills.reason } };
+  }
+
+  const body = content.slice(frontmatter[0].length);
+  const rule: Rule = { id: sourcePath, sourcePath, sourceLabel, body, hash: hashBody(body) };
+  if (paths) rule.paths = paths;
+  if (events) rule.events = events;
+  if (skills) rule.skills = skills;
+  return { rule };
+}
+
+async function findMarkdownFiles(directory: string, ancestors = new Set<string>()): Promise<string[]> {
+  let entries;
+  let resolvedDirectory: string;
+  try {
+    resolvedDirectory = await realpath(directory);
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (getErrorCode(error) === "ENOENT") return [];
+    throw error;
+  }
+
+  // ponytail: track current ancestry only; permits aliases while stopping symlink cycles.
+  if (ancestors.has(resolvedDirectory)) return [];
+  const nextAncestors = new Set(ancestors).add(resolvedDirectory);
+  const files: string[] = [];
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name);
+    let isDirectory = entry.isDirectory();
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try {
+        const target = await stat(entryPath);
+        isDirectory = target.isDirectory();
+        isFile = target.isFile();
+      } catch (error) {
+        if (getErrorCode(error) === "ENOENT" && entry.name.endsWith(".md")) files.push(entry.name);
+        else if (getErrorCode(error) !== "ENOENT") throw error;
+        continue;
+      }
+    }
+    if (isDirectory) {
+      const nested = await findMarkdownFiles(entryPath, nextAncestors);
+      files.push(...nested.map((relativePath) => `${entry.name}/${relativePath}`));
+      continue;
+    }
+    if (isFile && entry.name.endsWith(".md")) files.push(entry.name);
+  }
+  return files;
+}
+
+function resolvePiCodingAgentDirectory(env: NodeJS.ProcessEnv, home: string): string {
+  return env.PI_CODING_AGENT_DIR || path.join(env.PI_CONFIG_DIR || path.join(home, ".pi"), "agent");
+}
+
+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` };
+  }
+
+  if (source.kind === "pi") {
+    const directory = path.join(resolvePiCodingAgentDirectory(env, home), "rules");
+    return { directory, label: labelDirectory(directory, home) };
+  }
+  if (source.kind === "agents") {
+    return { directory: path.join(home, ".agents", "rules"), label: "~/.agents/rules" };
+  }
+
+  const directory = path.join(env.CLAUDE_CONFIG_DIR || path.join(home, ".claude"), "rules");
+  return { directory, label: labelDirectory(directory, home) };
+}
+
+function invalidConfig(configPath: string, sourceLabel: string, reason: string): RuleConfigResult {
+  return { enabled: false, sources: [], configPath, diagnostic: { sourceLabel, reason } };
+}
+
+function labelPath(target: string, cwd: string, home: string): string {
+  const relative = path.relative(cwd, target);
+  if (relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) {
+    return relative.split(path.sep).join("/");
+  }
+  return labelDirectory(target, home);
+}
+
+function normalizeRuleEvents(raw: unknown): RuleEvents | { reason: string } | undefined {
+  if (raw === undefined) return undefined;
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return { reason: "events must be a mapping of Pi event names to filters" };
+  }
+
+  const record = raw as Record<string, unknown>;
+  const unsupported = Object.keys(record).filter((name) => name !== "tool_call");
+  if (unsupported.length > 0) {
+    return { reason: `events contains unsupported Pi event: ${unsupported.join(", ")}` };
+  }
+  const toolNames = normalizeStringList(record.tool_call, "events.tool_call", "tool name");
+  if (!toolNames) return { reason: "events must include tool_call" };
+  if ("reason" in toolNames) return toolNames;
+  if (!toolNames.every((name): name is RuleToolName => RULE_TOOL_NAMES.has(name as RuleToolName))) {
+    return { reason: "events.tool_call supports only read, edit, or write" };
+  }
+  return { tool_call: toolNames };
+}
+
+function normalizeStringList(
+  raw: unknown,
+  field: string,
+  item: string,
+): string[] | { reason: string } | undefined {
+  if (raw === undefined) return undefined;
+  const values = typeof raw === "string" ? [raw] : raw;
+  if (!Array.isArray(values) || !values.every((value) => typeof value === "string")) {
+    return { reason: `${field} must be a string or string list` };
+  }
+  const normalized = values.map((value) => value.trim());
+  if (normalized.length === 0 || normalized.some((value) => value.length === 0)) {
+    return { reason: `${field} must contain at least one non-empty ${item}` };
+  }
+  return [...new Set(normalized)];
+}
+
+function labelDirectory(directory: string, home: string): string {
+  const relative = path.relative(home, directory);
+  if (relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) {
+    return `~/${relative.split(path.sep).join("/")}`;
+  }
+  return directory.split(path.sep).join("/");
+}
+
+function hashBody(body: string): string {
+  return createHash("sha256").update(body).digest("hex").slice(0, 16);
+}
+
+function getErrorCode(error: unknown): string {
+  if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string") {
+    return error.code;
+  }
+  return "EUNKNOWN";
+}