pi-local-agents-only 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.7 - 2026-04-11
+
+- fix non-git project-root detection so the global `~/.pi` directory no longer hijacks repo inference under a user's home directory
+- make the integration tests hermetic by resolving the repo-local `@mariozechner/pi-coding-agent` install instead of a global npm install
+- refuse to overwrite malformed global allowlist config and write config updates atomically
+- add regression tests for the homedir root bug and config-write hardening
+- add GitHub Actions CI plus a `prepublishOnly` guard that reruns `npm run check` before publish
+
+## 0.1.6 - 2026-04-07
+
+- add dev-time static checking with `tsc --noEmit`
+- add a local `check` script that runs tests plus typechecking
+- keep pi core typing support in `devDependencies` only so this stays a lightweight published package
+- annotate the extension with `// @ts-check` and JSDoc types for earlier local error detection
+
 ## 0.1.5 - 2026-04-07
 
 - strip already-loaded global `AGENTS.md` / `CLAUDE.md` context reliably instead of rereading live files from disk

package/extensions/local-agents-only.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * Purpose: Strip pi's global AGENTS.md and CLAUDE.md blocks from the effective prompt for opted-in projects.
  * Responsibilities: Detect repo and worktree opt-in state, manage repo and global toggles, add a local-only guardrail, and remove matching global context blocks before model calls.
@@ -7,10 +9,29 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
+/** @typedef {import("@mariozechner/pi-coding-agent").ExtensionAPI} ExtensionAPI */
+/** @typedef {import("@mariozechner/pi-coding-agent").ExtensionContext} ExtensionContext */
+/** @typedef {{ projects: string[]; repositories: string[] }} LocalAgentsOnlyConfig */
+/** @typedef {{ start: string; projectRoot: string; repoId: string; worktreeRoots: string[] }} ProjectState */
+/** @typedef {{ enabled: boolean; source: "env" | "marker" | "global-config" | "default" }} Mode */
+/** @typedef {{ path: string; start: number; end: number }} ContextBlock */
+/** @typedef {{ prompt: string; removedPaths: string[] }} StripResult */
+
+class ConfigError extends Error {
+	/**
+	 * @param {string} message
+	 * @param {unknown} [cause]
+	 */
+	constructor(message, cause) {
+		super(message, cause === undefined ? undefined : { cause });
+		this.name = "ConfigError";
+	}
+}
+
 const COMMAND = "local-agents-only";
 const MARKER = join(".pi", COMMAND);
 const GLOBAL_CONTEXT_FILES = ["AGENTS.md", "CLAUDE.md"];
@@ -20,7 +41,9 @@ const PROJECT_CONTEXT_HEADER = "\n\n# Project Context\n\nProject-specific instru
 const SKILLS_HEADER = "\n\nThe following skills provide specialized instructions for specific tasks.";
 const DATE_HEADER = "\nCurrent date:";
 const CONTEXT_BLOCK_HEADER = /^## ([^\n]+(?:AGENTS|CLAUDE)\.md)\n\n/gm;
+const emptyConfig = () => ({ projects: [], repositories: [] });
 
+/** @returns {string} */
 const getAgentDir = () => {
 	const env = process.env.PI_CODING_AGENT_DIR;
 	if (env === "~") {
@@ -31,10 +54,31 @@ const getAgentDir = () => {
 	}
 	return env || join(homedir(), ".pi", "agent");
 };
+
+/** @param {string} path */
 const normalizePath = (path) => resolve(path).replace(/\\/g, "/");
+
+/** @param {string} path */
+const isGlobalPiDirectory = (path) => {
+	const normalizedPath = normalizePath(path);
+	const agentDir = normalizePath(getAgentDir());
+	return normalizedPath === agentDir || normalizedPath === normalizePath(dirname(agentDir));
+};
+
+/** @returns {string} */
 const CONFIG = () => join(getAgentDir(), `${COMMAND}.json`);
+
+/** @param {string} projectRoot */
 const getMarkerPath = (projectRoot) => join(projectRoot, MARKER);
+
+/** @param {string[]} values */
 const uniqueSorted = (values) => [...new Set(values.map(normalizePath))].sort();
+
+/**
+ * @param {string} start
+ * @param {(dir: string) => boolean} predicate
+ * @returns {string | undefined}
+ */
 const walkUp = (start, predicate) => {
 	let current = resolve(start);
 	while (true) {
@@ -43,11 +87,17 @@ const walkUp = (start, predicate) => {
 		}
 		const parent = dirname(current);
 		if (parent === current) {
-			return;
+			return undefined;
 		}
 		current = parent;
 	}
 };
+
+/**
+ * @param {string} start
+ * @param {string[]} args
+ * @returns {string | undefined}
+ */
 const runGit = (start, args) => {
 	try {
 		return execFileSync("git", args, {
@@ -56,23 +106,118 @@ const runGit = (start, args) => {
 			stdio: ["ignore", "pipe", "ignore"],
 		}).trim();
 	} catch {
-		return;
+		return undefined;
+	}
+};
+
+/**
+ * @param {string} name
+ * @param {unknown} value
+ * @param {string} configPath
+ * @returns {string[]}
+ */
+const parseConfigList = (name, value, configPath) => {
+	if (value === undefined) {
+		return [];
+	}
+	if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) {
+		throw new ConfigError(
+			`Malformed local-agents-only config at ${normalizePath(configPath)}. Expected "${name}" to be an array of strings. Fix or remove the file, then retry.`,
+		);
+	}
+	return uniqueSorted(value);
+};
+
+/**
+ * @param {string} rawConfig
+ * @param {string} configPath
+ * @returns {LocalAgentsOnlyConfig}
+ */
+const parseConfig = (rawConfig, configPath) => {
+	let parsed;
+	try {
+		parsed = /** @type {{ projects?: unknown; repositories?: unknown }} */ (JSON.parse(rawConfig));
+	} catch (error) {
+		throw new ConfigError(
+			`Malformed local-agents-only config at ${normalizePath(configPath)}. Fix or remove the file, then retry.`,
+			error,
+		);
 	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new ConfigError(
+			`Malformed local-agents-only config at ${normalizePath(configPath)}. Expected a JSON object. Fix or remove the file, then retry.`,
+		);
+	}
+	return {
+		projects: parseConfigList("projects", parsed.projects, configPath),
+		repositories: parseConfigList("repositories", parsed.repositories, configPath),
+	};
 };
+
+/**
+ * @param {string} [configPath]
+ * @returns {LocalAgentsOnlyConfig}
+ */
+const readConfigForMutation = (configPath = CONFIG()) => {
+	if (!existsSync(configPath)) {
+		return emptyConfig();
+	}
+	return parseConfig(readFileSync(configPath, "utf8"), configPath);
+};
+
+/**
+ * @param {string} [configPath]
+ * @returns {LocalAgentsOnlyConfig}
+ */
 const readConfig = (configPath = CONFIG()) => {
 	try {
-		const { projects = [], repositories = [] } = JSON.parse(readFileSync(configPath, "utf8"));
-		return {
-			projects: Array.isArray(projects) ? projects.map(normalizePath) : [],
-			repositories: Array.isArray(repositories) ? repositories.map(normalizePath) : [],
-		};
+		return readConfigForMutation(configPath);
 	} catch {
-		return { projects: [], repositories: [] };
+		return emptyConfig();
 	}
 };
+
+/**
+ * @param {string} path
+ * @param {string} content
+ */
+const writeFileAtomically = (path, content) => {
+	mkdirSync(dirname(path), { recursive: true });
+	const tempPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+	/** @type {number | undefined} */
+	let fileDescriptor;
+	try {
+		fileDescriptor = openSync(tempPath, "wx", 0o600);
+		writeFileSync(fileDescriptor, content, "utf8");
+		fsyncSync(fileDescriptor);
+		closeSync(fileDescriptor);
+		fileDescriptor = undefined;
+		renameSync(tempPath, path);
+		try {
+			const directoryDescriptor = openSync(dirname(path), "r");
+			try {
+				fsyncSync(directoryDescriptor);
+			} finally {
+				closeSync(directoryDescriptor);
+			}
+		} catch {
+			// Best effort: directory fsync is not available on every platform.
+		}
+	} catch (error) {
+		if (fileDescriptor !== undefined) {
+			closeSync(fileDescriptor);
+		}
+		rmSync(tempPath, { force: true });
+		throw error;
+	}
+};
+
+/**
+ * @param {LocalAgentsOnlyConfig} config
+ * @param {string} [configPath]
+ */
 const writeConfig = ({ projects, repositories }, configPath = CONFIG()) => {
-	mkdirSync(dirname(configPath), { recursive: true });
-	writeFileSync(
+	writeFileAtomically(
 		configPath,
 		JSON.stringify(
 			{
@@ -84,6 +229,11 @@ const writeConfig = ({ projects, repositories }, configPath = CONFIG()) => {
 		) + "\n",
 	);
 };
+
+/**
+ * @param {string | undefined} [value]
+ * @returns {boolean | undefined}
+ */
 const getEnvToggle = (value = process.env.PI_LOCAL_AGENTS_ONLY) => {
 	const toggle = `${value ?? ""}`.trim().toLowerCase();
 	if (ENV_TRUE.includes(toggle)) {
@@ -92,24 +242,46 @@ const getEnvToggle = (value = process.env.PI_LOCAL_AGENTS_ONLY) => {
 	if (ENV_FALSE.includes(toggle)) {
 		return false;
 	}
+	return undefined;
 };
+
+/** @param {string} [agentDir] */
 const getGlobalContextPaths = (agentDir = getAgentDir()) => GLOBAL_CONTEXT_FILES.map((name) => join(agentDir, name));
+
+/** @param {string} [agentDir] */
 const getExistingGlobalContextPaths = (agentDir = getAgentDir()) =>
 	getGlobalContextPaths(agentDir).filter((path) => existsSync(path));
+
+/**
+ * @param {string} prompt
+ * @param {number} offset
+ * @returns {number}
+ */
 const getContextSectionEnd = (prompt, offset) => {
 	const candidates = [prompt.indexOf(SKILLS_HEADER, offset), prompt.indexOf(DATE_HEADER, offset)].filter(
 		(index) => index !== -1,
 	);
 	return candidates.length > 0 ? Math.min(...candidates) : prompt.length;
 };
+
+/**
+ * @param {string} contextSection
+ * @returns {ContextBlock[]}
+ */
 const getContextBlocks = (contextSection) => {
 	const matches = [...contextSection.matchAll(CONTEXT_BLOCK_HEADER)];
 	return matches.map((match, index) => ({
 		path: match[1],
-		start: match.index,
-		end: index + 1 < matches.length ? matches[index + 1].index : contextSection.length,
+		start: match.index ?? 0,
+		end: index + 1 < matches.length ? (matches[index + 1].index ?? contextSection.length) : contextSection.length,
 	}));
 };
+
+/**
+ * @param {string} prompt
+ * @param {string[]} [globalPaths]
+ * @returns {StripResult}
+ */
 const stripGlobalContext = (prompt, globalPaths = getGlobalContextPaths()) => {
 	const sectionStart = prompt.lastIndexOf(PROJECT_CONTEXT_HEADER);
 	if (sectionStart === -1) {
@@ -123,7 +295,9 @@ const stripGlobalContext = (prompt, globalPaths = getGlobalContextPaths()) => {
 		return { prompt, removedPaths: [] };
 	}
 	const globalPathKeys = new Set(globalPaths.map(normalizePath));
+	/** @type {string[]} */
 	const keptBlocks = [];
+	/** @type {string[]} */
 	const removedPaths = [];
 	for (const block of blocks) {
 		const blockText = contextSection.slice(block.start, block.end);
@@ -146,14 +320,29 @@ const stripGlobalContext = (prompt, globalPaths = getGlobalContextPaths()) => {
 		removedPaths: uniqueSorted(removedPaths),
 	};
 };
+
+/**
+ * @param {string} start
+ * @returns {string | undefined}
+ */
 const getGitTopLevel = (start) => {
 	const topLevel = runGit(start, ["rev-parse", "--show-toplevel"]);
 	return topLevel ? normalizePath(topLevel) : undefined;
 };
+
+/**
+ * @param {string} start
+ * @returns {string | undefined}
+ */
 const getGitCommonDir = (start) => {
 	const commonDir = runGit(start, ["rev-parse", "--git-common-dir"]);
 	return commonDir ? normalizePath(resolve(start, commonDir)) : undefined;
 };
+
+/**
+ * @param {string} start
+ * @returns {string[]}
+ */
 const getWorktreeRoots = (start) => {
 	const list = runGit(start, ["worktree", "list", "--porcelain"]);
 	if (!list) {
@@ -166,13 +355,21 @@ const getWorktreeRoots = (start) => {
 			.map((line) => line.slice("worktree ".length)),
 	);
 };
+
+/**
+ * @param {string} [start]
+ * @returns {ProjectState}
+ */
 const getProjectState = (start = process.cwd()) => {
 	const normalizedStart = normalizePath(start);
 	const gitTopLevel = getGitTopLevel(normalizedStart);
 	const projectRoot =
 		gitTopLevel ||
 		walkUp(normalizedStart, (dir) => existsSync(getMarkerPath(dir))) ||
-		walkUp(normalizedStart, (dir) => existsSync(join(dir, ".pi"))) ||
+		walkUp(normalizedStart, (dir) => {
+			const piDir = join(dir, ".pi");
+			return existsSync(piDir) && !isGlobalPiDirectory(piDir);
+		}) ||
 		normalizedStart;
 	const worktreeRoots = getWorktreeRoots(normalizedStart);
 	return {
@@ -183,19 +380,32 @@ const getProjectState = (start = process.cwd()) => {
 			worktreeRoots.length > 0 ? uniqueSorted([projectRoot, ...worktreeRoots]) : [normalizePath(projectRoot)],
 	};
 };
+
+/** @param {ProjectState} state */
 const getMarkerRoots = (state) => uniqueSorted([state.projectRoot, ...state.worktreeRoots]);
+
+/** @param {ProjectState} state */
 const hasMarker = (state) => getMarkerRoots(state).some((root) => existsSync(getMarkerPath(root)));
+
+/** @param {ProjectState} state */
 const writeMarkers = (state) => {
 	for (const root of getMarkerRoots(state)) {
 		mkdirSync(dirname(getMarkerPath(root)), { recursive: true });
 		writeFileSync(getMarkerPath(root), "\n");
 	}
 };
+
+/** @param {ProjectState} state */
 const clearMarkers = (state) => {
 	for (const root of getMarkerRoots(state)) {
 		rmSync(getMarkerPath(root), { force: true });
 	}
 };
+
+/**
+ * @param {string[]} [paths]
+ * @returns {string}
+ */
 const buildLocalOnlyNotice = (paths = getExistingGlobalContextPaths(getAgentDir())) => {
 	if (paths.length === 0) {
 		return "";
@@ -208,6 +418,12 @@ const buildLocalOnlyNotice = (paths = getExistingGlobalContextPaths(getAgentDir(
 		"Follow only repo-local AGENTS.md or CLAUDE.md guidance for this project.",
 	].join("\n");
 };
+
+/**
+ * @param {string} prompt
+ * @param {string} [agentDir]
+ * @returns {string}
+ */
 const applyLocalOnlyPrompt = (prompt, agentDir = getAgentDir()) => {
 	const { prompt: stripped, removedPaths } = stripGlobalContext(prompt, getGlobalContextPaths(agentDir));
 	const notice = buildLocalOnlyNotice(
@@ -215,6 +431,8 @@ const applyLocalOnlyPrompt = (prompt, agentDir = getAgentDir()) => {
 	);
 	return notice ? `${stripped}\n\n${notice}` : stripped;
 };
+
+/** @param {ExtensionContext} ctx */
 const setStatus = (ctx) => {
 	if (!ctx.hasUI) {
 		return;
@@ -222,8 +440,18 @@ const setStatus = (ctx) => {
 	const mode = getMode(ctx.cwd);
 	ctx.ui.setStatus(COMMAND, mode.enabled ? `AGENTS: local-only (${mode.source})` : undefined);
 };
+
+/**
+ * @param {ProjectState} state
+ * @returns {string}
+ */
 const getProjectTarget = (state) =>
 	state.worktreeRoots.length > 1 ? `${state.projectRoot} and linked worktrees` : state.projectRoot;
+
+/**
+ * @param {ProjectState} state
+ * @returns {string}
+ */
 const getOffNotification = (state) => {
 	const mode = getMode(state);
 	if (!mode.enabled) {
@@ -238,10 +466,43 @@ const getOffNotification = (state) => {
 	return `Repo marker cleared for ${getProjectTarget(state)}, but local-agents-only is still enabled via ${mode.source}.`;
 };
 
+/**
+ * @param {(config: LocalAgentsOnlyConfig) => LocalAgentsOnlyConfig} mutate
+ */
+const mutateGlobalConfig = (mutate) => {
+	const configPath = CONFIG();
+	const config = readConfigForMutation(configPath);
+	writeConfig(mutate(config), configPath);
+	return configPath;
+};
+
+/**
+ * @param {unknown} error
+ * @param {string} [configPath]
+ * @returns {string}
+ */
+const getGlobalConfigMutationError = (error, configPath = CONFIG()) => {
+	if (error instanceof ConfigError) {
+		return `Global allowlist unchanged: ${error.message}`;
+	}
+	const reason = error instanceof Error ? error.message : String(error);
+	return `Global allowlist unchanged: failed to update ${normalizePath(configPath)} (${reason}).`;
+};
+
+/**
+ * @param {string} [start]
+ * @returns {string}
+ */
 export function findProjectRoot(start = process.cwd()) {
 	return getProjectState(start).projectRoot;
 }
 
+/**
+ * @param {string | ProjectState} [start]
+ * @param {string | undefined} [envValue]
+ * @param {string} [configPath]
+ * @returns {Mode}
+ */
 export function getMode(start = process.cwd(), envValue = process.env.PI_LOCAL_AGENTS_ONLY, configPath = CONFIG()) {
 	const state = typeof start === "string" ? getProjectState(start) : start;
 	const envToggle = getEnvToggle(envValue);
@@ -261,10 +522,16 @@ export function getMode(start = process.cwd(), envValue = process.env.PI_LOCAL_A
 	return { enabled: false, source: "default" };
 }
 
+/**
+ * @param {string} prompt
+ * @param {string[]} [globalPaths]
+ * @returns {string}
+ */
 export function stripGlobalBlocks(prompt, globalPaths = getGlobalContextPaths()) {
 	return stripGlobalContext(prompt, globalPaths).prompt;
 }
 
+/** @param {ExtensionAPI} pi */
 export default function localAgentsOnly(pi) {
 	pi.registerCommand(COMMAND, {
 		description: "Use only repo-local AGENTS prompt context",
@@ -274,7 +541,10 @@ export default function localAgentsOnly(pi) {
 				case "on":
 					writeMarkers(state);
 					setStatus(ctx);
-					ctx.ui.notify(`Enabled for ${state.projectRoot}${state.worktreeRoots.length > 1 ? ` across ${state.worktreeRoots.length} worktrees` : ""}`, "info");
+					ctx.ui.notify(
+						`Enabled for ${state.projectRoot}${state.worktreeRoots.length > 1 ? ` across ${state.worktreeRoots.length} worktrees` : ""}`,
+						"info",
+					);
 					return;
 				case "off":
 					clearMarkers(state);
@@ -282,21 +552,29 @@ export default function localAgentsOnly(pi) {
 					ctx.ui.notify(getOffNotification(state), "info");
 					return;
 				case "global-on": {
-					const config = readConfig();
-					writeConfig({
-						projects: [...config.projects, ...state.worktreeRoots],
-						repositories: [...config.repositories, state.repoId],
-					});
+					try {
+						mutateGlobalConfig((config) => ({
+							projects: [...config.projects, ...state.worktreeRoots],
+							repositories: [...config.repositories, state.repoId],
+						}));
+					} catch (error) {
+						ctx.ui.notify(getGlobalConfigMutationError(error), "error");
+						return;
+					}
 					setStatus(ctx);
 					ctx.ui.notify(`Global allowlist enabled for ${state.projectRoot}`, "info");
 					return;
 				}
 				case "global-off": {
-					const config = readConfig();
-					writeConfig({
-						projects: config.projects.filter((path) => !state.worktreeRoots.includes(path)),
-						repositories: config.repositories.filter((id) => id !== state.repoId),
-					});
+					try {
+						mutateGlobalConfig((config) => ({
+							projects: config.projects.filter((path) => !state.worktreeRoots.includes(path)),
+							repositories: config.repositories.filter((id) => id !== state.repoId),
+						}));
+					} catch (error) {
+						ctx.ui.notify(getGlobalConfigMutationError(error), "error");
+						return;
+					}
 					setStatus(ctx);
 					ctx.ui.notify(`Global allowlist disabled for ${state.projectRoot}`, "info");
 					return;

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "pi-local-agents-only",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Pi extension that strips global AGENTS.md and CLAUDE.md from the effective prompt for selected projects.",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
   "license": "MIT",
   "type": "module",
-  "keywords": ["pi-package", "pi", "pi-extension", "extension"],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "extension"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fitchmultz/pi-local-agents-only.git"
@@ -14,11 +19,26 @@
     "url": "https://github.com/fitchmultz/pi-local-agents-only/issues"
   },
   "homepage": "https://github.com/fitchmultz/pi-local-agents-only#readme",
-  "files": ["extensions", "README.md", "CHANGELOG.md", "LICENSE"],
+  "files": [
+    "extensions",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "pi": {
-    "extensions": ["./extensions"]
+    "extensions": [
+      "./extensions"
+    ]
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "check": "npm test && npm run typecheck",
+    "prepublishOnly": "npm run check"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.65.2",
+    "@types/node": "^24.3.0",
+    "typescript": "^5.7.3"
   }
 }