@henryqw/pi-add-dir 3.1.1 → 3.1.3

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. At launch, the extension shows a warning for each unknown key and each invalid or duplicate directory entry. It ignores that key or entry and loads the other directories. If the file is malformed or `directories` is not an array, it shows a warning and uses the default. It does not change the file. `/dir-add --global` and global removal with `/dir-ls` fail until you fix the reported issues. 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-config.ts

@@ -1,40 +1,11 @@
-import { isAbsolute } from "node:path";
-import { createConfigStore } from "@henryqw/pi-config-store";
-
-export interface AddDirConfig {
-	directories: string[];
-}
-
-function parseConfig(value: unknown): AddDirConfig {
-	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		throw new Error("Invalid pi-add-dir config: expected an object.");
-	}
-	const config = value as Record<string, unknown>;
-	if (Object.keys(config).length !== 1 || !Array.isArray(config.directories)) {
-		throw new Error('Invalid pi-add-dir config: expected only a "directories" array.');
-	}
-	const directories = config.directories;
-	if (
-		directories.some(
-			(directory) =>
-				typeof directory !== "string" ||
-				!isAbsolute(directory) ||
-				/\p{C}/u.test(directory),
-		)
-	) {
-		throw new Error("Invalid pi-add-dir config: directories must be absolute paths without control characters.");
-	}
-	if (new Set(directories).size !== directories.length) {
-		throw new Error("Invalid pi-add-dir config: directories must be unique.");
-	}
-	return { directories: [...directories] };
-}
+import { createConfigStore, field, parsers } from "@henryqw/pi-config-store";
 
 export function createAddDirConfigStore(agentDir?: string) {
-	return createConfigStore<AddDirConfig>({
+	return createConfigStore({
 		extensionId: "pi-add-dir",
 		agentDir,
-		defaults: () => ({ directories: [] }),
-		parse: parseConfig,
+		fields: {
+			directories: field(parsers.array(parsers.absolutePath(), { unique: (directory) => directory }), []),
+		},
 	});
 }

package/extensions/add-dir.ts

@@ -9,6 +9,7 @@ import {
 	type AutocompleteSuggestions,
 } from "@earendil-works/pi-tui";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { registerConfigReporting } from "@henryqw/pi-config-store";
 import { Type } from "typebox";
 import {
 	buildContextInjection,
@@ -227,6 +228,9 @@ export function createExternalAutocompleteProvider(
 
 export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOptions = {}): void {
 	const globalStore = createAddDirConfigStore(options.agentDir);
+	const configReporter = registerConfigReporting(pi, [globalStore]);
+	// Report the latest file before a global write, so issues found after launch use the same deduplicated report.
+	const reportGlobalConfig = (ctx: ExtensionContext) => configReporter.report(ctx, globalStore, globalStore.loadSync());
 	let sessionDirs: SessionDir[] = [];
 	let projectPaths: string[] = [];
 	let globalPaths: string[] = [];
@@ -234,17 +238,10 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 	let addedDirs: ScopedDir[] = [];
 	let currentCwd = "";
 
-	function globalConfigError(error: unknown): Error {
-		const message = error instanceof Error ? error.message : String(error);
-		return new Error(`Cannot load pi-add-dir global config at ${globalStore.path}: ${message}`, { cause: error });
-	}
-
+	// No field disables this config, so a load always has a value; bad entries are dropped and reported at launch.
 	function loadGlobalPaths(): string[] {
-		try {
-			return globalStore.loadSync().value.directories;
-		} catch (error) {
-			throw globalConfigError(error);
-		}
+		const loaded = globalStore.loadSync();
+		return loaded.status === "ok" ? loaded.value.directories : [];
 	}
 
 	function updateWidget(ctx: ExtensionContext): void {
@@ -391,17 +388,14 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 
 	async function writePersistentPath(source: "project" | "global", absolutePath: string, ctx: ExtensionContext): Promise<void> {
 		if (source === "global") {
-			try {
-				const config = await globalStore.update((current) => ({
-					directories: current.directories.includes(absolutePath)
-						? current.directories
-						: [...current.directories, absolutePath],
-				}));
-				globalPaths = config.directories;
-				return;
-			} catch (error) {
-				throw globalConfigError(error);
-			}
+			reportGlobalConfig(ctx);
+			const config = await globalStore.update((current) => ({
+				directories: current.directories.includes(absolutePath)
+					? current.directories
+					: [...current.directories, absolutePath],
+			}));
+			globalPaths = config.directories;
+			return;
 		}
 		projectPaths = await readProjectPaths(ctx.cwd, true);
 		if (projectPaths.some((path) => resolveDir(path, ctx.cwd) === absolutePath)) return;
@@ -498,14 +492,11 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 				);
 				persistState();
 			} else if (dir.source === "global") {
-				try {
-					const config = await globalStore.update((current) => ({
-						directories: current.directories.filter((path) => path !== dir.storedPath),
-					}));
-					globalPaths = config.directories;
-				} catch (error) {
-					throw globalConfigError(error);
-				}
+				reportGlobalConfig(ctx);
+				const config = await globalStore.update((current) => ({
+					directories: current.directories.filter((path) => path !== dir.storedPath),
+				}));
+				globalPaths = config.directories;
 			} else {
 				await mutateProjectConfig(
 					["--unset-all", "--fixed-value", PROJECT_CONFIG_KEY, dir.storedPath],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-add-dir",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "description": "Add external directories to a Pi session with context, skills, and file search.",
   "keywords": [
     "pi-package",
@@ -47,7 +47,7 @@
     "image": "https://raw.githubusercontent.com/HenryQW/pi-harness/main/extensions/pi-add-dir/example.png"
   },
   "dependencies": {
-    "@henryqw/pi-config-store": "^3.0.0"
+    "@henryqw/pi-config-store": "^4.0.0"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "1.1.0",