pi-extmgr 0.1.22 → 0.1.24

package/README.md

@@ -26,6 +26,7 @@ Requires Node.js `>=22.5.0`.
   - Scope indicators (global/project), status indicators, update badges
 - **Package extension configuration panel**
   - Configure individual extension entrypoints inside an installed package (`c` on package row)
+  - Works with manifest-declared entrypoints and conventional `extensions/` package layouts
   - Persists to package filters in `settings.json` (no manual JSON editing)
 - **Safe staged local extension toggles**
   - Toggle with `Space/Enter`, apply with `S`
@@ -36,15 +37,16 @@ Requires Node.js `>=22.5.0`.
 - **Remote discovery and install**
   - npm search/browse with pagination
   - Install by source (`npm:`, `git:`, `https://`, `ssh://`, `git@...`, local path)
-  - Supports direct GitHub `.ts` installs and local standalone install mode
+  - Supports direct GitHub `.ts` installs and standalone local install for self-contained packages
 - **Auto-update**
   - Interactive wizard (`t` in manager, or `/extensions auto-update`)
   - Persistent schedule restored on startup and session switch
-  - Background checks + status bar updates
+  - Background checks + status bar updates for installed npm packages
 - **Operational visibility**
   - Session history (`/extensions history`)
-  - Cache controls (`/extensions clear-cache`)
+  - Cache controls (`/extensions clear-cache` clears persistent + runtime extmgr caches)
   - Status line summary (`pkg count • auto-update • known updates`)
+  - History now records local extension deletions and auto-update configuration changes
 - **Interactive + non-interactive support**
   - Works in TUI and non-UI modes
   - Non-interactive commands for list/install/remove/update/auto-update
@@ -91,9 +93,9 @@ Open the manager:
 /extensions remove [source]      # Remove package
 /extensions uninstall [source]   # Alias: remove
 /extensions update [source]      # Update one package (or all when omitted)
-/extensions auto-update [every]  # No arg opens wizard in UI; accepts 1d, 1w, never, etc.
+/extensions auto-update [every]  # No arg opens wizard in UI; accepts 1d, 1w, 1mo, never, etc.
 /extensions history [options]    # View change history (supports filters)
-/extensions clear-cache          # Clear metadata cache
+/extensions clear-cache          # Clear persistent + runtime extmgr caches
 ```
 
 ### Non-interactive mode
@@ -107,23 +109,33 @@ When Pi is running without UI, extmgr still supports command-driven workflows:
 - `/extensions update [source]`
 - `/extensions history [options]`
 - `/extensions auto-update <duration>`
+  - Use `1mo` for monthly schedules (`/extensions history --since <duration>` also accepts `1mo`; `30m`/`24h` are just lookback examples)
 
-Remote browsing/search menus require interactive mode.
+Remote browsing/search menus require the full interactive TUI.
+
+### RPC / limited-UI mode
+
+In RPC mode, dialog-based commands still work, but the custom TUI panels do not:
+
+- `/extensions` falls back to read-only local/package lists
+- `/extensions installed` lists packages directly
+- remote browsing/search panels require the full interactive TUI
+- package extension configuration requires the full interactive TUI
 
 History options (works in non-interactive mode too):
 
 - `--limit <n>`
-- `--action <extension_toggle|package_install|package_update|package_remove|cache_clear>`
+- `--action <extension_toggle|extension_delete|package_install|package_update|package_remove|cache_clear|auto_update_config>`
 - `--success` / `--failed`
 - `--package <query>`
-- `--since <duration>` (e.g. `30m`, `24h`, `7d`, `1mo`)
-- `--global` (non-interactive mode only; reads all persisted sessions)
+- `--since <duration>` (e.g. `30m`, `24h`, `7d`, `1mo`; `1mo` is supported for monthly lookbacks)
+- `--global` (non-interactive mode only; reads all persisted sessions under `~/.pi/agent/sessions`)
 
 Examples:
 
 - `/extensions history --failed --limit 50`
 - `/extensions history --action package_update --since 7d`
-- `/extensions history --global --package extmgr --since 24h`
+- `/extensions history --global --package extmgr --since 1mo`
 
 ### Install sources
 
@@ -144,9 +156,10 @@ Examples:
 - **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
+  - **Managed** (npm): Auto-updates with `pi update`, stored in pi's package cache, supports Pi package manifest/convention loading
+  - **Local** (standalone): Copies to `~/.pi/agent/extensions/{package}/`, so it only accepts runnable standalone layouts (manifest-declared/root entrypoints), requires `tar` on `PATH`, and rejects packages whose runtime `dependencies` are not already bundled with the package contents
 - **Auto-update schedule is persistent**: `/extensions auto-update 1d` stays active across future Pi sessions and is restored when switching sessions.
+- **Auto-update coverage is npm-only today**: extmgr checks update availability for managed npm packages; git/local installs are not included in the background update badge yet.
 - **Settings/cache writes are hardened**: extmgr serializes writes and uses safe file replacement to reduce JSON corruption issues.
 - **Invalid JSON is handled safely**: malformed `auto-update.json` / metadata cache files are backed up and reset; invalid `.pi/settings.json` is not overwritten during package-extension toggles.
 - **Reload is built-in**: When extmgr asks to reload, it calls `ctx.reload()` directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extmgr",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Enhanced UX for managing local Pi extensions and community packages",
   "keywords": [
     "pi-package",

package/src/commands/auto-update.ts

@@ -54,7 +54,7 @@ export async function handleAutoUpdateSubcommand(
       "  3d      - Check every 3 days",
       "  1w      - Check weekly",
       "  2w      - Check every 2 weeks",
-      "  1m      - Check monthly",
+      "  1mo     - Check monthly (1m also works)",
       "  daily   - Check daily (alias)",
       "  weekly  - Check weekly (alias)",
     ];

package/src/commands/cache.ts

@@ -1,4 +1,6 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { clearSearchCache } from "../packages/discovery.js";
+import { clearRemotePackageInfoCache } from "../ui/remote.js";
 import { clearCache } from "../utils/cache.js";
 import { logCacheClear } from "../utils/history.js";
 import { notify } from "../utils/notify.js";
@@ -10,8 +12,10 @@ export async function clearMetadataCacheCommand(
 ): Promise<void> {
   try {
     await clearCache();
+    clearSearchCache();
+    clearRemotePackageInfoCache();
     logCacheClear(pi, true);
-    notify(ctx, "Metadata cache cleared.", "info");
+    notify(ctx, "Metadata and in-memory extmgr caches cleared.", "info");
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     logCacheClear(pi, false, message);

package/src/commands/history.ts

@@ -11,10 +11,12 @@ import { formatListOutput } from "../utils/ui-helpers.js";
 
 const HISTORY_ACTIONS: ChangeAction[] = [
   "extension_toggle",
+  "extension_delete",
   "package_install",
   "package_update",
   "package_remove",
   "cache_clear",
+  "auto_update_config",
 ];
 
 interface ParsedHistoryArgs {
@@ -187,12 +189,12 @@ function showHistoryHelp(ctx: ExtensionCommandContext): void {
     "Options:",
     "  --limit <n>      Maximum entries to show (default: 20)",
     "  --action <type>  Filter by action",
-    "                   extension_toggle | package_install | package_update | package_remove | cache_clear",
+    `                   ${HISTORY_ACTIONS.join(" | ")}`,
     "  --success        Show only successful entries",
     "  --failed         Show only failed entries",
     "  --package <q>    Filter by package/source/extension id",
     "  --since <d>      Show only entries newer than duration (e.g. 30m, 24h, 7d, 1mo)",
-    "  --global         Read all persisted sessions (non-interactive mode only)",
+    "  --global         Read all persisted sessions from ~/.pi/agent/sessions (non-interactive mode only)",
     "",
     "Examples:",
     "  /extensions history --failed --limit 50",

package/src/commands/registry.ts

@@ -34,7 +34,7 @@ function showNonInteractiveHelp(ctx: ExtensionCommandContext): void {
     "  /extensions remove <source>  - Remove a package",
     "  /extensions update [source]  - Update one package or all packages",
     "  /extensions history [opts]   - Show history (supports filters)",
-    "  /extensions auto-update <d>  - Configure auto-update (e.g. 1d, 1w, never)",
+    "  /extensions auto-update <d>  - Configure auto-update (e.g. 1d, 1w, 1mo, never)",
     "",
     "History examples:",
     "  /extensions history --failed --limit 50",

package/src/index.ts

@@ -70,12 +70,17 @@ export default function extensionsManager(pi: ExtensionAPI) {
     // Restore persisted auto-update config into session entries so sync lookups are valid.
     await hydrateAutoUpdateConfig(pi, ctx);
 
-    if (!ctx.hasUI) return;
+    if (!ctx.hasUI) {
+      stopAutoUpdateTimer();
+      return;
+    }
 
     const config = getAutoUpdateConfig(ctx);
     if (config.enabled && config.intervalMs > 0) {
       const getCtx: ContextProvider = () => ctx;
       startAutoUpdateTimer(pi, getCtx, createAutoUpdateNotificationHandler(ctx));
+    } else {
+      stopAutoUpdateTimer();
     }
 
     setImmediate(() => {

package/src/packages/discovery.ts

@@ -12,7 +12,13 @@ import type { InstalledPackage, NpmPackage, SearchCache } from "../types/index.j
 import { CACHE_TTL, TIMEOUTS } from "../constants.js";
 import { readSummary } from "../utils/fs.js";
 import { parseNpmSource } from "../utils/format.js";
-import { getPackageSourceKind, splitGitRepoAndRef } from "../utils/package-source.js";
+import {
+  getPackageSourceKind,
+  normalizePackageIdentity,
+  splitGitRepoAndRef,
+  stripGitSourcePrefix,
+} from "../utils/package-source.js";
+import { execNpm } from "../utils/npm-exec.js";
 
 let searchCache: SearchCache | null = null;
 
@@ -67,9 +73,8 @@ export async function searchNpmPackages(
     ctx.ui.notify(`Searching npm for "${query}"...`, "info");
   }
 
-  const res = await pi.exec("npm", ["search", "--json", `--searchlimit=${searchLimit}`, query], {
+  const res = await execNpm(pi, ["search", "--json", `--searchlimit=${searchLimit}`, query], ctx, {
     timeout: TIMEOUTS.npmSearch,
-    cwd: ctx.cwd,
   });
 
   if (res.code !== 0) {
@@ -117,8 +122,11 @@ function sanitizeListSourceSuffix(source: string): string {
     .trim();
 }
 
-function normalizeSourceIdentity(source: string): string {
-  return sanitizeListSourceSuffix(source).replace(/\\/g, "/").toLowerCase();
+function getInstalledPackageIdentity(pkg: InstalledPackage): string {
+  return normalizePackageIdentity(
+    pkg.source,
+    pkg.resolvedPath ? { resolvedPath: pkg.resolvedPath } : undefined
+  );
 }
 
 function isScopeHeader(lowerTrimmed: string, scope: "global" | "project"): boolean {
@@ -170,12 +178,8 @@ function parseResolvedPathLine(line: string): string | undefined {
   return undefined;
 }
 
-function parseInstalledPackagesOutputInternal(
-  text: string,
-  options?: { dedupeBySource?: boolean }
-): InstalledPackage[] {
+function parseInstalledPackagesOutputInternal(text: string): InstalledPackage[] {
   const packages: InstalledPackage[] = [];
-  const seenSources = new Set<string>();
 
   const lines = text.split("\n");
   let currentScope: "global" | "project" = "global";
@@ -211,15 +215,6 @@ function parseInstalledPackagesOutputInternal(
     if (!looksLikePackageSource(candidate)) continue;
 
     const source = sanitizeListSourceSuffix(candidate);
-    if (options?.dedupeBySource !== false) {
-      const sourceIdentity = normalizeSourceIdentity(source);
-      if (seenSources.has(sourceIdentity)) {
-        currentPackage = undefined;
-        continue;
-      }
-      seenSources.add(sourceIdentity);
-    }
-
     const { name, version } = parsePackageNameAndVersion(source);
 
     const pkg: InstalledPackage = { source, name, scope: currentScope };
@@ -233,8 +228,34 @@ function parseInstalledPackagesOutputInternal(
   return packages;
 }
 
+function shouldReplaceInstalledPackage(
+  current: InstalledPackage | undefined,
+  candidate: InstalledPackage
+): boolean {
+  if (!current) {
+    return true;
+  }
+
+  if (current.scope !== candidate.scope) {
+    return candidate.scope === "project";
+  }
+
+  return false;
+}
+
 export function parseInstalledPackagesOutput(text: string): InstalledPackage[] {
-  return parseInstalledPackagesOutputInternal(text, { dedupeBySource: true });
+  const parsed = parseInstalledPackagesOutputInternal(text);
+  const deduped = new Map<string, InstalledPackage>();
+
+  for (const pkg of parsed) {
+    const identity = getInstalledPackageIdentity(pkg);
+    const current = deduped.get(identity);
+    if (shouldReplaceInstalledPackage(current, pkg)) {
+      deduped.set(identity, pkg);
+    }
+  }
+
+  return Array.from(deduped.values());
 }
 
 /**
@@ -252,10 +273,10 @@ export async function isSourceInstalled(
     if (res.code !== 0) return false;
 
     const installed = parseInstalledPackagesOutputAllScopes(res.stdout || "");
-    const expected = normalizeSourceIdentity(source);
+    const expected = normalizePackageIdentity(source);
 
     return installed.some((pkg) => {
-      if (normalizeSourceIdentity(pkg.source) !== expected) {
+      if (getInstalledPackageIdentity(pkg) !== expected) {
         return false;
       }
       return options?.scope ? pkg.scope === options.scope : true;
@@ -265,8 +286,14 @@ export async function isSourceInstalled(
   }
 }
 
+/**
+ * parseInstalledPackagesOutputAllScopes returns the raw parsed entries from
+ * parseInstalledPackagesOutputInternal without deduplication or scope merging.
+ * Prefer parseInstalledPackagesOutput for user-facing lists, since it applies
+ * deduplication and normalized scope selection.
+ */
 export function parseInstalledPackagesOutputAllScopes(text: string): InstalledPackage[] {
-  return parseInstalledPackagesOutputInternal(text, { dedupeBySource: false });
+  return parseInstalledPackagesOutputInternal(text);
 }
 
 function extractGitPackageName(repoSpec: string): string {
@@ -305,7 +332,7 @@ function parsePackageNameAndVersion(fullSource: string): {
 
   const sourceKind = getPackageSourceKind(fullSource);
   if (sourceKind === "git") {
-    const gitSpec = fullSource.startsWith("git:") ? fullSource.slice(4) : fullSource;
+    const gitSpec = stripGitSourcePrefix(fullSource);
     const { repo } = splitGitRepoAndRef(gitSpec);
     return { name: extractGitPackageName(repo) };
   }
@@ -375,9 +402,8 @@ async function fetchPackageSize(
 
   try {
     // Try to get unpacked size from npm view
-    const res = await pi.exec("npm", ["view", pkgName, "dist.unpackedSize", "--json"], {
+    const res = await execNpm(pi, ["view", pkgName, "dist.unpackedSize", "--json"], ctx, {
       timeout: TIMEOUTS.npmView,
-      cwd: ctx.cwd,
     });
     if (res.code === 0) {
       try {
@@ -441,9 +467,8 @@ async function addPackageMetadata(
                 if (cached?.description) {
                   pkg.description = cached.description;
                 } else {
-                  const res = await pi.exec("npm", ["view", pkgName, "description", "--json"], {
+                  const res = await execNpm(pi, ["view", pkgName, "description", "--json"], ctx, {
                     timeout: TIMEOUTS.npmView,
-                    cwd: ctx.cwd,
                   });
                   if (res.code === 0) {
                     try {

package/src/packages/extensions.ts

@@ -9,6 +9,7 @@ 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";
+import { resolveNpmCommand } from "../utils/npm-exec.js";
 
 interface PackageSettingsObject {
   source: string;
@@ -19,6 +20,14 @@ interface SettingsFile {
   packages?: (string | PackageSettingsObject)[];
 }
 
+export interface PackageManifest {
+  name?: string;
+  dependencies?: Record<string, string>;
+  pi?: {
+    extensions?: unknown;
+  };
+}
+
 const execFileAsync = promisify(execFile);
 let globalNpmRootCache: string | null | undefined;
 
@@ -50,7 +59,8 @@ async function getGlobalNpmRoot(): Promise<string | undefined> {
   }
 
   try {
-    const { stdout } = await execFileAsync("npm", ["root", "-g"], {
+    const npmCommand = resolveNpmCommand(["root", "-g"]);
+    const { stdout } = await execFileAsync(npmCommand.command, npmCommand.args, {
       timeout: 2_000,
       windowsHide: true,
     });
@@ -206,6 +216,125 @@ async function writeSettingsFile(path: string, settings: SettingsFile): Promise<
   }
 }
 
+function findPackageSettingsIndex(
+  packages: SettingsFile["packages"] extends infer T ? NonNullable<T> : never,
+  normalizedSource: string
+): number {
+  return packages.findIndex((pkg) => {
+    if (typeof pkg === "string") {
+      return normalizeSource(pkg) === normalizedSource;
+    }
+    return normalizeSource(pkg.source) === normalizedSource;
+  });
+}
+
+function toPackageSettingsObject(
+  existing: string | PackageSettingsObject | undefined,
+  packageSource: string
+): PackageSettingsObject {
+  if (typeof existing === "string") {
+    return { source: existing, extensions: [] };
+  }
+
+  if (existing && typeof existing.source === "string") {
+    return {
+      source: existing.source,
+      extensions: Array.isArray(existing.extensions) ? [...existing.extensions] : [],
+    };
+  }
+
+  return { source: packageSource, extensions: [] };
+}
+
+function updateExtensionMarkers(
+  existingTokens: string[] | undefined,
+  changes: ReadonlyMap<string, State>
+): string[] {
+  const nextTokens: string[] = [];
+
+  for (const token of existingTokens ?? []) {
+    if (typeof token !== "string") {
+      continue;
+    }
+
+    if (token[0] !== "+" && token[0] !== "-") {
+      nextTokens.push(token);
+      continue;
+    }
+
+    const tokenPath = normalizeRelativePath(token.slice(1));
+    if (!changes.has(tokenPath)) {
+      nextTokens.push(token);
+    }
+  }
+
+  for (const [extensionPath, target] of Array.from(changes.entries()).sort((a, b) =>
+    a[0].localeCompare(b[0])
+  )) {
+    nextTokens.push(`${target === "enabled" ? "+" : "-"}${extensionPath}`);
+  }
+
+  return nextTokens;
+}
+
+export async function validatePackageExtensionSettings(
+  scope: Scope,
+  cwd: string
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    await readSettingsFile(getSettingsPath(scope, cwd), { strict: true });
+    return { ok: true };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function applyPackageExtensionStateChanges(
+  packageSource: string,
+  scope: Scope,
+  changes: readonly { extensionPath: string; target: State }[],
+  cwd: string
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    if (changes.length === 0) {
+      return { ok: true };
+    }
+
+    const settingsPath = getSettingsPath(scope, cwd);
+    const settings = await readSettingsFile(settingsPath, { strict: true });
+    const normalizedSource = normalizeSource(packageSource);
+    const packages = [...(settings.packages ?? [])];
+    const index = findPackageSettingsIndex(packages, normalizedSource);
+    const packageEntry = toPackageSettingsObject(packages[index], packageSource);
+
+    const normalizedChanges = new Map<string, State>();
+    for (const change of changes) {
+      normalizedChanges.set(normalizeRelativePath(change.extensionPath), change.target);
+    }
+
+    packageEntry.extensions = updateExtensionMarkers(packageEntry.extensions, normalizedChanges);
+
+    if (index === -1) {
+      packages.push(packageEntry);
+    } else {
+      packages[index] = packageEntry;
+    }
+
+    settings.packages = packages;
+    await writeSettingsFile(settingsPath, settings);
+
+    return { ok: true };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 function safeMatchesGlob(targetPath: string, pattern: string): boolean {
   try {
     return matchesGlob(targetPath, pattern);
@@ -405,20 +534,29 @@ async function resolveManifestExtensionEntries(
   return Array.from(selected).sort((a, b) => a.localeCompare(b));
 }
 
-export async function resolveManifestExtensionEntrypoints(
+export async function readPackageManifest(
   packageRoot: string
-): Promise<string[] | undefined> {
+): Promise<PackageManifest | undefined> {
   const packageJsonPath = join(packageRoot, "package.json");
 
-  let parsed: { pi?: { extensions?: unknown } };
   try {
     const raw = await readFile(packageJsonPath, "utf8");
-    parsed = JSON.parse(raw) as { pi?: { extensions?: unknown } };
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return undefined;
+    }
+    return parsed as PackageManifest;
   } catch {
     return undefined;
   }
+}
 
-  const extensions = parsed.pi?.extensions;
+export async function resolveManifestExtensionEntrypoints(
+  packageRoot: string,
+  manifest?: PackageManifest
+): Promise<string[] | undefined> {
+  const parsed = manifest ?? (await readPackageManifest(packageRoot));
+  const extensions = parsed?.pi?.extensions;
   if (!Array.isArray(extensions)) {
     return undefined;
   }
@@ -427,12 +565,35 @@ export async function resolveManifestExtensionEntrypoints(
   return resolveManifestExtensionEntries(packageRoot, entries);
 }
 
-async function discoverEntrypoints(packageRoot: string): Promise<string[]> {
-  const manifestEntrypoints = await resolveManifestExtensionEntrypoints(packageRoot);
+async function resolveConventionExtensionEntrypoints(packageRoot: string): Promise<string[]> {
+  const extensionsDir = join(packageRoot, "extensions");
+  return collectExtensionFilesFromDir(packageRoot, extensionsDir);
+}
+
+export async function discoverPackageExtensionEntrypoints(
+  packageRoot: string,
+  options?: {
+    allowConventionDirectory?: boolean;
+    allowRootIndexFallback?: boolean;
+  }
+): Promise<string[]> {
+  const manifest = await readPackageManifest(packageRoot);
+  const manifestEntrypoints = await resolveManifestExtensionEntrypoints(packageRoot, manifest);
   if (manifestEntrypoints !== undefined) {
     return manifestEntrypoints;
   }
 
+  if (options?.allowConventionDirectory !== false) {
+    const conventionEntrypoints = await resolveConventionExtensionEntrypoints(packageRoot);
+    if (conventionEntrypoints.length > 0) {
+      return conventionEntrypoints.sort((a, b) => a.localeCompare(b));
+    }
+  }
+
+  if (options?.allowRootIndexFallback === false) {
+    return [];
+  }
+
   const indexTs = join(packageRoot, "index.ts");
   if (await fileExists(indexTs)) {
     return ["index.ts"];
@@ -456,7 +617,7 @@ export async function discoverPackageExtensions(
     const packageRoot = await toPackageRoot(pkg, cwd);
     if (!packageRoot) continue;
 
-    const extensionPaths = await discoverEntrypoints(packageRoot);
+    const extensionPaths = await discoverPackageExtensionEntrypoints(packageRoot);
     for (const extensionPath of extensionPaths) {
       const normalizedPath = normalizeRelativePath(extensionPath);
       const absolutePath = resolve(packageRoot, extensionPath);
@@ -490,58 +651,5 @@ export async function setPackageExtensionState(
   target: State,
   cwd: string
 ): Promise<{ ok: true } | { ok: false; error: string }> {
-  try {
-    const settingsPath = getSettingsPath(scope, cwd);
-    const settings = await readSettingsFile(settingsPath, { strict: true });
-
-    const normalizedSource = normalizeSource(packageSource);
-    const normalizedPath = normalizeRelativePath(extensionPath);
-    const marker = `${target === "enabled" ? "+" : "-"}${normalizedPath}`;
-
-    const packages = [...(settings.packages ?? [])];
-    let index = packages.findIndex((pkg) => {
-      if (typeof pkg === "string") {
-        return normalizeSource(pkg) === normalizedSource;
-      }
-      return normalizeSource(pkg.source) === normalizedSource;
-    });
-
-    let packageEntry: PackageSettingsObject;
-    if (index === -1) {
-      packageEntry = { source: packageSource, extensions: [marker] };
-      packages.push(packageEntry);
-      index = packages.length - 1;
-    } else {
-      const existing = packages[index];
-      if (typeof existing === "string") {
-        packageEntry = { source: existing, extensions: [] };
-      } else if (existing && typeof existing.source === "string") {
-        packageEntry = {
-          source: existing.source,
-          extensions: Array.isArray(existing.extensions) ? [...existing.extensions] : [],
-        };
-      } else {
-        packageEntry = { source: packageSource, extensions: [] };
-      }
-
-      packageEntry.extensions = (packageEntry.extensions ?? []).filter((token) => {
-        if (typeof token !== "string") return false;
-        if (token[0] !== "+" && token[0] !== "-") return true;
-        return normalizeRelativePath(token.slice(1)) !== normalizedPath;
-      });
-      packageEntry.extensions.push(marker);
-      packages[index] = packageEntry;
-    }
-
-    settings.packages = packages;
-
-    await writeSettingsFile(settingsPath, settings);
-
-    return { ok: true };
-  } catch (error) {
-    return {
-      ok: false,
-      error: error instanceof Error ? error.message : String(error),
-    };
-  }
+  return applyPackageExtensionStateChanges(packageSource, scope, [{ extensionPath, target }], cwd);
 }