@henryqw/pi-add-dir 3.1.0 → 3.1.2

package/README.md

@@ -1,6 +1,6 @@
 # `@henryqw/pi-add-dir`
 
-Give the current Pi session context, skills, and searchable files from directories outside the workspace. Reuse those resources in place without copying or linking their directories.
+Give the current Pi session the context, skills, and searchable files of external directories. Pi uses these resources in place, so you do not copy or link the directories.
 
 ![Pi using added external directories by name](https://raw.githubusercontent.com/HenryQW/pi-harness/main/extensions/pi-add-dir/example.png)
 
@@ -14,19 +14,19 @@ Requires Pi 1.1.0 or later in the 1.x series.
 
 ## Use
 
-Run `/dir-add`, enter a directory, then run `/dir-ls` to confirm it was added. Pi lists the directory and exposes its supported resources.
+Run `/dir-add` and enter a directory. Then run `/dir-ls` to make sure that Pi added it. Pi lists the directory and makes its supported resources available.
 
-Use slash commands from the Pi prompt as a human; Pi agents use the tools.
+Humans use the slash commands from the Pi prompt. Pi agents use the tools.
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `/dir-add [path]` | command | Add to this session by default; pass `--project` or `--global` before the path to persist for this Git repository's linked worktrees or every workspace. Omit the path to enter it when prompted; supports `~`. |
-| `/dir-ls` | command | List directories with their scope; select one to remove from that scope. |
+| `/dir-add [path]` | command | Add to this session by default. To persist for the linked worktrees of this Git repository or for every workspace, pass `--project` or `--global` before the path. Omit the path to enter it at the prompt. Supports `~`. |
+| `/dir-ls` | command | List directories with their scope. Select one to remove it from that scope. |
 | `/dir-reload` | command | Reload external directory resources. |
 | `add_directory(path)` | tool | Add a directory to this session and return its context and instructions. Model-only: codemode scripts cannot call it. |
-| `search_external_files(pattern, maxResults?)` | tool | Glob-search added directories; returns up to 50 results by default, configurable to 1,000. Returns a structured result to codemode scripts. |
+| `search_external_files(pattern, maxResults?)` | tool | Search added directories with a glob. Returns up to 50 results by default; `maxResults` accepts up to 1,000. Returns a structured result to codemode scripts. |
 | `@` file autocomplete | ui | Find files in added directories and insert their absolute paths. |
-| External directory widget | ui | Show added directories and point to `/dir-ls` for management. |
+| External directory widget | ui | Show added directories and refer to `/dir-ls` for management. |
 
 Added directories give Pi these resources:
 
@@ -34,13 +34,13 @@ Added directories give Pi these resources:
 - Skills that Pi loads from `.pi/skills`, `.agents/skills`, and `.claude/skills`.
 - Files in the editor's `@` autocomplete, with absolute paths.
 
-`/dir-add` reloads only when the discovered external skill paths change, not merely because the directory contains skills. `add_directory` stays session-local; when its result asks for `/reload`, run it to update external skills.
+`/dir-add` reloads only when the discovered external skill paths change. A directory that contains skills does not alone cause a reload. `add_directory` stays session-local. When its result asks for `/reload`, run `/reload` to update external skills.
 
 ### Programmatic use
 
-`search_external_files` declares an output schema. Programmatic callers such as Pi `codemode` scripts receive `{ pattern, maxResults, searchedDirectories, totalFound, truncated, directories }`. `directories` lists each directory with at least one match, with its label and absolute file paths. `searchedDirectories` counts only directories actually searched, including those with no matches; directories skipped after reaching the cap are not counted. `truncated` is true when the result cap stopped the search, so later directories or files may hold more matches. The model receives the same matches as text. Calling the tool with no added directories is a tool error, and scripts reject with the message.
+`search_external_files` declares an output schema. Programmatic callers, such as Pi `codemode` scripts, receive `{ pattern, maxResults, searchedDirectories, totalFound, truncated, directories }`. `directories` lists each directory that has at least one match, with its label and absolute file paths. `searchedDirectories` counts only the directories that the tool searched, including directories with no matches. It does not count directories that the tool skipped after it reached the cap. `truncated` is true when the result cap stopped the search. In that case, later directories or files can contain more matches. The model receives the same matches as text. If there are no added directories, a call to the tool is a tool error, and scripts reject with the message.
 
-`add_directory` is declared to the model only (Pi `model-only` exposure). Codemode scripts and other tools cannot call it, so another directory's `AGENTS.md`, `CLAUDE.md`, and skills enter the session only through a model-visible tool call or a user command. This package does not enable codemode.
+`add_directory` is declared to the model only (Pi `model-only` exposure). Codemode scripts and other tools cannot call it. Thus, the `AGENTS.md`, `CLAUDE.md`, and skills of another directory enter the session only through a model-visible tool call or a user command. This package does not enable codemode.
 
 ## Config
 
@@ -50,16 +50,16 @@ Package-owned: `~/.pi/agent/config/pi-add-dir/config.json`
 | --- | --- | --- | --- |
 | `directories` | Directories loaded for every workspace. `/dir-add --global` updates this list. | Array of unique absolute paths without control characters. | `[]` |
 
-A missing file uses the default. Invalid config stops loading and is not overwritten. Reload Pi after editing the file manually.
+If the file is missing, the extension uses the default. Invalid config stops the load, and the extension does not overwrite the file. Reload Pi after you edit the file manually.
 
 ## State and storage
 
-Session directories live in the current session branch. New session additions reject directories inside or containing the current working directory, or overlapping another active added directory. Restored session entries are not rechecked for overlap when the working directory changes. Project directories use the repository's repeatable local Git config key `pi-add-dir.directory`. Local Git config is shared by linked worktrees, cannot be injected by cloning a repository, and remains machine-local. `/dir-add --project` therefore requires a Git repository.
+Session directories are stored in the current session branch. A new session addition rejects a directory that is inside the current working directory or that contains it. It also rejects a directory that overlaps another active added directory. When the working directory changes, the extension does not check restored session entries for overlap again. Project directories use the repeatable local Git config key `pi-add-dir.directory` of the repository. Linked worktrees share local Git config. A cloned repository cannot inject this config, and it stays on the local machine. Thus, `/dir-add --project` requires a Git repository.
 
 Persistent scopes are explicit because added directories can inject `AGENTS.md`, `CLAUDE.md`, and skills.
 
 ## Limits and recovery
 
-Search supports basename and relative-path globs. It skips `.git` and `node_modules` and does not follow symbolic links. It uses Node filesystem traversal and returns at most 1,000 results per call.
+Search supports basename and relative-path globs. It skips `.git` and `node_modules` and does not follow symbolic links. It uses Node filesystem traversal and returns at most 1,000 results for each call.
 
-Missing or overlapping **project and global** directories remain configured but are skipped with a warning. Restore a missing directory at its original path or resolve the overlap, then run `/dir-reload` to rescan. To change or discard a configured path, use `/dir-ls` to **remove** it from its scope, then `/dir-add` with the corrected path if needed; `/dir-ls` cannot repair paths in place.
+Missing or overlapping **project and global** directories stay in the config, but the extension skips them with a warning. Restore a missing directory at its original path, or resolve the overlap. Then run `/dir-reload` to scan again. To change or discard a configured path, use `/dir-ls` to **remove** it from its scope. If necessary, run `/dir-add` with the corrected path. `/dir-ls` cannot repair paths in place.

package/extensions/add-dir-helpers.ts

@@ -23,7 +23,7 @@ function isMissingPathError(error: unknown): boolean {
 	return error.code === "ENOENT" || error.code === "ENOTDIR";
 }
 
-export function expandUserPath(input: string): string {
+function expandUserPath(input: string): string {
 	if (input === "~") return homedir();
 	if (input.startsWith("~/") || input.startsWith(`~${path.sep}`)) return path.join(homedir(), input.slice(2));
 	return input;
@@ -49,7 +49,7 @@ export function dirExists(dir: string): boolean {
 	}
 }
 
-export function readFileSafe(filePath: string): string | null {
+function readFileSafe(filePath: string): string | null {
 	try {
 		return readFileSync(filePath, "utf8");
 	} catch {
@@ -113,8 +113,6 @@ export function collectSkillPaths(dirs: AddedDir[]): string[] {
 }
 
 export function buildContextInjection(dirs: AddedDir[]): string {
-	if (dirs.length === 0) return "";
-
 	const sections = [
 		"\n\n## External Directories (added via pi-add-dir)",
 		`\nThe following ${dirs.length} external director${dirs.length === 1 ? "y is" : "ies are"} included in this session. You can read, edit, and write files in these directories using absolute paths.\n`,
@@ -154,7 +152,6 @@ export async function findFiles(
 
 	const directories = [root];
 	while (directories.length > 0) {
-		signal?.throwIfAborted();
 		const dir = directories.pop()!;
 		let entries;
 		try {
@@ -166,7 +163,6 @@ export async function findFiles(
 		}
 		signal?.throwIfAborted();
 		for (const entry of entries) {
-			signal?.throwIfAborted();
 			if (entry.isSymbolicLink()) continue;
 
 			const fullPath = path.join(dir, entry.name);

package/extensions/add-dir.ts

@@ -84,7 +84,6 @@ interface AddDirectoryDetails {
 	directory: string;
 	hasAgentsMd: boolean;
 	hasClaudeMd: boolean;
-	skillCount: number;
 	skillNames: string[];
 }
 
@@ -94,40 +93,34 @@ interface SearchDetails {
 	dirCount: number;
 }
 
-function isAddedDir(value: unknown): value is AddedDir {
+interface SessionDir {
+	absolutePath: string;
+}
+
+function isAddedDir(value: unknown): value is SessionDir {
 	if (!value || typeof value !== "object") return false;
-	const dir = value as Partial<AddedDir>;
-	return typeof dir.absolutePath === "string" && isAbsolute(dir.absolutePath) && typeof dir.label === "string";
+	const dir = value as Partial<SessionDir>;
+	return typeof dir.absolutePath === "string" && isAbsolute(dir.absolutePath);
 }
 
-function readState(data: unknown): AddedDir[] {
+function readState(data: unknown): SessionDir[] {
 	if (!data || typeof data !== "object") return [];
 	const dirs = (data as { dirs?: unknown }).dirs;
 	return Array.isArray(dirs) ? dirs.filter(isAddedDir) : [];
 }
 
-function parseAddArgs(args: string | undefined): ParsedAddArgs {
-	const input = args?.trim() ?? "";
+function parseAddArgs(args: string): ParsedAddArgs | undefined {
+	const input = args.trim();
 	if (!input) return { source: "session", path: "" };
 	for (const source of ["project", "global"] as const) {
 		const flag = `--${source}`;
 		if (input === flag) return { source, path: "" };
 		if (input.startsWith(`${flag} `)) return { source, path: input.slice(flag.length).trim() };
 	}
-	if (input.startsWith("--")) throw new Error(DIR_ADD_USAGE);
+	if (input.startsWith("--")) return undefined;
 	return { source: "session", path: input };
 }
 
-function validateStoredPaths(paths: string[], source: DirSource): void {
-	if (
-		paths.some(
-			(path) => typeof path !== "string" || !isAbsolute(path) || /\p{C}/u.test(path),
-		)
-	) {
-		throw new Error(`Invalid ${source} pi-add-dir configuration: expected absolute paths.`);
-	}
-}
-
 function hasGitMarker(cwd: string): boolean {
 	let directory = resolveDir(cwd, cwd);
 	while (true) {
@@ -150,12 +143,15 @@ function isWithinDir(dir: string, candidate: string): boolean {
 	return relativePath === "" || (!relativePath.startsWith(`..${sep}`) && relativePath !== ".." && !isAbsolute(relativePath));
 }
 
+function overlaps(a: string, b: string): boolean {
+	return isWithinDir(a, b) || isWithinDir(b, a);
+}
+
 function contextDetails(dirCtx: DirContext, absolutePath: string): AddDirectoryDetails {
 	return {
 		directory: absolutePath,
 		hasAgentsMd: dirCtx.agentsMd !== null,
 		hasClaudeMd: dirCtx.claudeMd !== null,
-		skillCount: dirCtx.skills.size,
 		skillNames: [...dirCtx.skills],
 	};
 }
@@ -231,7 +227,7 @@ export function createExternalAutocompleteProvider(
 
 export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOptions = {}): void {
 	const globalStore = createAddDirConfigStore(options.agentDir);
-	let sessionDirs: AddedDir[] = [];
+	let sessionDirs: SessionDir[] = [];
 	let projectPaths: string[] = [];
 	let globalPaths: string[] = [];
 	let managedDirs: ScopedDir[] = [];
@@ -318,17 +314,11 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 				}
 				const duplicate = nextActive.find((dir) => dir.absolutePath === absolutePath);
 				if (!inactiveReason && duplicate) inactiveReason = `shadowed by ${duplicate.source} scope`;
-				if (
-					!inactiveReason &&
-					(isWithinDir(cwdPath, absolutePath) || isWithinDir(absolutePath, cwdPath))
-				) {
+				if (!inactiveReason && overlaps(cwdPath, absolutePath)) {
 					inactiveReason = "overlaps current working directory scope";
 				}
 				const overlap = !inactiveReason
-					? nextActive.find(
-							(dir) =>
-								isWithinDir(dir.absolutePath, absolutePath) || isWithinDir(absolutePath, dir.absolutePath),
-						)
+					? nextActive.find((dir) => overlaps(dir.absolutePath, absolutePath))
 					: undefined;
 				if (overlap) inactiveReason = `overlaps ${overlap.source} directory ${overlap.absolutePath}`;
 				const scoped = {
@@ -361,7 +351,7 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 	}
 
 	function persistState(): void {
-		pi.appendEntry(STATE_TYPE, { dirs: sessionDirs.map((dir) => ({ ...dir })) });
+		pi.appendEntry(STATE_TYPE, { dirs: sessionDirs.map(({ absolutePath }) => ({ absolutePath })) });
 	}
 
 	async function readProjectPaths(cwd: string, required: boolean): Promise<string[]> {
@@ -381,7 +371,9 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 			throw new Error(`Cannot read project pi-add-dir configuration: ${result.stderr.trim() || `git exited ${result.code}`}`);
 		}
 		const paths = result.stdout.split("\0").filter((path) => path.length > 0);
-		validateStoredPaths(paths, "project");
+		if (paths.some((path) => !isAbsolute(path) || /\p{C}/u.test(path))) {
+			throw new Error("Invalid project pi-add-dir configuration: expected absolute paths.");
+		}
 		return [...new Set(paths)];
 	}
 
@@ -424,7 +416,6 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 	async function addDir(
 		dirPath: string,
 		source: DirSource,
-		cwd: string,
 		ctx: ExtensionContext,
 	): Promise<{ ok: boolean; message: string; resourcesChanged: boolean; absolutePath?: string; context?: DirContext }> {
 		const input = dirPath.trim();
@@ -432,7 +423,7 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 
 		let absolutePath: string;
 		try {
-			absolutePath = resolveDir(input, cwd);
+			absolutePath = resolveDir(input, ctx.cwd);
 			if (!dirExists(absolutePath)) {
 				return { ok: false, message: `Directory does not exist: ${absolutePath}`, resourcesChanged: false };
 			}
@@ -453,14 +444,11 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 				resourcesChanged: false,
 			};
 		}
-		const cwdPath = resolveDir(cwd, cwd);
-		if (isWithinDir(cwdPath, absolutePath) || isWithinDir(absolutePath, cwdPath)) {
+		if (overlaps(resolveDir(ctx.cwd, ctx.cwd), absolutePath)) {
 			return { ok: false, message: "Directory overlaps current working directory scope.", resourcesChanged: false };
 		}
 		const overlap = addedDirs.find(
-			(dir) =>
-				dir.absolutePath !== absolutePath &&
-				(isWithinDir(dir.absolutePath, absolutePath) || isWithinDir(absolutePath, dir.absolutePath)),
+			(dir) => dir.absolutePath !== absolutePath && overlaps(dir.absolutePath, absolutePath),
 		);
 		if (overlap) {
 			return {
@@ -475,32 +463,13 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 		const label = basename(absolutePath) || absolutePath;
 		try {
 			if (source === "session") {
-				sessionDirs.push({ absolutePath, label });
+				sessionDirs.push({ absolutePath });
 				persistState();
 			} else {
-				const previousSessionDirs = sessionDirs;
+				await writePersistentPath(source, absolutePath, ctx);
 				if (sessionMatch) {
 					sessionDirs = sessionDirs.filter((dir) => resolveDir(dir.absolutePath, ctx.cwd) !== absolutePath);
-					try {
-						persistState();
-					} catch (error) {
-						sessionDirs = previousSessionDirs;
-						throw error;
-					}
-				}
-				try {
-					await writePersistentPath(source, absolutePath, ctx);
-				} catch (error) {
-					if (sessionMatch) {
-						sessionDirs = previousSessionDirs;
-						try {
-							persistState();
-						} catch (recoveryError) {
-							const recoveryMessage = recoveryError instanceof Error ? recoveryError.message : String(recoveryError);
-							throw new Error(`Persistent write failed and session recovery failed: ${recoveryMessage}`, { cause: error });
-						}
-					}
-					throw error;
+					persistState();
 				}
 			}
 		} catch (error) {
@@ -577,18 +546,15 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 		description: "Reload external directory resources",
 		handler: async (_args, ctx) => {
 			await ctx.reload();
-			return;
 		},
 	});
 
 	pi.registerCommand("dir-add", {
 		description: "Add an external directory to this session, project, or global scope",
 		handler: async (args, ctx) => {
-			let parsed: ParsedAddArgs;
-			try {
-				parsed = parseAddArgs(args);
-			} catch (error) {
-				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			const parsed = parseAddArgs(args);
+			if (!parsed) {
+				ctx.ui.notify(DIR_ADD_USAGE, "error");
 				return;
 			}
 			if (!parsed.path) {
@@ -597,7 +563,7 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 				parsed.path = prompted;
 			}
 
-			const result = await addDir(parsed.path, parsed.source, ctx.cwd, ctx);
+			const result = await addDir(parsed.path, parsed.source, ctx);
 			const message = result.ok && result.resourcesChanged ? `${result.message} Reloading external skills...` : result.message;
 			ctx.ui.notify(message, result.ok ? "info" : "error");
 			if (result.ok && result.resourcesChanged) await ctx.reload();
@@ -645,8 +611,7 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 		annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const inputPath = params.path.trim();
-			const result = await addDir(inputPath, "session", ctx.cwd, ctx);
+			const result = await addDir(params.path, "session", ctx);
 			if (!result.ok) throw new Error(result.message);
 
 			const absolutePath = result.absolutePath!;
@@ -679,7 +644,7 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 
 		renderResult(result, { expanded }, theme) {
 			const details = result.details as AddDirectoryDetails | undefined;
-			if (!details) {
+			if (!details?.directory) {
 				const content = result.content[0];
 				const text = content?.type === "text" ? content.text : "Done";
 				return new Text(theme.fg("success", `✓ ${text}`), 0, 0);
@@ -689,7 +654,7 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 			const badges: string[] = [];
 			if (details.hasAgentsMd) badges.push(theme.fg("accent", "AGENTS.md"));
 			if (details.hasClaudeMd) badges.push(theme.fg("accent", "CLAUDE.md"));
-			if (details.skillCount > 0) badges.push(theme.fg("warning", `${details.skillCount} skills`));
+			if (details.skillNames.length > 0) badges.push(theme.fg("warning", `${details.skillNames.length} skills`));
 			if (badges.length > 0) parts.push(theme.fg("dim", " | ") + badges.join(theme.fg("dim", ", ")));
 			if (expanded && details.skillNames.length > 0) {
 				parts.push("\n" + theme.fg("muted", "  Skills: ") + details.skillNames.map((name) => theme.fg("text", name)).join(", "));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-add-dir",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Add external directories to a Pi session with context, skills, and file search.",
   "keywords": [
     "pi-package",