@spences10/pi-coding-preferences 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Spence
+
+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/README.md

@@ -0,0 +1,34 @@
+# @spences10/pi-coding-preferences
+
+Pi extension that blocks configured coding workflow anti-patterns
+before agents run them.
+
+It ships with default preferences for Scott's workflow. Add user
+preferences at `~/.pi/agent/coding-preferences.json` and project
+preferences at `.pi/coding-preferences.json`; when either file exists,
+configured rules are loaded instead of the built-in defaults.
+
+```json
+{
+	"rules": [
+		{
+			"name": "no-npm",
+			"toolNames": ["bash"],
+			"target": "command",
+			"pattern": "^npm\\\\b",
+			"reason": "Use pnpm in this repo."
+		}
+	]
+}
+```
+
+Rule targets are `command`, `path`, or `input`. Patterns are
+JavaScript regular expressions.
+
+```bash
+pi install npm:@spences10/pi-coding-preferences
+```
+
+This is opt-in: installing the package globally applies it to your Pi
+sessions, but projects and downstream users do not inherit it unless
+they install the package.

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { type ExtensionAPI, type ToolCallEvent } from '@earendil-works/pi-coding-agent';
+export type PreferenceRuleConfig = {
+    name: string;
+    toolNames?: string[];
+    pattern: string;
+    target?: 'command' | 'path' | 'input';
+    reason: string;
+};
+export type CodingPreferencesConfig = {
+    rules: PreferenceRuleConfig[];
+};
+export declare const default_config: CodingPreferencesConfig;
+export declare function get_global_config_path(): string;
+export declare function get_project_config_path(cwd?: string): string;
+export declare function load_config(cwd?: string): CodingPreferencesConfig;
+export declare function should_block_coding_preference(event: ToolCallEvent, config?: CodingPreferencesConfig): string | undefined;
+export default function coding_preferences(pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,112 @@
+// Config-driven coding workflow preferences for Pi agents.
+import { getAgentDir, } from '@earendil-works/pi-coding-agent';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export const default_config = {
+    rules: [
+        {
+            name: 'no-secret-file-reads',
+            toolNames: ['read', 'bash'],
+            target: 'input',
+            pattern: String.raw `(^|/)\.env(?:\.[^/\s"']*)?$|\.tfvars(?:\.json)?$`,
+            reason: 'Blocked by coding preferences: do not read secret files into model context. Use nopeek to list or load only the required key names without exposing secret values.',
+        },
+        {
+            name: 'prefer-read-tool',
+            toolNames: ['bash'],
+            target: 'command',
+            pattern: String.raw `^\s*(?:cat|sed\s+(?:-n\s+)?["']?\d+(?:,\d+)?p["']?)\s+[^|;&>]+$`,
+            reason: 'Blocked by coding preferences: use the read tool for file inspection instead of cat or sed. Do not investigate this guardrail; retry with read.',
+        },
+        {
+            name: 'prefer-rg',
+            toolNames: ['bash'],
+            target: 'command',
+            pattern: '^\\s*grep\\b',
+            reason: 'Blocked by coding preferences: use rg for code/text search instead of grep. Do not investigate this guardrail; retry with rg.',
+        },
+        {
+            name: 'no-ad-hoc-todos',
+            toolNames: ['write', 'edit', 'bash'],
+            target: 'input',
+            pattern: '(^|/)(?:TODO|TODOS|todo|todos|tasks|TASKS)\\.md$',
+            reason: "Blocked by coding preferences: do not create ad-hoc TODO markdown files. Use Pi team/tasks or the project's existing issue tracker instead.",
+        },
+    ],
+};
+function input_record(event) {
+    return event.input;
+}
+function input_strings(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(input_strings);
+    if (!value || typeof value !== 'object')
+        return [];
+    return Object.values(value).flatMap(input_strings);
+}
+function path_from(event) {
+    const input = input_record(event);
+    for (const key of ['path', 'file_path', 'filePath']) {
+        const value = input[key];
+        if (typeof value === 'string')
+            return value;
+    }
+    return undefined;
+}
+function command_from(event) {
+    const command = input_record(event).command;
+    return typeof command === 'string' ? command : undefined;
+}
+function target_values(event, target = 'input') {
+    if (target === 'command')
+        return command_from(event) ? [command_from(event)] : [];
+    if (target === 'path')
+        return path_from(event) ? [path_from(event)] : [];
+    return input_strings(event.input);
+}
+export function get_global_config_path() {
+    return join(getAgentDir(), 'coding-preferences.json');
+}
+export function get_project_config_path(cwd = process.cwd()) {
+    return join(resolve(cwd), '.pi', 'coding-preferences.json');
+}
+function read_config_file(path) {
+    if (!existsSync(path))
+        return undefined;
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return { rules: parsed.rules ?? [] };
+}
+export function load_config(cwd = process.cwd()) {
+    const global_config = read_config_file(get_global_config_path());
+    const project_config = read_config_file(get_project_config_path(cwd));
+    if (!global_config && !project_config)
+        return default_config;
+    return {
+        rules: [
+            ...(global_config?.rules ?? []),
+            ...(project_config?.rules ?? []),
+        ],
+    };
+}
+export function should_block_coding_preference(event, config = load_config()) {
+    for (const rule of config.rules) {
+        if (rule.toolNames && !rule.toolNames.includes(event.toolName))
+            continue;
+        const pattern = new RegExp(rule.pattern);
+        if (target_values(event, rule.target).some((value) => pattern.test(value)))
+            return rule.reason;
+    }
+    return undefined;
+}
+export default function coding_preferences(pi) {
+    const config = load_config();
+    pi.on('tool_call', async (event) => {
+        const reason = should_block_coding_preference(event, config);
+        if (!reason)
+            return undefined;
+        return { block: true, reason };
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@spences10/pi-coding-preferences",
+  "version": "0.0.2",
+  "description": "Pi extension that nudges agents toward Scott's coding workflow preferences",
+  "keywords": [
+    "agent-guardrails",
+    "coding-preferences",
+    "pi",
+    "pi-package"
+  ],
+  "license": "MIT",
+  "author": "Scott Spence <me@scottspence.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spences10/my-pi.git",
+    "directory": "packages/pi-coding-preferences"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "scripts": {
+    "build": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run build:self",
+    "build:self": "tsc -p tsconfig.build.json",
+    "check": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run check:self",
+    "check:self": "tsc --noEmit -p tsconfig.json",
+    "test": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run test:self",
+    "test:self": "vitest run",
+    "test:watch": "vitest"
+  }
+}