@wahack/pi-coding-agent 15.11.0

package/src/discovery/at-imports.ts

@@ -0,0 +1,273 @@
+/**
+ * @-import expansion for context files (AGENTS.md / CLAUDE.md / GEMINI.md / …).
+ *
+ * Other coding agents (Claude Code, Goose, Cline, …) treat `@path/to/file`
+ * references inside their markdown memory files as inline includes. omp
+ * loads the same files in their native shape, so this module performs the
+ * same expansion before content lands in the system prompt.
+ *
+ * Semantics mirror Claude Code's documented behavior:
+ * - `@` must sit at start of line or after whitespace (so `git@github.com`
+ *   and `user@example.com` are not treated as imports).
+ * - Relative paths resolve against the importing file's directory, not the
+ *   working directory.
+ * - `~/...` resolves to the user's home directory.
+ * - Imports inside fenced code blocks (` ``` ` / `~~~`) and inline code
+ *   spans (`` `…` ``) are preserved verbatim so technical examples like
+ *   `npm install @types/node` survive intact.
+ * - Recursive imports are followed up to {@link MAX_AT_IMPORT_DEPTH} hops;
+ *   cycles are broken silently.
+ * - When the referenced file cannot be read, the original `@token` is
+ *   left untouched and a debug log is emitted.
+ *
+ * @see https://docs.claude.com/en/docs/claude-code/memory#import-additional-files
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import { logger } from "@oh-my-pi/pi-utils";
+import { readFile } from "../capability/fs";
+
+/** Maximum number of recursive `@`-import hops. Matches Claude Code's documented cap. */
+export const MAX_AT_IMPORT_DEPTH = 5;
+
+/**
+ * Matches a candidate `@import` token: a leading boundary (start-of-string
+ * or single whitespace char) and a token whose first character is path-like.
+ *
+ * The boundary character is captured separately so the slice arithmetic in
+ * {@link expandLine} aligns with the `@` position, not the whitespace.
+ */
+const AT_IMPORT_REGEX = /(^|[ \t])@([./~A-Za-z0-9_-][^\s]*)/g;
+
+/**
+ * Trailing characters stripped from a captured path token: sentence-ending
+ * punctuation, closing brackets, quotes. A lone trailing period is treated
+ * as sentence grammar (e.g. `See @AGENTS.md.`) — legitimate file extensions
+ * still match because the stripped set is anchored at the very end of the
+ * token, so `@AGENTS.md` keeps the `.md` (the `d` is not in the set).
+ */
+const TRAILING_PUNCT = /[.,;:!?)\]}"']+$/;
+
+export interface ExpandAtImportsOptions {
+	/** Maximum hop depth (default: {@link MAX_AT_IMPORT_DEPTH}). */
+	maxDepth?: number;
+	/** Override the home directory used to resolve `~/...` (default: `os.homedir()`). */
+	home?: string;
+}
+
+/**
+ * Expand `@path/to/file` references in `content` against `filePath`'s directory.
+ *
+ * Returns the expanded text. When no imports match, the original string is
+ * returned unchanged.
+ */
+export async function expandAtImports(
+	content: string,
+	filePath: string,
+	options: ExpandAtImportsOptions = {},
+): Promise<string> {
+	const maxDepth = options.maxDepth ?? MAX_AT_IMPORT_DEPTH;
+	const home = options.home ?? os.homedir();
+	const absoluteSource = path.resolve(filePath);
+	const visited = new Set<string>([absoluteSource]);
+	return await expand(content, path.dirname(absoluteSource), 0, maxDepth, home, visited);
+}
+
+async function expand(
+	content: string,
+	baseDir: string,
+	depth: number,
+	maxDepth: number,
+	home: string,
+	visited: Set<string>,
+): Promise<string> {
+	if (depth >= maxDepth) return content;
+
+	const segments = splitMarkdownSegments(content);
+	const out: string[] = [];
+	for (const segment of segments) {
+		if (segment.kind === "code") {
+			out.push(segment.text);
+			continue;
+		}
+		out.push(await expandTextSegment(segment.text, baseDir, depth, maxDepth, home, visited));
+	}
+	return out.join("");
+}
+
+async function expandTextSegment(
+	text: string,
+	baseDir: string,
+	depth: number,
+	maxDepth: number,
+	home: string,
+	visited: Set<string>,
+): Promise<string> {
+	const lines = text.split("\n");
+	for (let i = 0; i < lines.length; i++) {
+		lines[i] = await expandLine(lines[i], baseDir, depth, maxDepth, home, visited);
+	}
+	return lines.join("\n");
+}
+
+async function expandLine(
+	line: string,
+	baseDir: string,
+	depth: number,
+	maxDepth: number,
+	home: string,
+	visited: Set<string>,
+): Promise<string> {
+	if (!line.includes("@")) return line;
+
+	const matches: Array<{ start: number; end: number; importPath: string }> = [];
+	for (const m of line.matchAll(AT_IMPORT_REGEX)) {
+		const matchIndex = m.index ?? 0;
+		const leading = m[1];
+		const rawToken = m[2];
+		const atPos = matchIndex + leading.length;
+		if (isInsideInlineCode(line, atPos)) continue;
+
+		const trimmedToken = rawToken.replace(TRAILING_PUNCT, "");
+		if (trimmedToken.length === 0) continue;
+
+		matches.push({
+			start: atPos,
+			end: atPos + 1 + trimmedToken.length,
+			importPath: trimmedToken,
+		});
+	}
+
+	if (matches.length === 0) return line;
+
+	const parts: string[] = [];
+	let cursor = 0;
+	for (const m of matches) {
+		parts.push(line.slice(cursor, m.start));
+		const expanded = await resolveAndExpand(m.importPath, baseDir, depth, maxDepth, home, visited);
+		parts.push(expanded ?? line.slice(m.start, m.end));
+		cursor = m.end;
+	}
+	parts.push(line.slice(cursor));
+	return parts.join("");
+}
+
+async function resolveAndExpand(
+	importPath: string,
+	baseDir: string,
+	depth: number,
+	maxDepth: number,
+	home: string,
+	visited: Set<string>,
+): Promise<string | null> {
+	const resolved = resolveImportPath(importPath, baseDir, home);
+	if (visited.has(resolved)) {
+		logger.debug("@-import: skipping cyclic include", { path: resolved });
+		return null;
+	}
+
+	const content = await readFile(resolved);
+	if (content === null) {
+		logger.debug("@-import: file not found", { path: resolved });
+		return null;
+	}
+
+	// Visited is shared across the whole expansion tree to break cycles,
+	// even cycles that span multiple importing files.
+	visited.add(resolved);
+	return await expand(content, path.dirname(resolved), depth + 1, maxDepth, home, visited);
+}
+
+function resolveImportPath(importPath: string, baseDir: string, home: string): string {
+	if (importPath === "~") return path.resolve(home);
+	if (importPath.startsWith("~/")) return path.resolve(home, importPath.slice(2));
+	if (path.isAbsolute(importPath)) return path.resolve(importPath);
+	return path.resolve(baseDir, importPath);
+}
+
+interface MarkdownSegment {
+	kind: "text" | "code";
+	text: string;
+}
+
+/**
+ * Split markdown into alternating text/code segments by tracking fenced
+ * code blocks. Inline code spans are handled per-line by {@link isInsideInlineCode}.
+ *
+ * A fence is recognized as a line whose first non-whitespace run is three or
+ * more backticks (or tildes). The closing fence must use the same character
+ * with at least as many marks as the opener.
+ */
+function splitMarkdownSegments(content: string): MarkdownSegment[] {
+	const segments: MarkdownSegment[] = [];
+	const lines = content.split("\n");
+	let buffer: string[] = [];
+	let bufferKind: MarkdownSegment["kind"] = "text";
+	let fenceChar = "";
+	let fenceLen = 0;
+
+	const flush = (): void => {
+		if (buffer.length === 0) return;
+		segments.push({ kind: bufferKind, text: buffer.join("") });
+		buffer = [];
+	};
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const isLast = i === lines.length - 1;
+		// Re-attach each line's trailing newline so adjacent segments
+		// concatenate without losing the boundary `\n`.
+		const lineText = isLast ? line : `${line}\n`;
+		const fence = matchFence(line);
+
+		if (fence && bufferKind === "text") {
+			flush();
+			bufferKind = "code";
+			buffer.push(lineText);
+			fenceChar = fence.char;
+			fenceLen = fence.len;
+		} else if (fence && bufferKind === "code" && fence.char === fenceChar && fence.len >= fenceLen) {
+			buffer.push(lineText);
+			flush();
+			bufferKind = "text";
+			fenceChar = "";
+			fenceLen = 0;
+		} else {
+			buffer.push(lineText);
+		}
+
+		if (isLast) flush();
+	}
+	return segments;
+}
+
+function matchFence(line: string): { char: string; len: number } | null {
+	let i = 0;
+	while (i < line.length && (line[i] === " " || line[i] === "\t")) i++;
+	const char = line[i];
+	if (char !== "`" && char !== "~") return null;
+	let len = 0;
+	while (i + len < line.length && line[i + len] === char) len++;
+	if (len < 3) return null;
+	return { char, len };
+}
+
+/**
+ * Returns `true` when `position` falls inside an unclosed inline-code span on
+ * this line. Implemented as a backtick-parity scan so it handles repeated
+ * delimiters like `` `` literal ` backtick `` `` correctly enough for the
+ * "@-imports inside `code` should not expand" case.
+ */
+function isInsideInlineCode(line: string, position: number): boolean {
+	let inSpan = false;
+	let i = 0;
+	while (i < position && i < line.length) {
+		if (line[i] === "`") {
+			while (i < line.length && line[i] === "`") i++;
+			inSpan = !inSpan;
+		} else {
+			i++;
+		}
+	}
+	return inSpan;
+}

package/src/discovery/builtin-defaults.ts

@@ -0,0 +1,39 @@
+/**
+ * Builtin Defaults Provider
+ *
+ * Ships a curated set of default rules (mostly TTSR conventions) embedded into
+ * the binary. Registered at the lowest priority so any user/project/tool rule
+ * with the same `name` overrides the bundled copy (first-wins dedup by name).
+ *
+ * Users disable bundled rules three ways:
+ *   - flip `ttsr.builtinRules` off (drops the whole set),
+ *   - list a name in `ttsr.disabledRules` (drops one rule),
+ *   - define a same-named rule in any higher-priority source (overrides it).
+ * The first two are enforced in `bucketRules` (see capability/rule-buckets.ts).
+ */
+import { registerProvider } from "../capability";
+import { BUILTIN_DEFAULTS_PROVIDER_ID, type Rule, ruleCapability } from "../capability/rule";
+import type { LoadContext, LoadResult } from "../capability/types";
+import { BUILTIN_RULE_SOURCES } from "./builtin-rules";
+import { buildRuleFromMarkdown, createSourceMeta } from "./helpers";
+
+const DISPLAY_NAME = "Builtin Defaults";
+// Lowest priority: every other rule provider wins a name conflict.
+const PRIORITY = 1;
+
+async function loadRules(_ctx: LoadContext): Promise<LoadResult<Rule>> {
+	const items = BUILTIN_RULE_SOURCES.map(({ name, content }) => {
+		const virtualPath = `${BUILTIN_DEFAULTS_PROVIDER_ID}:${name}.md`;
+		const source = createSourceMeta(BUILTIN_DEFAULTS_PROVIDER_ID, virtualPath, "user");
+		return buildRuleFromMarkdown(name, content, virtualPath, source, { ruleName: name });
+	});
+	return { items };
+}
+
+registerProvider<Rule>(ruleCapability.id, {
+	id: BUILTIN_DEFAULTS_PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Default rules shipped with the agent (disable via ttsr.builtinRules / ttsr.disabledRules)",
+	priority: PRIORITY,
+	load: loadRules,
+});

package/src/discovery/builtin-rules/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Bundled default rules shipped with the coding agent.
+ *
+ * Each markdown source is embedded via `with { type: "text" }` so it survives
+ * `bun build --compile` (the compiled binary ships no loose rule files; only
+ * the embedded text). The native source/tarball installs read the same modules.
+ *
+ * Registered by the lowest-priority `builtin-defaults` rule provider so any
+ * user/project/tool rule with the same name overrides the bundled copy.
+ */
+import rsBoxLeak from "./rs-box-leak.md" with { type: "text" };
+import rsFuturePrelude from "./rs-future-prelude.md" with { type: "text" };
+import rsLazylock from "./rs-lazylock.md" with { type: "text" };
+import rsMatchErgonomics from "./rs-match-ergonomics.md" with { type: "text" };
+import rsParkingLot from "./rs-parking-lot.md" with { type: "text" };
+import rsResultType from "./rs-result-type.md" with { type: "text" };
+import tsBareCatch from "./ts-bare-catch.md" with { type: "text" };
+import tsImportType from "./ts-import-type.md" with { type: "text" };
+import tsNoAny from "./ts-no-any.md" with { type: "text" };
+import tsNoDeprecatedLeftovers from "./ts-no-deprecated-leftovers.md" with { type: "text" };
+import tsNoDynamicImport from "./ts-no-dynamic-import.md" with { type: "text" };
+import tsNoReturnType from "./ts-no-return-type.md" with { type: "text" };
+import tsNoTestTimers from "./ts-no-test-timers.md" with { type: "text" };
+import tsNoTinyFunctions from "./ts-no-tiny-functions.md" with { type: "text" };
+import tsPromiseWithResolvers from "./ts-promise-with-resolvers.md" with { type: "text" };
+import tsRedundantClearGuard from "./ts-redundant-clear-guard.md" with { type: "text" };
+import tsSetMap from "./ts-set-map.md" with { type: "text" };
+
+/** A bundled rule's stable name and raw markdown (frontmatter + body). */
+export interface BuiltinRuleSource {
+	name: string;
+	content: string;
+}
+
+/** All bundled default rules, ordered by name. */
+export const BUILTIN_RULE_SOURCES: readonly BuiltinRuleSource[] = [
+	{ name: "rs-box-leak", content: rsBoxLeak },
+	{ name: "rs-future-prelude", content: rsFuturePrelude },
+	{ name: "rs-lazylock", content: rsLazylock },
+	{ name: "rs-match-ergonomics", content: rsMatchErgonomics },
+	{ name: "rs-parking-lot", content: rsParkingLot },
+	{ name: "rs-result-type", content: rsResultType },
+	{ name: "ts-bare-catch", content: tsBareCatch },
+	{ name: "ts-import-type", content: tsImportType },
+	{ name: "ts-no-any", content: tsNoAny },
+	{ name: "ts-no-deprecated-leftovers", content: tsNoDeprecatedLeftovers },
+	{ name: "ts-no-dynamic-import", content: tsNoDynamicImport },
+	{ name: "ts-no-return-type", content: tsNoReturnType },
+	{ name: "ts-no-test-timers", content: tsNoTestTimers },
+	{ name: "ts-no-tiny-functions", content: tsNoTinyFunctions },
+	{ name: "ts-promise-with-resolvers", content: tsPromiseWithResolvers },
+	{ name: "ts-redundant-clear-guard", content: tsRedundantClearGuard },
+	{ name: "ts-set-map", content: tsSetMap },
+];

package/src/discovery/builtin-rules/rs-box-leak.md

@@ -0,0 +1,48 @@
+---
+description: Never use Box::leak - it intentionally leaks memory
+condition: "Box::leak"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Never use `Box::leak` to satisfy a lifetime. It intentionally leaks the allocation for the rest of the process.
+
+## Why
+
+- The allocation is never freed.
+- It hides ownership bugs.
+- It turns lifetime errors into process lifetime growth.
+- It makes tests pass while production memory grows.
+
+## Use instead
+
+| Need | Use |
+| --- | --- |
+| Shared async/thread data | `Arc<T>` or owned values |
+| Global lazy state | `LazyLock<T>` or `OnceLock<T>` |
+| Text escaping a scope | `String` / `Arc<str>` |
+| `'static` callback | `move` closure with owned captures |
+| FFI pointer | Explicit owner that frees on drop |
+
+## Examples
+
+```rust
+// Bad — leaking to manufacture 'static.
+fn label(id: u64) -> &'static str {
+    Box::leak(Box::new(format!("item_{id}")))
+}
+
+// Good — return owned data.
+fn label(id: u64) -> String {
+    format!("item_{id}")
+}
+
+// Bad — leaking before spawn.
+let state = Box::leak(Box::new(state));
+tokio::spawn(async move { use_state(state) });
+
+// Good — share owned state.
+let state = Arc::new(state);
+tokio::spawn(async move { use_state(&state) });
+```
+
+If `Box::leak` looks necessary, fix ownership instead.

package/src/discovery/builtin-rules/rs-future-prelude.md

@@ -0,0 +1,23 @@
+---
+description: Use Future not std::future::Future - it's in the prelude
+condition: "std::future::Future"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Use `Future` directly instead of `std::future::Future` in type positions.
+
+Rust 2024 includes `Future` in the standard prelude. Older editions can import it once with `use std::future::Future;`. Repeating the fully qualified path makes signatures harder to read without adding safety.
+
+## Examples
+
+```rust
+// Bad — fully qualified in every signature.
+fn fetch() -> impl std::future::Future<Output = Result<Data>> { ... }
+fn poll(fut: Pin<&mut dyn std::future::Future<Output = i32>>) { ... }
+
+// Good — use the prelude or one import.
+fn fetch() -> impl Future<Output = Result<Data>> { ... }
+fn poll(fut: Pin<&mut dyn Future<Output = i32>>) { ... }
+```
+
+Pre-2024 edition? Add `use std::future::Future;` at the top.

package/src/discovery/builtin-rules/rs-lazylock.md

@@ -0,0 +1,51 @@
+---
+description: Prefer std::sync::LazyLock over OnceLock and once_cell
+condition:
+  - "once_cell::"
+  - "OnceLock::new"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Prefer `std::sync::LazyLock` over `OnceLock` and the `once_cell` crate when the initializer is known at declaration time.
+
+`LazyLock` stores the cell and initializer together. There is no separate `init()` function, no repeated `get_or_init`, and no missing initialization path.
+
+## once_cell → std
+
+```rust
+// Before
+use once_cell::sync::Lazy;
+static CONFIG: Lazy<String> = Lazy::new(|| "value".to_string());
+
+// After
+use std::sync::LazyLock;
+static CONFIG: LazyLock<String> = LazyLock::new(|| "value".to_string());
+```
+
+## OnceLock → LazyLock
+
+```rust
+// Before — fixed initializer hidden in accessor.
+use std::sync::OnceLock;
+static SETTINGS: OnceLock<Settings> = OnceLock::new();
+fn settings() -> &'static Settings {
+    SETTINGS.get_or_init(Settings::load)
+}
+
+// After — initializer lives with the static.
+use std::sync::LazyLock;
+static SETTINGS: LazyLock<Settings> = LazyLock::new(Settings::load);
+```
+
+## Keep OnceLock when runtime input is required
+
+```rust
+use std::sync::OnceLock;
+static DATABASE: OnceLock<Database> = OnceLock::new();
+
+fn init_database(url: &str) {
+    let _ = DATABASE.set(Database::connect(url));
+}
+```
+
+Do not add `once_cell` for new code. Use the standard library equivalent.

package/src/discovery/builtin-rules/rs-match-ergonomics.md

@@ -0,0 +1,67 @@
+---
+description: Use match ergonomics instead of ref/ref mut patterns
+condition:
+  - "\\(ref mut "
+  - "\\(ref [a-z_]"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Use match ergonomics instead of explicit `ref` / `ref mut` patterns. Borrow the scrutinee and let bindings receive references.
+
+## Shared references
+
+```rust
+// Before
+match value {
+    Some(ref item) => println!("{item}"),
+    None => {}
+}
+
+// After
+match &value {
+    Some(item) => println!("{item}"),
+    None => {}
+}
+
+if let Some(item) = &value {
+    println!("{item}");
+}
+```
+
+## Mutable references
+
+```rust
+// Before
+match value {
+    Some(ref mut item) => *item += 1,
+    None => {}
+}
+
+// After
+match &mut value {
+    Some(item) => *item += 1,
+    None => {}
+}
+
+if let Some(item) = &mut value {
+    *item += 1;
+}
+```
+
+## Result
+
+```rust
+// Before
+match result {
+    Ok(ref data) => println!("{data}"),
+    Err(ref err) => eprintln!("{err}"),
+}
+
+// After
+match &result {
+    Ok(data) => println!("{data}"),
+    Err(err) => eprintln!("{err}"),
+}
+```
+
+Modern Rust rarely needs `ref` in patterns. Borrow the value being matched.

package/src/discovery/builtin-rules/rs-parking-lot.md

@@ -0,0 +1,44 @@
+---
+description: Use parking_lot instead of std::sync for Mutex/RwLock
+condition:
+  - "\\.lock\\(\\)\\.unwrap\\(\\)"
+  - "\\.read\\(\\)\\.unwrap\\(\\)"
+  - "\\.write\\(\\)\\.unwrap\\(\\)"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Use `parking_lot::{Mutex, RwLock}` instead of `std::sync::{Mutex, RwLock}` when code immediately unwraps lock results.
+
+## Why
+
+- `lock()`, `read()`, and `write()` return guards directly.
+- No poisoning error path to unwrap.
+- Guards are smaller and faster in common contention cases.
+- The call site shows locking, not error handling boilerplate.
+
+## Migration
+
+```rust
+// Before
+use std::sync::Mutex;
+let data = Mutex::new(Vec::new());
+let guard = data.lock().unwrap();
+
+// After
+use parking_lot::Mutex;
+let data = Mutex::new(Vec::new());
+let guard = data.lock();
+```
+
+## Equivalents
+
+| std::sync | parking_lot |
+| --- | --- |
+| `Mutex<T>` | `Mutex<T>` |
+| `RwLock<T>` | `RwLock<T>` |
+| `Condvar` | `Condvar` |
+| `Once` | `Once` |
+
+## Keep async locks async
+
+Use `tokio::sync::Mutex` / `tokio::sync::RwLock` when a guard is held across `.await` or the lock belongs to async coordination.

package/src/discovery/builtin-rules/rs-result-type.md

@@ -0,0 +1,19 @@
+---
+description: Result type aliases must include a defaulted error type parameter
+condition: "type\\s+Result<[A-Za-z_]\\w*>\\s*="
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+`Result` aliases must expose the error type as a defaulted parameter.
+
+```rust
+pub type Result<T, E = anyhow::Error> = std::result::Result<T, E>;
+```
+
+Never write:
+
+```rust
+type Result<T> = std::result::Result<T, anyhow::Error>;
+```
+
+The default keeps common call sites short while preserving escape hatches for precise errors.

package/src/discovery/builtin-rules/ts-bare-catch.md

@@ -0,0 +1,38 @@
+---
+description: Use bare `catch {` when the error binding is unused
+condition: "catch \\(_"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Use bare `catch {}` when the caught value is unused. An underscore-prefixed binding adds noise and still allocates a local name.
+
+## Replace
+
+```typescript
+// Bad
+try {
+	await loadConfig();
+} catch (_err) {
+	return null;
+}
+
+// Good
+try {
+	await loadConfig();
+} catch {
+	return null;
+}
+```
+
+## Keep a real name when used
+
+```typescript
+try {
+	await saveConfig();
+} catch (err) {
+	logger.error("save failed", { err });
+	throw err;
+}
+```
+
+Unused error? Bare `catch`. Used error? Name it for what it carries.