@oh-my-pi/pi-coding-agent 15.6.0 → 15.7.1

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.

package/src/discovery/builtin-rules/ts-import-type.md

@@ -0,0 +1,42 @@
+---
+description: "Use `import type`, not `import('pkg').Type` in type positions"
+condition: "import\\("
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Use top-level `import type` declarations for type-only dependencies. NEVER write `import("pkg").Type` inside source annotations.
+
+## Why
+
+- Top-level imports expose dependencies immediately.
+- Import sorting and deduplication can manage them.
+- Signatures stay readable and reviewable.
+- Re-exports do not inherit noisy inline paths.
+
+## Avoid
+
+```typescript
+// Bad — inline imports hide dependencies in signatures.
+function run(client: import("some-sdk").Client, input: import("zod/v4").infer<Schema>): Promise<Output>;
+
+// Bad — annotations become path dumps.
+const options: import("some-sdk/config").ClientOptions = { ... };
+```
+
+## Use
+
+```typescript
+import type { Client } from "some-sdk";
+import type { ClientOptions } from "some-sdk/config";
+import type { infer as Infer } from "zod/v4";
+
+function run(client: Client, input: Infer<Schema>): Promise<Output>;
+const options: ClientOptions = { ... };
+```
+
+## Exceptions
+
+- Ambient `.d.ts` globals that must not become modules.
+- Generated files whose generator owns import management.
+
+In normal `.ts` / `.tsx` source, use `import type`.

package/src/discovery/builtin-rules/ts-no-any.md

@@ -0,0 +1,56 @@
+---
+description: "Never use `any` in TypeScript annotations or assertions — use `unknown`, generics, or the actual type"
+condition: ": any|as any"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Never use `: any` or `as any`. They disable type checking exactly where the boundary needs precision.
+
+## Use instead
+
+- `unknown` for unvalidated input.
+- A domain type when the shape is known.
+- A generic when the caller supplies the shape.
+- A type guard when runtime checks establish shape.
+- `satisfies` for object literals that must match a contract.
+
+## Parameters and returns
+
+```typescript
+// Bad
+function readId(value: any): any {
+	return value.id;
+}
+
+// Good — validate unknown input.
+function readId(value: unknown): string | undefined {
+	if (value && typeof value === "object" && "id" in value) {
+		const candidate = (value as { id: unknown }).id;
+		return typeof candidate === "string" ? candidate : undefined;
+	}
+}
+```
+
+## Assertions
+
+```typescript
+// Bad
+const root = document.getElementById("root") as any;
+root.innerText = "ready";
+
+// Good
+const root = document.getElementById("root") as HTMLElement | null;
+root?.innerText = "ready";
+```
+
+## Object literals
+
+```typescript
+// Bad
+const config = { port: 3000 } as any as ServerConfig;
+
+// Good
+const config = { port: 3000 } satisfies ServerConfig;
+```
+
+If a library boundary truly requires an unchecked cast, use `as unknown as T` with a short reason. Never leave a bare `any`.

package/src/discovery/builtin-rules/ts-no-dynamic-import.md

@@ -0,0 +1,39 @@
+---
+description: "Do not use `await import()` — use static imports unless dynamic loading is unavoidable"
+condition: "await import\\("
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Use static imports for modules known at author time. Reach for `await import()` only when the module specifier is genuinely runtime-selected.
+
+## Why
+
+- Static imports fail during build, not under load.
+- Bundlers, type checkers, and tree shakers see them.
+- The dependency graph remains reviewable.
+- Consumers keep precise module types without casts.
+
+## Avoid
+
+```typescript
+// Bad — the module path is a literal.
+const { createClient } = await import("some-sdk");
+
+// Bad — dynamic import followed by a shape assertion.
+const mod = (await import("./known-module")) as { run?: unknown };
+```
+
+## Use
+
+```typescript
+import { createClient } from "some-sdk";
+import { run } from "./known-module";
+```
+
+## Exceptions
+
+- Plugin loading from a runtime registry.
+- Platform-specific modules that do not exist everywhere.
+- Test cases that intentionally exercise module loading boundaries.
+
+Exception? Add a short comment naming why static import cannot work.

package/src/discovery/builtin-rules/ts-no-return-type.md

@@ -0,0 +1,45 @@
+---
+description: "Do not use `ReturnType<typeof fn>` — name the type explicitly"
+condition: "ReturnType<"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Do not publish contracts through `ReturnType<typeof fn>`. Name the type at the module that owns the value and import that name at consumers.
+
+## Why
+
+- Named types document the contract directly.
+- Consumers stop coupling to implementation helpers.
+- JSDoc and changelog notes attach to the exported type.
+- Type errors point at the intended API boundary.
+
+## Avoid
+
+```typescript
+// Bad — opaque and coupled to implementation names.
+type Config = Awaited<ReturnType<typeof loadConfig>>;
+type Message = ReturnType<typeof buildMessage>["message"];
+let service: ReturnType<typeof createService> | undefined;
+```
+
+## Use
+
+```typescript
+// In the module that owns the function:
+export interface LoadedConfig {
+	path: string;
+	values: Record<string, unknown>;
+}
+
+export function loadConfig(path: string): Promise<LoadedConfig> { ... }
+
+// At the consumer:
+import type { LoadedConfig } from "./config";
+```
+
+## Exceptions
+
+- Timer handles: `ReturnType<typeof setTimeout>` / `setInterval`.
+- Generic type utilities where the function is a type parameter.
+
+Concrete function? Export a concrete type.

package/src/discovery/builtin-rules/ts-no-tiny-functions.md

@@ -0,0 +1,50 @@
+---
+description: "Do not extract 1-2 line functions that only wrap an expression — inline them"
+condition: "\\{\\s*return [^;{}\\n]+;?\\s*\\}|\\b(?:const|let|var)\\s+[\\w$]+\\s*=\\s*(\\([^)]*\\)|[a-zA-Z_$][\\w$]*)\\s*=>\\s*[^{\\n]+$"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+interruptMode: never
+---
+
+Do not extract a function whose whole body is one expression or one `return`. Inline it unless the name creates a durable contract.
+
+## Why
+
+- One-line wrappers hide no real behavior.
+- Readers must jump to verify trivial code.
+- The signature freezes a shape too early.
+- Search and type flow work better with inline expressions.
+
+## Avoid
+
+```typescript
+// Bad — pure rename, no behavior added.
+function isEmpty(value: string): boolean {
+	return value.length === 0;
+}
+
+const getDisplayName = (user: User) => user.profile.displayName;
+
+function double(value: number) {
+	return value * 2;
+}
+
+if (isEmpty(name)) { ... }
+```
+
+## Use
+
+```typescript
+if (name.length === 0) { ... }
+const displayName = user.profile.displayName;
+const doubled = value * 2;
+```
+
+## Allowed tiny functions
+
+- Three or more call sites need lockstep behavior.
+- Exported name represents a stable domain concept.
+- Callback identity matters.
+- Type guard preserves narrowing.
+- Public API, test seam, or DI boundary needs indirection.
+
+If none apply, inline it.

package/src/discovery/builtin-rules/ts-promise-with-resolvers.md

@@ -0,0 +1,65 @@
+---
+description: Use Promise.withResolvers() instead of new Promise() constructor
+condition: "new Promise\\("
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Use `Promise.withResolvers()` instead of `new Promise((resolve, reject) => ...)`. It keeps control flow linear and exposes typed resolver functions without callback nesting.
+
+## Basic operation
+
+```typescript
+// Bad
+function delay(ms: number): Promise<void> {
+	return new Promise(resolve => {
+		setTimeout(resolve, ms);
+	});
+}
+
+// Good
+function delay(ms: number): Promise<void> {
+	const { promise, resolve } = Promise.withResolvers<void>();
+	setTimeout(resolve, ms);
+	return promise;
+}
+```
+
+## Event-based completion
+
+```typescript
+// Bad
+function waitForEvent(emitter: EventEmitter, event: string): Promise<unknown> {
+	return new Promise((resolve, reject) => {
+		emitter.once(event, resolve);
+		emitter.once("error", reject);
+	});
+}
+
+// Good
+function waitForEvent(emitter: EventEmitter, event: string): Promise<unknown> {
+	const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+	emitter.once(event, resolve);
+	emitter.once("error", reject);
+	return promise;
+}
+```
+
+## Stored resolver
+
+```typescript
+class Gate {
+	#promise: Promise<void>;
+	#resolve: () => void;
+
+	constructor() {
+		const { promise, resolve } = Promise.withResolvers<void>();
+		this.#promise = promise;
+		this.#resolve = resolve;
+	}
+
+	open(): void { this.#resolve(); }
+	wait(): Promise<void> { return this.#promise; }
+}
+```
+
+Use the constructor only when an API specifically requires the executor form.

package/src/discovery/builtin-rules/ts-set-map.md

@@ -0,0 +1,28 @@
+---
+description: Prefer Record<K, V> for small static literals; use Set/Map for anything dynamic
+condition: "\\bnew\\s+(Set|Map)\\b"
+scope: "tool:edit(**/*.{ts,tsx}), tool:write(**/*.{ts,tsx})"
+interruptMode: never
+---
+
+Use `Record<K, V>` / `Record<K, true>` for small, static string-keyed lookup tables.
+
+Use `Set` / `Map` when keys are dynamic, non-string, inserted or deleted at runtime, or when code needs `.size`, `.clear()`, stable insertion order, or iterator APIs.
+
+```typescript
+// Static literal → Record
+const LABEL_BY_KIND: Record<string, string> = {
+	text: "Text",
+	json: "JSON",
+	binary: "Binary",
+};
+
+// Dynamic membership → Set
+const seen = new Set<string>();
+for (const item of items) {
+	if (seen.has(item.id)) continue;
+	seen.add(item.id);
+}
+```
+
+Small fixed table? `Record`. Runtime collection? `Set` / `Map`.

package/src/discovery/index.ts

@@ -22,6 +22,7 @@ import "../capability/tool";
 // Import providers (each registers itself on import)
 import "./agents-md";
 import "./builtin";
+import "./builtin-defaults";
 import "./claude";
 import "./claude-plugins";
 import "./cline";

package/src/edit/hashline/block-resolver.ts

@@ -0,0 +1,14 @@
+/**
+ * Tree-sitter-backed {@link BlockResolver} for the hashline `replace block N:`
+ * operator. Bridges the pure hashline seam to the native `blockRangeAt`
+ * primitive in `@oh-my-pi/pi-natives`, which infers the language from the file
+ * path and returns the 1-indexed line span of the syntactic block beginning on
+ * the requested line (or `null` when none can be resolved).
+ */
+import type { BlockResolver } from "@oh-my-pi/hashline";
+import { blockRangeAt } from "@oh-my-pi/pi-natives";
+
+export const nativeBlockResolver: BlockResolver = ({ path, text, line }) => {
+	const range = blockRangeAt({ code: text, path, line });
+	return range ? { start: range.startLine, end: range.endLine } : null;
+};

package/src/edit/hashline/diff.ts

@@ -22,6 +22,7 @@ import {
 import { resolveToCwd } from "../../tools/path-utils";
 import { generateDiffString } from "../diff";
 import { readEditFileText } from "../read-file";
+import { nativeBlockResolver } from "./block-resolver";
 
 export interface HashlineDiffOptions {
 	/**
@@ -74,7 +75,9 @@ export async function computeHashlineSectionDiff(
 		const normalized = normalizeToLF(content);
 		const hashError = validateSectionHash(section, absolutePath, normalized, snapshots);
 		if (hashError) return { error: hashError };
-		const result = options.streaming ? section.applyPartialTo(normalized) : section.applyTo(normalized);
+		const result = options.streaming
+			? section.applyPartialTo(normalized, nativeBlockResolver)
+			: section.applyTo(normalized, nativeBlockResolver);
 		if (normalized === result.text) return { error: `No changes would be made to ${section.path}.` };
 		return generateDiffString(normalized, result.text);
 	} catch (err) {

package/src/edit/hashline/execute.ts

@@ -25,6 +25,7 @@ import { outputMeta } from "../../tools/output-meta";
 import { generateDiffString } from "../diff";
 import { getFileSnapshotStore } from "../file-snapshot-store";
 import type { EditToolDetails, EditToolPerFileResult, LspBatchRequest } from "../renderer";
+import { nativeBlockResolver } from "./block-resolver";
 import { HashlineFilesystem } from "./filesystem";
 import { type HashlineParams, hashlineEditParamsSchema } from "./params";
 
@@ -133,7 +134,7 @@ export async function executeHashlineSingle(
 		batchRequest: options.batchRequest,
 	});
 	const snapshots = getFileSnapshotStore(options.session);
-	const patcher = new Patcher({ fs, snapshots });
+	const patcher = new Patcher({ fs, snapshots, blockResolver: nativeBlockResolver });
 
 	// Single-section fast path: prepare, commit, render.
 	if (patch.sections.length === 1) {

package/src/edit/hashline/index.ts

@@ -1,3 +1,4 @@
+export * from "./block-resolver";
 export * from "./diff";
 export * from "./execute";
 export * from "./filesystem";

package/src/eval/py/kernel.ts

@@ -17,7 +17,7 @@ import { Settings } from "../../config/settings";
 import { type KernelDisplayOutput, renderKernelDisplay } from "./display";
 import { PYTHON_PRELUDE } from "./prelude";
 import RUNNER_SCRIPT from "./runner.py" with { type: "text" };
-import { filterEnv, resolvePythonRuntime } from "./runtime";
+import { enumeratePythonRuntimes, filterEnv, type PythonRuntime, resolvePythonRuntime } from "./runtime";
 
 export type { KernelDisplayOutput, PythonStatusEvent } from "./display";
 export { renderKernelDisplay } from "./display";
@@ -106,6 +106,8 @@ export interface PythonKernelAvailability {
 	ok: boolean;
 	pythonPath?: string;
 	reason?: string;
+	/** The probed-working runtime, when one was found. */
+	runtime?: PythonRuntime;
 }
 
 function getRemainingTimeMs(deadlineMs?: number): number | undefined {
@@ -134,19 +136,34 @@ export async function checkPythonKernelAvailability(cwd: string): Promise<Python
 		const settings = await Settings.init();
 		const { env } = settings.getShellConfig();
 		const baseEnv = filterEnv(env);
-		const runtime = resolvePythonRuntime(cwd, baseEnv);
-		const probe = await $`${runtime.pythonPath} -c "import sys;sys.exit(0)"`
-			.quiet()
-			.nothrow()
-			.cwd(cwd)
-			.env(runtime.env);
-		if (probe.exitCode === 0) {
-			return { ok: true, pythonPath: runtime.pythonPath };
+		const runtimes = enumeratePythonRuntimes(cwd, baseEnv);
+		if (runtimes.length === 0) {
+			return { ok: false, reason: "Python executable not found on PATH" };
+		}
+		// Probe each candidate in priority order and use the first that actually
+		// runs. A managed env left behind by a removed `uv` install can exist on
+		// disk yet fail to execute; falling through to the next candidate lets a
+		// working system Python take over instead of failing the whole session.
+		const failures: string[] = [];
+		for (const runtime of runtimes) {
+			try {
+				const probe = await $`${runtime.pythonPath} -c "import sys;sys.exit(0)"`
+					.quiet()
+					.nothrow()
+					.cwd(cwd)
+					.env(runtime.env);
+				if (probe.exitCode === 0) {
+					return { ok: true, pythonPath: runtime.pythonPath, runtime };
+				}
+				failures.push(`${runtime.pythonPath} (exit code ${probe.exitCode})`);
+			} catch (err) {
+				failures.push(`${runtime.pythonPath} (${err instanceof Error ? err.message : String(err)})`);
+			}
 		}
 		return {
 			ok: false,
-			pythonPath: runtime.pythonPath,
-			reason: `Python interpreter at ${runtime.pythonPath} returned exit code ${probe.exitCode}`,
+			pythonPath: runtimes[0].pythonPath,
+			reason: `No working Python interpreter found. Tried: ${failures.join("; ")}`,
 		};
 	} catch (err) {
 		return { ok: false, reason: err instanceof Error ? err.message : String(err) };
@@ -207,10 +224,15 @@ export class PythonKernel {
 			throw new Error(availability.reason ?? "Python kernel unavailable");
 		}
 
-		const settings = await Settings.init();
-		const { env: shellEnv } = settings.getShellConfig();
-		const baseEnv = filterEnv(shellEnv);
-		const runtime = resolvePythonRuntime(options.cwd, baseEnv);
+		// Reuse the interpreter the availability probe selected so the spawned
+		// kernel matches what we verified actually runs. The fallback computes a
+		// runtime only for the skip-check fast path (test runtime /
+		// PI_PYTHON_SKIP_CHECK), where no candidate was probed.
+		let runtime = availability.runtime;
+		if (!runtime) {
+			const { env: shellEnv } = (await Settings.init()).getShellConfig();
+			runtime = resolvePythonRuntime(options.cwd, filterEnv(shellEnv));
+		}
 		const spawnEnv: Record<string, string> = {};
 		for (const [key, value] of Object.entries(runtime.env)) {
 			if (typeof value === "string") spawnEnv[key] = value;

package/src/eval/py/runtime.ts

@@ -162,49 +162,78 @@ export function resolveVenvPath(cwd: string): string | undefined {
 }
 
 /**
- * Resolve Python runtime including executable path, environment, and venv detection.
+ * Apply a venv-style PATH/VIRTUAL_ENV layout onto a fresh copy of `baseEnv` for
+ * the interpreter living in `binDir`.
  */
-export function resolvePythonRuntime(cwd: string, baseEnv: Record<string, string | undefined>): PythonRuntime {
+function applyVenvEnv(
+	baseEnv: Record<string, string | undefined>,
+	venvPath: string,
+	binDir: string,
+): Record<string, string | undefined> {
 	const env = { ...baseEnv };
-	const venvPath = env.VIRTUAL_ENV ?? resolveVenvPath(cwd);
+	env.VIRTUAL_ENV = venvPath;
+	const pathKey = resolvePathKey(env);
+	const currentPath = env[pathKey];
+	env[pathKey] = currentPath ? `${binDir}${path.delimiter}${currentPath}` : binDir;
+	return env;
+}
+
+function venvBinDir(venvPath: string): string {
+	return process.platform === "win32" ? path.join(venvPath, "Scripts") : path.join(venvPath, "bin");
+}
+
+/**
+ * Enumerate candidate Python runtimes in priority order: an active/project venv,
+ * the managed `~/.omp/python-env`, then the system interpreter on PATH. Every
+ * candidate that physically exists is returned so callers can probe each in turn
+ * rather than committing to the first — a managed env left behind by a removed
+ * `uv` install no longer shadows a working system Python.
+ */
+export function enumeratePythonRuntimes(cwd: string, baseEnv: Record<string, string | undefined>): PythonRuntime[] {
+	const runtimes: PythonRuntime[] = [];
+	const seen = new Set<string>();
+	const push = (runtime: PythonRuntime): void => {
+		if (seen.has(runtime.pythonPath)) return;
+		seen.add(runtime.pythonPath);
+		runtimes.push(runtime);
+	};
 
+	const venvPath = baseEnv.VIRTUAL_ENV ?? resolveVenvPath(cwd);
 	if (venvPath) {
-		env.VIRTUAL_ENV = venvPath;
-		const binDir = process.platform === "win32" ? path.join(venvPath, "Scripts") : path.join(venvPath, "bin");
+		const binDir = venvBinDir(venvPath);
 		const pythonCandidate = path.join(binDir, process.platform === "win32" ? "python.exe" : "python");
 		if (fs.existsSync(pythonCandidate)) {
-			const pathKey = resolvePathKey(env);
-			const currentPath = env[pathKey];
-			env[pathKey] = currentPath ? `${binDir}${path.delimiter}${currentPath}` : binDir;
-			return {
-				pythonPath: pythonCandidate,
-				env,
-				venvPath,
-			};
+			push({ pythonPath: pythonCandidate, env: applyVenvEnv(baseEnv, venvPath, binDir), venvPath });
 		}
 	}
 
 	const managed = resolveManagedPythonCandidate();
 	if (fs.existsSync(managed.pythonPath)) {
-		env.VIRTUAL_ENV = managed.venvPath;
-		const pathKey = resolvePathKey(env);
-		const currentPath = env[pathKey];
-		const managedBin =
-			process.platform === "win32" ? path.join(managed.venvPath, "Scripts") : path.join(managed.venvPath, "bin");
-		env[pathKey] = currentPath ? `${managedBin}${path.delimiter}${currentPath}` : managedBin;
-		return {
+		const managedBin = path.dirname(managed.pythonPath);
+		push({
 			pythonPath: managed.pythonPath,
-			env,
+			env: applyVenvEnv(baseEnv, managed.venvPath, managedBin),
 			venvPath: managed.venvPath,
-		};
+		});
 	}
 
-	const pythonPath = $which("python") ?? $which("python3");
-	if (!pythonPath) {
+	const systemPath = $which("python") ?? $which("python3");
+	if (systemPath) {
+		push({ pythonPath: systemPath, env: { ...baseEnv } });
+	}
+
+	return runtimes;
+}
+
+/**
+ * Resolve the highest-priority Python runtime. Prefer {@link enumeratePythonRuntimes}
+ * when you can probe candidates; this returns only the first one and throws when
+ * no interpreter exists.
+ */
+export function resolvePythonRuntime(cwd: string, baseEnv: Record<string, string | undefined>): PythonRuntime {
+	const [runtime] = enumeratePythonRuntimes(cwd, baseEnv);
+	if (!runtime) {
 		throw new Error("Python executable not found on PATH");
 	}
-	return {
-		pythonPath,
-		env,
-	};
+	return runtime;
 }