pi-extmgr 0.1.20 → 0.1.22

package/README.md

@@ -17,11 +17,16 @@ pi install npm:pi-extmgr
 
 Then reload Pi.
 
+Requires Node.js `>=22.5.0`.
+
 ## Features
 
 - **Unified manager UI**
   - Local extensions (`~/.pi/agent/extensions`, `.pi/extensions`) and installed packages in one list
   - Scope indicators (global/project), status indicators, update badges
+- **Package extension configuration panel**
+  - Configure individual extension entrypoints inside an installed package (`c` on package row)
+  - Persists to package filters in `settings.json` (no manual JSON editing)
 - **Safe staged local extension toggles**
   - Toggle with `Space/Enter`, apply with `S`
   - Unsaved-change guard when leaving (save/discard/stay)
@@ -54,22 +59,23 @@ Open the manager:
 
 ### In the manager
 
-| Key           | Action                                           |
-| ------------- | ------------------------------------------------ |
-| `↑↓`          | Navigate                                         |
-| `Space/Enter` | Toggle local/package extension on/off            |
-| `S`           | Save changes                                     |
-| `Enter` / `A` | Actions on selected package (update/remove/view) |
-| `u`           | Update selected package directly                 |
-| `X`           | Remove selected item (package/local extension)   |
-| `i`           | Quick install by source                          |
-| `f`           | Quick search                                     |
-| `U`           | Update all packages                              |
-| `t`           | Auto-update wizard                               |
-| `P` / `M`     | Quick actions palette                            |
-| `R`           | Browse remote packages                           |
-| `?` / `H`     | Help                                             |
-| `Esc`         | Exit                                             |
+| Key           | Action                                                |
+| ------------- | ----------------------------------------------------- |
+| `↑↓`          | Navigate                                              |
+| `Space/Enter` | Toggle local extension on/off                         |
+| `S`           | Save local extension changes                          |
+| `Enter` / `A` | Actions on selected package (configure/update/remove) |
+| `c`           | Configure selected package extensions                 |
+| `u`           | Update selected package directly                      |
+| `X`           | Remove selected item (package/local extension)        |
+| `i`           | Quick install by source                               |
+| `f`           | Quick search                                          |
+| `U`           | Update all packages                                   |
+| `t`           | Auto-update wizard                                    |
+| `P` / `M`     | Quick actions palette                                 |
+| `R`           | Browse remote packages                                |
+| `?` / `H`     | Help                                                  |
+| `Esc`         | Exit                                                  |
 
 ### Commands
 
@@ -134,7 +140,9 @@ Examples:
 
 ## Tips
 
-- **Staged changes**: Toggle extensions on/off, then press `S` to apply all at once. A `*` shows pending changes.
+- **Staged local changes**: Toggle local extensions on/off, then press `S` to apply all at once.
+- **Package extension config**: Select a package and press `c` (or Enter/A → Configure) to enable/disable individual package entrypoints.
+  - After saving package extension config, restart pi to fully apply changes.
 - **Two install modes**:
   - **Managed** (npm): Auto-updates with `pi update`, stored in pi's package cache
   - **Local** (standalone): Copies to `~/.pi/agent/extensions/{package}/`, supports multi-file extensions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extmgr",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Enhanced UX for managing local Pi extensions and community packages",
   "keywords": [
     "pi-package",
@@ -57,7 +57,7 @@
   "author": "ayagmar",
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.5.0"
   },
   "repository": {
     "type": "git",

package/src/commands/registry.ts

@@ -132,16 +132,20 @@ const COMMAND_DEFINITIONS: Record<CommandId, CommandDefinition> = {
   },
 };
 
-const COMMAND_ALIAS_TO_ID: Record<string, CommandId> = Object.values(COMMAND_DEFINITIONS).reduce(
-  (acc, def) => {
-    acc[def.id] = def.id;
+function buildCommandAliasMap(
+  definitions: Record<CommandId, CommandDefinition>
+): Record<string, CommandId> {
+  const map: Record<string, CommandId> = {};
+  for (const def of Object.values(definitions)) {
+    map[def.id] = def.id;
     for (const alias of def.aliases ?? []) {
-      acc[alias] = def.id;
+      map[alias] = def.id;
     }
-    return acc;
-  },
-  {} as Record<string, CommandId>
-);
+  }
+  return map;
+}
+
+const COMMAND_ALIAS_TO_ID: Record<string, CommandId> = buildCommandAliasMap(COMMAND_DEFINITIONS);
 
 export function resolveCommand(tokens: string[]): { id: CommandId; args: string[] } | undefined {
   if (tokens.length === 0) {

package/src/constants.ts

@@ -1,48 +1,79 @@
 /**
  * Constants for pi-extmgr
+ *
+ * All time values are in milliseconds unless otherwise noted.
  */
 
+/** File extension suffix used to disable extensions (e.g., `extension.ts.disabled`) */
 export const DISABLED_SUFFIX = ".disabled";
+
+/** Number of items to display per page in paginated views */
 export const PAGE_SIZE = 20;
-export const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+/** Default cache time-to-live: 5 minutes */
+export const CACHE_TTL = 5 * 60 * 1000;
 
 /**
  * Timeout values for various operations (in milliseconds)
+ *
+ * These values balance user experience with reliability.
+ * Network operations get shorter timeouts, file operations get longer ones.
  */
 export const TIMEOUTS = {
-  npmSearch: 20000,
-  npmView: 10000,
-  packageInstall: 180000,
-  packageUpdate: 120000,
-  packageRemove: 60000,
-  listPackages: 10000,
-  fetchPackageInfo: 30000,
-  extractPackage: 30000,
-  weeklyDownloads: 5000,
+  /** npm registry search timeout */
+  npmSearch: 20_000,
+  /** npm package metadata lookup timeout */
+  npmView: 10_000,
+  /** Full package installation timeout (3 minutes) */
+  packageInstall: 180_000,
+  /** Package update timeout (2 minutes) */
+  packageUpdate: 120_000,
+  /** Bulk package update timeout (5 minutes) */
+  packageUpdateAll: 300_000,
+  /** Package removal timeout (1 minute) */
+  packageRemove: 60_000,
+  /** Package listing timeout */
+  listPackages: 10_000,
+  /** Package metadata fetch timeout */
+  fetchPackageInfo: 30_000,
+  /** Package extraction timeout */
+  extractPackage: 30_000,
+  /** Weekly download stats timeout */
+  weeklyDownloads: 5_000,
 } as const;
 
 export type TimeoutKey = keyof typeof TIMEOUTS;
 
 /**
- * Cache limits (in milliseconds or count)
+ * Cache limits and TTL values (in milliseconds or count)
  */
 export const CACHE_LIMITS = {
+  /** Maximum number of package info entries to cache */
   packageInfoMaxSize: 100,
-  metadataTTL: 24 * 60 * 60 * 1000, // 24 hours
-  searchTTL: 15 * 60 * 1000, // 15 minutes
-  packageInfoTTL: 6 * 60 * 60 * 1000, // 6 hours
+  /** Metadata cache TTL: 24 hours */
+  metadataTTL: 24 * 60 * 60 * 1000,
+  /** Search results cache TTL: 15 minutes */
+  searchTTL: 15 * 60 * 1000,
+  /** Package info cache TTL: 6 hours */
+  packageInfoTTL: 6 * 60 * 60 * 1000,
 } as const;
 
 export type CacheLimitKey = keyof typeof CACHE_LIMITS;
 
 /**
  * UI Constants
+ *
+ * These values control the user interface behavior and appearance.
  */
 export const UI = {
+  /** Maximum height for scrollable lists in terminal rows */
   maxListHeight: 16,
-  searchThreshold: 8, // Enable search when items exceed this
-  confirmTimeout: 30000,
-  longConfirmTimeout: 60000,
+  /** Minimum number of items before enabling search functionality */
+  searchThreshold: 8,
+  /** Default confirmation dialog timeout: 30 seconds */
+  confirmTimeout: 30_000,
+  /** Extended confirmation timeout for destructive operations: 1 minute */
+  longConfirmTimeout: 60_000,
 } as const;
 
 export type UIKey = keyof typeof UI;

package/src/packages/extensions.ts

@@ -1,9 +1,13 @@
-import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
-import { dirname, join, relative, resolve } from "node:path";
+import { mkdir, readFile, writeFile, rename, rm, readdir } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import { dirname, join, matchesGlob, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import type { InstalledPackage, PackageExtensionEntry, Scope, State } from "../types/index.js";
+import { parseNpmSource } from "../utils/format.js";
 import { fileExists, readSummary } from "../utils/fs.js";
 
 interface PackageSettingsObject {
@@ -15,6 +19,9 @@ interface SettingsFile {
   packages?: (string | PackageSettingsObject)[];
 }
 
+const execFileAsync = promisify(execFile);
+let globalNpmRootCache: string | null | undefined;
+
 function normalizeRelativePath(value: string): string {
   const normalized = value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
   return normalized;
@@ -37,11 +44,69 @@ function normalizePackageRootCandidate(candidate: string): string {
   return resolved;
 }
 
-function toPackageRoot(pkg: InstalledPackage, cwd: string): string | undefined {
+async function getGlobalNpmRoot(): Promise<string | undefined> {
+  if (globalNpmRootCache !== undefined) {
+    return globalNpmRootCache ?? undefined;
+  }
+
+  try {
+    const { stdout } = await execFileAsync("npm", ["root", "-g"], {
+      timeout: 2_000,
+      windowsHide: true,
+    });
+    const root = stdout.trim();
+    globalNpmRootCache = root || null;
+  } catch {
+    globalNpmRootCache = null;
+  }
+
+  return globalNpmRootCache ?? undefined;
+}
+
+async function resolveNpmPackageRoot(
+  pkg: InstalledPackage,
+  cwd: string
+): Promise<string | undefined> {
+  const parsed = parseNpmSource(pkg.source);
+  if (!parsed?.name) {
+    return undefined;
+  }
+
+  const packageName = parsed.name;
+  const projectCandidates = [
+    join(cwd, ".pi", "npm", "node_modules", packageName),
+    join(cwd, "node_modules", packageName),
+  ];
+
+  const packageDir = process.env.PI_PACKAGE_DIR || join(homedir(), ".pi", "agent");
+  const globalCandidates = [join(packageDir, "npm", "node_modules", packageName)];
+
+  const npmGlobalRoot = await getGlobalNpmRoot();
+  if (npmGlobalRoot) {
+    globalCandidates.unshift(join(npmGlobalRoot, packageName));
+  }
+
+  const candidates =
+    pkg.scope === "project" ? projectCandidates : [...globalCandidates, ...projectCandidates];
+
+  for (const candidate of candidates) {
+    if (await fileExists(join(candidate, "package.json"))) {
+      return candidate;
+    }
+  }
+
+  return undefined;
+}
+
+async function toPackageRoot(pkg: InstalledPackage, cwd: string): Promise<string | undefined> {
   if (pkg.resolvedPath) {
     return normalizePackageRootCandidate(pkg.resolvedPath);
   }
 
+  if (pkg.source.startsWith("npm:")) {
+    return resolveNpmPackageRoot(pkg, cwd);
+  }
+
   if (pkg.source.startsWith("file://")) {
     try {
       return normalizePackageRootCandidate(fileURLToPath(pkg.source));
@@ -141,23 +206,79 @@ async function writeSettingsFile(path: string, settings: SettingsFile): Promise<
   }
 }
 
+function safeMatchesGlob(targetPath: string, pattern: string): boolean {
+  try {
+    return matchesGlob(targetPath, pattern);
+  } catch {
+    return false;
+  }
+}
+
+function matchesFilterPattern(targetPath: string, pattern: string): boolean {
+  const normalizedPattern = normalizeRelativePath(pattern.trim());
+  if (!normalizedPattern) return false;
+  if (targetPath === normalizedPattern) return true;
+
+  return safeMatchesGlob(targetPath, normalizedPattern);
+}
+
 function getPackageFilterState(filters: string[] | undefined, extensionPath: string): State {
-  if (!filters || filters.length === 0) {
+  // Omitted key => all enabled (pi default).
+  if (filters === undefined) {
     return "enabled";
   }
 
+  // Explicit empty array => load none.
+  if (filters.length === 0) {
+    return "disabled";
+  }
+
   const normalizedTarget = normalizeRelativePath(extensionPath);
-  let state: State = "enabled";
+  const includePatterns: string[] = [];
+  const excludePatterns: string[] = [];
+  let markerOverride: State | undefined;
+
+  for (const rawToken of filters) {
+    const token = rawToken.trim();
+    if (!token) continue;
+
+    const prefix = token[0];
+
+    if (prefix === "+" || prefix === "-") {
+      const markerPath = normalizeRelativePath(token.slice(1));
+      if (markerPath === normalizedTarget) {
+        markerOverride = prefix === "+" ? "enabled" : "disabled";
+      }
+      continue;
+    }
+
+    if (prefix === "!") {
+      const pattern = normalizeRelativePath(token.slice(1));
+      if (pattern) {
+        excludePatterns.push(pattern);
+      }
+      continue;
+    }
+
+    const include = normalizeRelativePath(token);
+    if (include) {
+      includePatterns.push(include);
+    }
+  }
+
+  let enabled =
+    includePatterns.length === 0 ||
+    includePatterns.some((p) => matchesFilterPattern(normalizedTarget, p));
+
+  if (enabled && excludePatterns.some((p) => matchesFilterPattern(normalizedTarget, p))) {
+    enabled = false;
+  }
 
-  for (const token of filters) {
-    if (!token || (token[0] !== "+" && token[0] !== "-")) continue;
-    const sign = token[0];
-    const path = normalizeRelativePath(token.slice(1));
-    if (path !== normalizedTarget) continue;
-    state = sign === "+" ? "enabled" : "disabled";
+  if (markerOverride !== undefined) {
+    enabled = markerOverride === "enabled";
   }
 
-  return state;
+  return enabled ? "enabled" : "disabled";
 }
 
 async function getPackageExtensionState(
@@ -185,26 +306,131 @@ async function getPackageExtensionState(
   return getPackageFilterState(entry.extensions, extensionPath);
 }
 
-async function discoverEntrypoints(packageRoot: string): Promise<string[]> {
+function isExtensionEntrypointPath(path: string): boolean {
+  return /\.(ts|js)$/i.test(path);
+}
+
+function hasGlobMagic(path: string): boolean {
+  return /[*?{}[\]]/.test(path);
+}
+
+function isSafeRelativePath(path: string): boolean {
+  return path !== "" && path !== ".." && !path.startsWith("../") && !path.includes("/../");
+}
+
+function selectDirectoryFiles(allFiles: string[], directoryPath: string): string[] {
+  const prefix = `${directoryPath}/`;
+  return allFiles.filter((file) => file.startsWith(prefix));
+}
+
+function applySelection(selected: Set<string>, files: Iterable<string>, exclude: boolean): void {
+  for (const file of files) {
+    if (exclude) {
+      selected.delete(file);
+    } else {
+      selected.add(file);
+    }
+  }
+}
+
+async function collectExtensionFilesFromDir(
+  packageRoot: string,
+  startDir: string
+): Promise<string[]> {
+  const collected: string[] = [];
+
+  let entries: Dirent[];
+  try {
+    entries = await readdir(startDir, { withFileTypes: true });
+  } catch {
+    return collected;
+  }
+
+  for (const entry of entries) {
+    const absolutePath = join(startDir, entry.name);
+
+    if (entry.isDirectory()) {
+      collected.push(...(await collectExtensionFilesFromDir(packageRoot, absolutePath)));
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const relativePath = normalizeRelativePath(relative(packageRoot, absolutePath));
+    if (isExtensionEntrypointPath(relativePath)) {
+      collected.push(relativePath);
+    }
+  }
+
+  return collected;
+}
+
+async function resolveManifestExtensionEntries(
+  packageRoot: string,
+  entries: string[]
+): Promise<string[]> {
+  const selected = new Set<string>();
+  const allFiles = await collectExtensionFilesFromDir(packageRoot, packageRoot);
+
+  for (const rawToken of entries) {
+    const token = rawToken.trim();
+    if (!token) continue;
+
+    const exclude = token.startsWith("!");
+    const normalizedToken = normalizeRelativePath(exclude ? token.slice(1) : token);
+    const pattern = normalizedToken.replace(/[\\/]+$/g, "");
+    if (!isSafeRelativePath(pattern)) {
+      continue;
+    }
+
+    if (hasGlobMagic(pattern)) {
+      const matchedFiles = allFiles.filter((file) => matchesFilterPattern(file, pattern));
+      applySelection(selected, matchedFiles, exclude);
+      continue;
+    }
+
+    const directoryFiles = selectDirectoryFiles(allFiles, pattern);
+    if (directoryFiles.length > 0) {
+      applySelection(selected, directoryFiles, exclude);
+      continue;
+    }
+
+    if (isExtensionEntrypointPath(pattern)) {
+      applySelection(selected, [pattern], exclude);
+    }
+  }
+
+  return Array.from(selected).sort((a, b) => a.localeCompare(b));
+}
+
+export async function resolveManifestExtensionEntrypoints(
+  packageRoot: string
+): Promise<string[] | undefined> {
   const packageJsonPath = join(packageRoot, "package.json");
-  let manifestExtensions: string[] | undefined;
 
+  let parsed: { pi?: { extensions?: unknown } };
   try {
     const raw = await readFile(packageJsonPath, "utf8");
-    const parsed = JSON.parse(raw) as { pi?: { extensions?: unknown } };
-    const ext = parsed.pi?.extensions;
-    if (Array.isArray(ext)) {
-      const entries = ext.filter((value): value is string => typeof value === "string");
-      if (entries.length > 0) {
-        manifestExtensions = entries;
-      }
-    }
+    parsed = JSON.parse(raw) as { pi?: { extensions?: unknown } };
   } catch {
-    // Ignore invalid/missing package.json and fall back.
+    return undefined;
+  }
+
+  const extensions = parsed.pi?.extensions;
+  if (!Array.isArray(extensions)) {
+    return undefined;
   }
 
-  if (manifestExtensions && manifestExtensions.length > 0) {
-    return manifestExtensions.map((entry) => normalizeRelativePath(entry));
+  const entries = extensions.filter((value): value is string => typeof value === "string");
+  return resolveManifestExtensionEntries(packageRoot, entries);
+}
+
+async function discoverEntrypoints(packageRoot: string): Promise<string[]> {
+  const manifestEntrypoints = await resolveManifestExtensionEntrypoints(packageRoot);
+  if (manifestEntrypoints !== undefined) {
+    return manifestEntrypoints;
   }
 
   const indexTs = join(packageRoot, "index.ts");
@@ -227,7 +453,7 @@ export async function discoverPackageExtensions(
   const entries: PackageExtensionEntry[] = [];
 
   for (const pkg of packages) {
-    const packageRoot = toPackageRoot(pkg, cwd);
+    const packageRoot = await toPackageRoot(pkg, cwd);
     if (!packageRoot) continue;
 
     const extensionPaths = await discoverEntrypoints(packageRoot);
@@ -319,8 +545,3 @@ export async function setPackageExtensionState(
     };
   }
 }
-
-export function toProjectRelativePath(path: string, cwd: string): string {
-  const rel = relative(cwd, path);
-  return rel.startsWith("..") ? path : normalizeRelativePath(rel);
-}

package/src/packages/install.ts

@@ -1,13 +1,14 @@
 /**
  * Package installation logic
  */
-import { mkdir, rm, writeFile, cp, readFile } from "node:fs/promises";
+import { mkdir, rm, writeFile, cp } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import { normalizePackageSource } from "../utils/format.js";
 import { fileExists } from "../utils/fs.js";
 import { clearSearchCache, isSourceInstalled } from "./discovery.js";
+import { resolveManifestExtensionEntrypoints } from "./extensions.js";
 import { waitForCondition } from "../utils/retry.js";
 import { logPackageInstall } from "../utils/history.js";
 import { clearUpdatesAvailable } from "../utils/settings.js";
@@ -48,18 +49,20 @@ function getExtensionInstallDir(ctx: ExtensionCommandContext, scope: InstallScop
   return join(homedir(), ".pi", "agent", "extensions");
 }
 
+interface GithubUrlInfo {
+  owner: string;
+  repo: string;
+  branch: string;
+  filePath: string;
+}
+
 /**
  * Safely extracts regex match groups with validation
  */
-function safeExtractGithubMatch(
-  match: RegExpMatchArray | null
-): { owner: string; repo: string; branch: string; filePath: string } | undefined {
+function safeExtractGithubMatch(match: RegExpMatchArray | null): GithubUrlInfo | undefined {
   if (!match) return undefined;
 
-  const owner = match[1];
-  const repo = match[2];
-  const branch = match[3];
-  const filePath = match[4];
+  const [, owner, repo, branch, filePath] = match;
 
   if (!owner || !repo || !branch || !filePath) {
     return undefined;
@@ -68,29 +71,15 @@ function safeExtractGithubMatch(
   return { owner, repo, branch, filePath };
 }
 
-function normalizeRelativePath(value: string): string {
-  return value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
-}
-
 async function hasStandaloneEntrypoint(packageRoot: string): Promise<boolean> {
-  try {
-    const manifestPath = join(packageRoot, "package.json");
-    const raw = await readFile(manifestPath, "utf8");
-    const parsed = JSON.parse(raw) as { pi?: { extensions?: unknown } };
-    const declared = parsed.pi?.extensions;
-
-    if (Array.isArray(declared) && declared.length > 0) {
-      for (const entry of declared) {
-        if (typeof entry !== "string" || !entry.trim()) continue;
-        const candidate = join(packageRoot, normalizeRelativePath(entry));
-        if (await fileExists(candidate)) {
-          return true;
-        }
+  const declared = await resolveManifestExtensionEntrypoints(packageRoot);
+  if (declared !== undefined) {
+    for (const path of declared) {
+      if (await fileExists(join(packageRoot, path))) {
+        return true;
       }
-      return false;
     }
-  } catch {
-    // Ignore invalid/missing manifest and fall back to conventional entrypoints.
+    return false;
   }
 
   return (