@dex-ai/coding-agent 0.1.92

package/src/commands/extension.ts

@@ -0,0 +1,924 @@
+/**
+ * `dex extension` CLI subcommand — manage installed extensions.
+ *
+ * Each extension is installed in its own isolated directory with a dedicated
+ * package.json, lockfile, and node_modules/. No shared dependency tree.
+ *
+ * Commands:
+ *   dex extension install npm:<package>           Install from npm (user scope)
+ *   dex extension install file:<path>             Install from local path (user scope)
+ *   dex extension install npm:<package> --local   Install to project scope
+ *   dex extension uninstall <name>                Remove an extension
+ *   dex extension uninstall <name> --local        Remove from project scope
+ *   dex extension update <name>                   Update an extension
+ *   dex extension update --all                    Update all npm extensions
+ *   dex extension list                            List installed extensions
+ */
+
+import {
+	existsSync,
+	readFileSync,
+	writeFileSync,
+	mkdirSync,
+	readdirSync,
+	rmSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+/* ------------------------------------------------------------------ */
+/* Constants                                                            */
+/* ------------------------------------------------------------------ */
+
+const USER_EXTENSIONS_DIR = join(homedir(), ".dex", "extensions");
+const USER_PACKAGES_DIR = join(USER_EXTENSIONS_DIR, "packages");
+const USER_REGISTRY_PATH = join(USER_EXTENSIONS_DIR, "registry.json");
+
+function getProjectExtensionsDir(cwd: string): string {
+	return join(cwd, ".dex", "extensions");
+}
+
+function getProjectRegistryPath(cwd: string): string {
+	return join(getProjectExtensionsDir(cwd), "registry.json");
+}
+
+/* ------------------------------------------------------------------ */
+/* Types                                                               */
+/* ------------------------------------------------------------------ */
+
+interface RegistryEntry {
+	source: "npm" | "file";
+	package: string;
+	version?: string;
+	path?: string;
+	type?: "native" | "pi-compat";
+	installedAt: string;
+}
+
+interface Registry {
+	version: 1;
+	extensions: Record<string, RegistryEntry>;
+}
+
+/* ------------------------------------------------------------------ */
+/* Registry helpers                                                     */
+/* ------------------------------------------------------------------ */
+
+function loadRegistry(registryPath: string): Registry {
+	if (!existsSync(registryPath)) {
+		return { version: 1, extensions: {} };
+	}
+	try {
+		const data = JSON.parse(readFileSync(registryPath, "utf-8"));
+		if (data.version === 1 && data.extensions) return data;
+		return { version: 1, extensions: {} };
+	} catch {
+		return { version: 1, extensions: {} };
+	}
+}
+
+function saveRegistry(registryPath: string, registry: Registry): void {
+	const dir = join(registryPath, "..");
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(registryPath, JSON.stringify(registry, null, 2) + "\n");
+
+	// Ensure extensions/config.json exists alongside registry
+	const configPath = join(dir, "config.json");
+	if (!existsSync(configPath)) {
+		writeFileSync(configPath, "{}\n");
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/* Package manager                                                     */
+/* ------------------------------------------------------------------ */
+
+type PackageManagerName = "npm" | "bun" | "pnpm" | "yarn";
+
+function getConfiguredPackageManager(): PackageManagerName {
+	const settingsPath = join(homedir(), ".dex", "settings.json");
+	if (existsSync(settingsPath)) {
+		try {
+			const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+			const pm = settings.packageManager;
+			if (pm === "npm" || pm === "bun" || pm === "pnpm" || pm === "yarn") {
+				return pm;
+			}
+		} catch {
+			// Fall through to default
+		}
+	}
+	return "npm";
+}
+
+interface PackageManagerCommands {
+	install: (cwd: string) => { command: string; args: string[] };
+	add: (cwd: string, pkg: string) => { command: string; args: string[] };
+	update: (cwd: string, pkg: string) => { command: string; args: string[] };
+}
+
+/**
+ * Copy .npmrc from ~/.dex/app to an extension directory so that npm resolves
+ * packages against the configured registry (e.g. local Verdaccio).
+ */
+function ensureNpmrc(extensionDir: string): void {
+	const appNpmrc = join(homedir(), ".dex", "app", ".npmrc");
+	if (!existsSync(appNpmrc)) return;
+	const destNpmrc = join(extensionDir, ".npmrc");
+	// Always overwrite to keep in sync with the app config
+	try {
+		const contents = readFileSync(appNpmrc, "utf-8");
+		mkdirSync(extensionDir, { recursive: true });
+		writeFileSync(destNpmrc, contents);
+	} catch {
+		// Non-fatal — npm will fall back to default registry
+	}
+}
+
+function getPackageManagerCommands(
+	pm: PackageManagerName,
+): PackageManagerCommands {
+	switch (pm) {
+		case "bun":
+			return {
+				install: (cwd) => ({ command: "bun", args: ["install"] }),
+				add: (cwd, pkg) => ({ command: "bun", args: ["add", pkg] }),
+				update: (cwd, pkg) => ({ command: "bun", args: ["update", pkg] }),
+			};
+		case "pnpm":
+			return {
+				install: (cwd) => ({ command: "pnpm", args: ["install"] }),
+				add: (cwd, pkg) => ({ command: "pnpm", args: ["add", pkg] }),
+				update: (cwd, pkg) => ({ command: "pnpm", args: ["update", pkg] }),
+			};
+		case "yarn":
+			return {
+				install: (cwd) => ({ command: "yarn", args: ["install"] }),
+				add: (cwd, pkg) => ({ command: "yarn", args: ["add", pkg] }),
+				update: (cwd, pkg) => ({ command: "yarn", args: ["upgrade", pkg] }),
+			};
+		case "npm":
+		default:
+			return {
+				install: (cwd) => ({ command: "npm", args: ["install"] }),
+				add: (cwd, pkg) => ({ command: "npm", args: ["install", pkg] }),
+				// Use `install @latest --prefer-online` instead of `update` —
+				// npm update doesn't reliably extract new tarballs from local registries.
+				update: (cwd, pkg) => ({
+					command: "npm",
+					args: ["install", `${pkg}@latest`, "--prefer-online"],
+				}),
+			};
+	}
+}
+
+function runPackageManager(
+	cmd: { command: string; args: string[] },
+	cwd: string,
+): { success: boolean } {
+	const result = spawnSync(cmd.command, cmd.args, {
+		cwd,
+		stdio: "inherit",
+	});
+	return { success: result.status === 0 };
+}
+
+/* ------------------------------------------------------------------ */
+/* Source parsing                                                       */
+/* ------------------------------------------------------------------ */
+
+interface ParsedSource {
+	type: "npm" | "file";
+	ref: string;
+}
+
+function parseSource(source: string): ParsedSource | null {
+	if (source.startsWith("npm:")) {
+		return { type: "npm", ref: source.slice(4) };
+	}
+	if (source.startsWith("file:")) {
+		return { type: "file", ref: source.slice(5) };
+	}
+	return null;
+}
+
+/** Derive extension name from npm package name (strip scope). */
+function deriveNameFromPackage(packageName: string): string {
+	return packageName.replace(/^@[^/]+\//, "");
+}
+
+/** Derive extension name from tarball filename. */
+function deriveNameFromTarball(tarballPath: string): string {
+	const base = tarballPath.split("/").pop() ?? tarballPath;
+	// e.g. dex-ai-devtools-extension-0.1.0.tgz -> devtools-extension
+	// Strip version suffix and .tgz
+	const withoutExt = base.replace(/\.tgz$|\.tar\.gz$/, "");
+	// Strip dex-ai- prefix and version suffix (-0.1.0, -1.2.3, etc.)
+	const withoutPrefix = withoutExt.replace(/^dex-ai-/, "");
+	const withoutVersion = withoutPrefix.replace(/-\d+\.\d+\.\d+(-[\w.]+)?$/, "");
+	return withoutVersion || withoutPrefix;
+}
+
+/** Find the actual primary package name installed in an extension's node_modules. */
+function findInstalledPackageName(extensionDir: string): string | null {
+	// Read the extension's package.json to find what was installed as a dependency
+	const extPkgJsonPath = join(extensionDir, "package.json");
+	if (existsSync(extPkgJsonPath)) {
+		try {
+			const pkg = JSON.parse(readFileSync(extPkgJsonPath, "utf-8"));
+			const deps = pkg.dependencies ?? {};
+			const depNames = Object.keys(deps);
+			if (depNames.length > 0) {
+				// Return the first (and should be only) dependency
+				return depNames[0]!;
+			}
+		} catch {
+			// Fall through to node_modules scan
+		}
+	}
+
+	// Fallback: scan node_modules for scoped @dex-ai packages first
+	const nmDir = join(extensionDir, "node_modules");
+	if (!existsSync(nmDir)) return null;
+
+	const entries = readdirSync(nmDir);
+
+	// Prefer scoped @dex-ai packages
+	for (const entry of entries) {
+		if (entry === "@dex-ai") {
+			const scopeDir = join(nmDir, entry);
+			const scopeEntries = readdirSync(scopeDir);
+			// Find one that matches the extension dir name
+			for (const sub of scopeEntries) {
+				if (sub.includes("extension")) {
+					return `${entry}/${sub}`;
+				}
+			}
+			// Otherwise return the first
+			if (scopeEntries.length > 0) {
+				return `${entry}/${scopeEntries[0]}`;
+			}
+		}
+	}
+
+	// Fallback: first non-hidden package
+	for (const entry of entries) {
+		if (entry.startsWith(".")) continue;
+		if (entry.startsWith("@")) continue;
+		const pkgJsonPath = join(nmDir, entry, "package.json");
+		if (existsSync(pkgJsonPath)) {
+			return entry;
+		}
+	}
+
+	return null;
+}
+
+/** Resolve a file path (supports ~). */
+function resolveFilePath(filePath: string): string {
+	if (filePath.startsWith("~/")) {
+		return join(homedir(), filePath.slice(2));
+	}
+	if (filePath.startsWith("~")) {
+		return join(homedir(), filePath.slice(1));
+	}
+	return resolve(filePath);
+}
+
+/* ------------------------------------------------------------------ */
+/* Package inspection                                                   */
+/* ------------------------------------------------------------------ */
+
+interface PackageInfo {
+	name: string;
+	version?: string;
+	hasDexField: boolean;
+	hasPiField: boolean;
+	dexExtensions?: string[];
+	piExtensions?: string[];
+}
+
+/** Read package.json from an installed extension's node_modules. */
+function readInstalledPackageInfo(
+	extensionDir: string,
+	packageName: string,
+): PackageInfo | null {
+	const pkgJsonPath = join(
+		extensionDir,
+		"node_modules",
+		packageName,
+		"package.json",
+	);
+	if (!existsSync(pkgJsonPath)) return null;
+	try {
+		const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+		return {
+			name: pkg.name ?? packageName,
+			version: pkg.version,
+			hasDexField: !!(pkg.dex && typeof pkg.dex === "object"),
+			hasPiField: !!(pkg.pi && typeof pkg.pi === "object"),
+			dexExtensions: pkg.dex?.extensions,
+			piExtensions: pkg.pi?.extensions,
+		};
+	} catch {
+		return null;
+	}
+}
+
+/** Read package.json from a source directory (for file: installs). */
+function readSourcePackageInfo(dirPath: string): PackageInfo | null {
+	const pkgJsonPath = join(dirPath, "package.json");
+	if (!existsSync(pkgJsonPath)) return null;
+	try {
+		const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+		return {
+			name: pkg.name ?? "unknown",
+			version: pkg.version,
+			hasDexField: !!(pkg.dex && typeof pkg.dex === "object"),
+			hasPiField: !!(pkg.pi && typeof pkg.pi === "object"),
+			dexExtensions: pkg.dex?.extensions,
+			piExtensions: pkg.pi?.extensions,
+		};
+	} catch {
+		return null;
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/* Extension directory management                                      */
+/* ------------------------------------------------------------------ */
+
+function getExtensionDir(name: string, local: boolean, cwd: string): string {
+	if (local) {
+		return join(getProjectExtensionsDir(cwd), name);
+	}
+	return join(USER_PACKAGES_DIR, name);
+}
+
+function createExtensionPackageJson(
+	extensionDir: string,
+	name: string,
+	packageName: string,
+	depValue: string,
+): void {
+	mkdirSync(extensionDir, { recursive: true });
+	const pkgJson = {
+		name: `dex-ext-${name}`,
+		private: true,
+		type: "module",
+		dependencies: {
+			[packageName]: depValue,
+		},
+	};
+	writeFileSync(
+		join(extensionDir, "package.json"),
+		JSON.stringify(pkgJson, null, 2) + "\n",
+	);
+}
+
+/* ------------------------------------------------------------------ */
+/* Install                                                             */
+/* ------------------------------------------------------------------ */
+
+function cmdInstall(source: string, local: boolean): void {
+	if (!source) {
+		console.error("Usage: dex extension install <source> [-l|--local]");
+		console.error("");
+		console.error("Sources:");
+		console.error("  npm:<package>    Install from npm registry");
+		console.error("  file:<path>      Install from local filesystem");
+		console.error("");
+		console.error("Options:");
+		console.error("  -l, --local      Install to project scope");
+		console.error("");
+		console.error("Examples:");
+		console.error("  dex extension install npm:@dex-ai/memory");
+		console.error("  dex extension install npm:pi-lens");
+		console.error("  dex extension install file:./my-extension");
+		console.error(
+			"  dex extension install npm:@dex-ai/devtools-extension --local",
+		);
+		process.exit(1);
+	}
+
+	const parsed = parseSource(source);
+	if (!parsed) {
+		console.error(`Invalid source format: ${source}`);
+		console.error("Use npm:<package> or file:<path>");
+		process.exit(1);
+	}
+
+	const cwd = process.cwd();
+
+	if (parsed.type === "npm") {
+		installFromNpm(parsed.ref, local, cwd);
+	} else {
+		installFromFile(parsed.ref, local, cwd);
+	}
+}
+
+function installFromNpm(
+	packageName: string,
+	local: boolean,
+	cwd: string,
+): void {
+	// Detect if this is a tarball path (e.g. /path/to/foo-0.1.0.tgz)
+	const isTarball =
+		packageName.endsWith(".tgz") || packageName.endsWith(".tar.gz");
+
+	const name = isTarball
+		? deriveNameFromTarball(packageName)
+		: deriveNameFromPackage(packageName);
+	const extensionDir = getExtensionDir(name, local, cwd);
+	const registryPath = local ? getProjectRegistryPath(cwd) : USER_REGISTRY_PATH;
+	const registry = loadRegistry(registryPath);
+	const scope = local ? "project" : "user";
+
+	if (registry.extensions[name]) {
+		console.log(`Updating existing extension "${name}"...`);
+	}
+
+	console.log(`Installing ${packageName} (${scope} scope)...`);
+
+	// Create isolated extension directory with its own package.json
+	// For tarballs, use the file path directly as the dep value
+	const depValue = isTarball ? packageName : "latest";
+	const depKey = isTarball ? name : packageName;
+
+	// For tarballs, we use the tarball name as both dep key and use `npm install`
+	// which resolves the tarball. For registry packages, use packageName@latest.
+	if (isTarball) {
+		// npm install <tarball> installs directly — use add command
+		mkdirSync(extensionDir, { recursive: true });
+		ensureNpmrc(extensionDir);
+		writeFileSync(
+			join(extensionDir, "package.json"),
+			JSON.stringify(
+				{ name: `dex-ext-${name}`, private: true, type: "module" },
+				null,
+				2,
+			) + "\n",
+		);
+		const pm = getConfiguredPackageManager();
+		const cmds = getPackageManagerCommands(pm);
+		const addCmd = cmds.add(extensionDir, packageName);
+		const { success } = runPackageManager(addCmd, extensionDir);
+
+		if (!success) {
+			rmSync(extensionDir, { recursive: true, force: true });
+			console.error(`Failed to install ${packageName}`);
+			process.exit(1);
+		}
+	} else {
+		createExtensionPackageJson(extensionDir, name, packageName, "latest");
+		ensureNpmrc(extensionDir);
+
+		// Run package manager install
+		const pm = getConfiguredPackageManager();
+		const cmds = getPackageManagerCommands(pm);
+		const installCmd = cmds.install(extensionDir);
+		const { success } = runPackageManager(installCmd, extensionDir);
+
+		if (!success) {
+			rmSync(extensionDir, { recursive: true, force: true });
+			console.error(`Failed to install ${packageName}`);
+			process.exit(1);
+		}
+	}
+
+	// Read installed package info — for tarballs, find the actual package name from node_modules
+	const actualPackageName = isTarball
+		? findInstalledPackageName(extensionDir)
+		: packageName;
+	const info = actualPackageName
+		? readInstalledPackageInfo(extensionDir, actualPackageName)
+		: null;
+	const type = info?.hasPiField ? "pi-compat" : "native";
+
+	// Check pi-compat requirements
+	if (type === "pi-compat") {
+		// Verify @dex-ai/pi-compat is installed somewhere
+		const piCompatInstalled =
+			existsSync(join(USER_PACKAGES_DIR, "pi-compat")) ||
+			(local && existsSync(join(getProjectExtensionsDir(cwd), "pi-compat")));
+		if (!piCompatInstalled) {
+			console.error("");
+			console.error(
+				`Warning: "${name}" is a pi-compat extension and requires @dex-ai/pi-compat.`,
+			);
+			console.error("Install it with:");
+			console.error("  dex extension install npm:@dex-ai/pi-compat");
+			console.error("");
+		}
+	}
+
+	// Update registry
+	registry.extensions[name] = {
+		source: "npm",
+		package: actualPackageName ?? packageName,
+		...(info?.version ? { version: info.version } : {}),
+		type,
+		installedAt: new Date().toISOString(),
+	};
+	saveRegistry(registryPath, registry);
+
+	console.log("");
+	console.log(
+		`Installed ${name}${info?.version ? ` v${info.version}` : ""} (${scope} scope)`,
+	);
+	if (type === "pi-compat") {
+		console.log("  Type: pi-compat");
+	}
+}
+
+function installFromFile(filePath: string, local: boolean, cwd: string): void {
+	const resolved = resolveFilePath(filePath);
+
+	if (!existsSync(resolved)) {
+		console.error(`Path not found: ${resolved}`);
+		process.exit(1);
+	}
+
+	// Read package.json from the source to get the package name
+	const info = readSourcePackageInfo(resolved);
+	if (!info) {
+		console.error(`No package.json found at: ${resolved}`);
+		console.error(
+			"For file: installs, the path must be a directory with a package.json.",
+		);
+		process.exit(1);
+	}
+
+	const packageName = info.name;
+	const name = deriveNameFromPackage(packageName);
+	const extensionDir = getExtensionDir(name, local, cwd);
+	const registryPath = local ? getProjectRegistryPath(cwd) : USER_REGISTRY_PATH;
+	const registry = loadRegistry(registryPath);
+	const scope = local ? "project" : "user";
+
+	console.log(`Installing ${packageName} from ${resolved} (${scope} scope)...`);
+
+	// Create isolated extension directory with file: dependency
+	createExtensionPackageJson(
+		extensionDir,
+		name,
+		packageName,
+		`file:${resolved}`,
+	);
+
+	// Run package manager install (installs via symlink + transitive deps)
+	const pm = getConfiguredPackageManager();
+	const cmds = getPackageManagerCommands(pm);
+	const installCmd = cmds.install(extensionDir);
+	const { success } = runPackageManager(installCmd, extensionDir);
+
+	if (!success) {
+		rmSync(extensionDir, { recursive: true, force: true });
+		console.error(`Failed to install from ${resolved}`);
+		process.exit(1);
+	}
+
+	// Read installed package info for type detection
+	const installedInfo = readInstalledPackageInfo(extensionDir, packageName);
+	const type = installedInfo?.hasPiField ? "pi-compat" : "native";
+
+	// Check pi-compat requirements
+	if (type === "pi-compat") {
+		const piCompatInstalled =
+			existsSync(join(USER_PACKAGES_DIR, "pi-compat")) ||
+			(local && existsSync(join(getProjectExtensionsDir(cwd), "pi-compat")));
+		if (!piCompatInstalled) {
+			console.error("");
+			console.error(
+				`Warning: "${name}" is a pi-compat extension and requires @dex-ai/pi-compat.`,
+			);
+			console.error("Install it with:");
+			console.error("  dex extension install npm:@dex-ai/pi-compat");
+			console.error("");
+		}
+	}
+
+	// Update registry
+	registry.extensions[name] = {
+		source: "file",
+		package: packageName,
+		path: resolved,
+		...(installedInfo?.version ? { version: installedInfo.version } : {}),
+		type,
+		installedAt: new Date().toISOString(),
+	};
+	saveRegistry(registryPath, registry);
+
+	console.log("");
+	console.log(`Installed ${name} (file) (${scope} scope)`);
+}
+
+/* ------------------------------------------------------------------ */
+/* Uninstall                                                           */
+/* ------------------------------------------------------------------ */
+
+function cmdUninstall(name: string, local: boolean): void {
+	if (!name) {
+		console.error("Usage: dex extension uninstall <name> [-l|--local]");
+		process.exit(1);
+	}
+
+	const cwd = process.cwd();
+	const registryPath = local ? getProjectRegistryPath(cwd) : USER_REGISTRY_PATH;
+	const registry = loadRegistry(registryPath);
+	const entry = registry.extensions[name];
+
+	if (!entry) {
+		console.error(`Extension "${name}" is not installed.`);
+		const installed = Object.keys(registry.extensions);
+		if (installed.length > 0) {
+			console.error("");
+			console.error("Installed extensions:");
+			for (const key of installed) {
+				console.error(`  ${key}`);
+			}
+		}
+		process.exit(1);
+	}
+
+	// Remove the extension directory
+	const extensionDir = getExtensionDir(name, local, cwd);
+	if (existsSync(extensionDir)) {
+		console.log(`Removing ${name}...`);
+		rmSync(extensionDir, { recursive: true, force: true });
+	}
+
+	// Remove from registry
+	delete registry.extensions[name];
+	saveRegistry(registryPath, registry);
+
+	console.log(`Uninstalled "${name}"`);
+}
+
+/* ------------------------------------------------------------------ */
+/* Update                                                              */
+/* ------------------------------------------------------------------ */
+
+function cmdUpdate(nameOrFlag: string, local: boolean): void {
+	const cwd = process.cwd();
+	const registryPath = local ? getProjectRegistryPath(cwd) : USER_REGISTRY_PATH;
+	const registry = loadRegistry(registryPath);
+
+	if (nameOrFlag === "--all") {
+		const npmEntries = Object.entries(registry.extensions).filter(
+			([_, e]) => e.source === "npm",
+		);
+		if (npmEntries.length === 0) {
+			console.log("No npm extensions installed.");
+			return;
+		}
+		console.log(`Updating ${npmEntries.length} extension(s)...`);
+		console.log("");
+		for (const [name, entry] of npmEntries) {
+			updateSingle(name, entry, registry, local, cwd);
+		}
+		saveRegistry(registryPath, registry);
+		return;
+	}
+
+	if (!nameOrFlag) {
+		console.error(
+			"Usage: dex extension update <name> | dex extension update --all",
+		);
+		process.exit(1);
+	}
+
+	const entry = registry.extensions[nameOrFlag];
+	if (!entry) {
+		console.error(`Extension "${nameOrFlag}" is not installed.`);
+		process.exit(1);
+	}
+	if (entry.source !== "npm") {
+		console.error(
+			`Extension "${nameOrFlag}" is a file install. Run "npm install" in the source directory to update.`,
+		);
+		process.exit(1);
+	}
+
+	updateSingle(nameOrFlag, entry, registry, local, cwd);
+	saveRegistry(registryPath, registry);
+}
+
+function updateSingle(
+	name: string,
+	entry: RegistryEntry,
+	registry: Registry,
+	local: boolean,
+	cwd: string,
+): void {
+	const oldVersion = entry.version ?? "unknown";
+	const extensionDir = getExtensionDir(name, local, cwd);
+
+	if (!existsSync(extensionDir)) {
+		console.error(
+			`  Extension directory not found for "${name}". Re-install it.`,
+		);
+		return;
+	}
+
+	console.log(`Updating ${entry.package}...`);
+
+	// Ensure .npmrc is present so we resolve against the configured registry
+	ensureNpmrc(extensionDir);
+
+	const pm = getConfiguredPackageManager();
+	const cmds = getPackageManagerCommands(pm);
+	const updateCmd = cmds.update(extensionDir, entry.package);
+	const { success } = runPackageManager(updateCmd, extensionDir);
+
+	if (!success) {
+		console.error(`  Failed to update ${name}`);
+		return;
+	}
+
+	// Read new version
+	const info = readInstalledPackageInfo(extensionDir, entry.package);
+	const newVersion = info?.version ?? "unknown";
+
+	registry.extensions[name] = {
+		...entry,
+		...(info?.version ? { version: info.version } : {}),
+		installedAt: new Date().toISOString(),
+	};
+
+	if (oldVersion !== newVersion) {
+		console.log(`  ${name}: ${oldVersion} -> ${newVersion}`);
+	} else {
+		console.log(`  ${name}: already at latest (${newVersion})`);
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/* List                                                                */
+/* ------------------------------------------------------------------ */
+
+function cmdList(): void {
+	const cwd = process.cwd();
+	const userRegistry = loadRegistry(USER_REGISTRY_PATH);
+	const projectRegistryPath = getProjectRegistryPath(cwd);
+
+	// Don't show project scope if it resolves to the same file as user scope
+	const isSamePath =
+		resolve(projectRegistryPath) === resolve(USER_REGISTRY_PATH);
+	const projectRegistry = isSamePath
+		? { version: 1 as const, extensions: {} }
+		: loadRegistry(projectRegistryPath);
+
+	const userEntries = Object.entries(userRegistry.extensions);
+	const projectEntries = Object.entries(projectRegistry.extensions);
+
+	if (userEntries.length === 0 && projectEntries.length === 0) {
+		console.log("No extensions installed.");
+		console.log("");
+		console.log("Install one with:");
+		console.log("  dex extension install npm:<package>");
+		console.log("  dex extension install file:<path>");
+		return;
+	}
+
+	console.log("Installed extensions:");
+	console.log("");
+
+	if (userEntries.length > 0) {
+		console.log("  User:");
+		for (const [name, entry] of userEntries) {
+			// For file: sources, read live version from disk
+			let version = entry.version ?? "";
+			if (entry.source === "file" && entry.path) {
+				const livePkgPath = join(entry.path, "package.json");
+				if (existsSync(livePkgPath)) {
+					try {
+						const livePkg = JSON.parse(readFileSync(livePkgPath, "utf-8"));
+						if (livePkg.version) version = livePkg.version;
+					} catch {
+						/* use registry version */
+					}
+				}
+			}
+			const versionStr = version ? `v${version}` : "";
+			const source =
+				entry.source === "npm"
+					? `npm:${entry.package}`
+					: `file:${entry.path ?? entry.package}`;
+			const type = entry.type === "pi-compat" ? " [pi-compat]" : "";
+			console.log(
+				`    ${name.padEnd(24)} ${versionStr.padEnd(10)} ${source}${type}`,
+			);
+		}
+	}
+
+	if (projectEntries.length > 0) {
+		if (userEntries.length > 0) console.log("");
+		console.log(`  Project (${cwd}):`);
+		for (const [name, entry] of projectEntries) {
+			let version = entry.version ?? "";
+			if (entry.source === "file" && entry.path) {
+				const livePkgPath = join(entry.path, "package.json");
+				if (existsSync(livePkgPath)) {
+					try {
+						const livePkg = JSON.parse(readFileSync(livePkgPath, "utf-8"));
+						if (livePkg.version) version = livePkg.version;
+					} catch {
+						/* use registry version */
+					}
+				}
+			}
+			const versionStr = version ? `v${version}` : "";
+			const source =
+				entry.source === "npm"
+					? `npm:${entry.package}`
+					: `file:${entry.path ?? entry.package}`;
+			const type = entry.type === "pi-compat" ? " [pi-compat]" : "";
+			console.log(
+				`    ${name.padEnd(24)} ${versionStr.padEnd(10)} ${source}${type}`,
+			);
+		}
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/* Help                                                                */
+/* ------------------------------------------------------------------ */
+
+function printHelp(): void {
+	console.log(`
+dex extension — manage Dex extensions
+
+Usage:
+  dex extension install <source> [-l]   Install an extension
+  dex extension uninstall <name> [-l]   Remove an extension
+  dex extension update <name>           Update an npm extension
+  dex extension update --all            Update all npm extensions
+  dex extension list                    List installed extensions
+
+Sources:
+  npm:<package>    Install from npm registry
+  file:<path>      Install from local filesystem (directory with package.json)
+
+Options:
+  -l, --local      Operate on project scope (${process.cwd()}/.dex/extensions/)
+                   Default is user scope (~/.dex/extensions/packages/)
+
+Examples:
+  dex extension install npm:@dex-ai/memory
+  dex extension install npm:@dex-ai/devtools-extension
+  dex extension install npm:pi-lens
+  dex extension install file:./my-extension
+  dex extension install npm:@dex-ai/mcp-extension --local
+  dex extension uninstall memory-extension
+  dex extension update pi-lens
+  dex extension update --all
+  dex extension list
+`);
+}
+
+/* ------------------------------------------------------------------ */
+/* Main dispatch                                                       */
+/* ------------------------------------------------------------------ */
+
+export function runExtensionCommand(args: string[]): void {
+	const subcommand = args[0] ?? "list";
+	const rest = args.slice(1);
+
+	// Parse --local / -l flag from remaining args
+	const localIdx = rest.findIndex((a) => a === "--local" || a === "-l");
+	const local = localIdx !== -1;
+	const cleanArgs = local
+		? [...rest.slice(0, localIdx), ...rest.slice(localIdx + 1)]
+		: rest;
+
+	switch (subcommand) {
+		case "install":
+		case "add":
+			cmdInstall(cleanArgs[0] ?? "", local);
+			break;
+		case "uninstall":
+		case "remove":
+		case "rm":
+			cmdUninstall(cleanArgs[0] ?? "", local);
+			break;
+		case "update":
+		case "upgrade":
+			cmdUpdate(cleanArgs[0] ?? "", local);
+			break;
+		case "list":
+		case "ls":
+			cmdList();
+			break;
+		case "help":
+		case "--help":
+		case "-h":
+			printHelp();
+			break;
+		default:
+			console.error(`Unknown subcommand: ${subcommand}`);
+			printHelp();
+			process.exit(1);
+	}
+}