@oh-my-tool/cli 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oh-my-tool/cli",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "Oh My Tool CLI - local and enterprise tools for agents",
   "keywords": [
@@ -29,7 +29,7 @@
   "dependencies": {
     "@clack/prompts": "^1.7.0",
     "@modelcontextprotocol/client": "2.0.0",
-    "@oh-my-tool/sdk": "0.3.1",
+    "@oh-my-tool/sdk": "0.3.3",
     "open": "11.0.0"
   },
   "engines": {

package/src/cli/commands/connections.ts

@@ -1,18 +1,15 @@
-import { loadConfig } from "../../config/config";
+import { loadConfig, sanitizeExtensionConnections, validateConfiguredConnections } from "../../config/config";
 import { createPaths } from "../../paths";
 import { prepareHome } from "../../migration";
 import { withRuntime } from "../context";
+import { discoverExtensions } from "../../extension/discovery";
 
 export interface ConnectionSummary {
   extension: string;
   name: string;
-  environment: string;
-  host: string;
-  port: number;
-  database: string;
-  username: string;
-  tls: boolean;
-  secretConfigured: boolean;
+  environment?: string;
+  settings: Record<string, unknown>;
+  secretsConfigured: Record<string, boolean>;
 }
 
 export interface ConnectionListResult {
@@ -43,20 +40,15 @@ async function configuredConnections(): Promise<ConnectionListResult> {
   const paths = createPaths();
   await prepareHome(paths);
   const config = loadConfig(paths.home);
-  const connections = Object.entries(config.extensions)
+  const sanitized = sanitizeExtensionConnections(config);
+  const connections = Object.entries(sanitized)
     .sort(([left], [right]) => left.localeCompare(right))
-    .flatMap(([extension, value]) => Object.entries(value.connections)
+    .flatMap(([extension, value]) => Object.entries(value)
       .sort(([left], [right]) => left.localeCompare(right))
       .map(([name, connection]) => ({
         extension,
         name,
-        environment: connection.environment,
-        host: connection.host,
-        port: connection.port,
-        database: connection.database,
-        username: connection.username,
-        tls: connection.tls,
-        secretConfigured: connection.secret.length > 0,
+        ...connection,
       })));
   return { connections, count: connections.length };
 }
@@ -69,6 +61,7 @@ export async function runConfigCheck(): Promise<ConfigCheckResult> {
   const paths = createPaths();
   await prepareHome(paths);
   const config = loadConfig(paths.home);
+  validateConfiguredConnections(config, discoverExtensions(paths.home));
   return {
     valid: true,
     connectionCount: Object.values(config.extensions).reduce((count, extension) => count + Object.keys(extension.connections).length, 0),
@@ -78,21 +71,32 @@ export async function runConfigCheck(): Promise<ConfigCheckResult> {
 
 export async function runConnectionCheck(): Promise<ConnectionCheckResult> {
   const list = await configuredConnections();
+  const paths = createPaths();
+  const checkTools = new Map(discoverExtensions(paths.home).map((extension) => [extension.id, extension.manifest.connectionCheckTool]));
   return withRuntime(async (runtime) => {
-    const checks: ConnectionCheck[] = [];
-    for (const connection of list.connections) {
-      if (connection.extension !== "redis" && connection.extension !== "mysql") {
-        checks.push({ extension: connection.extension, name: connection.name, status: "unsupported", code: "CHECK_UNSUPPORTED" });
-        continue;
-      }
+    const checks: ConnectionCheck[] = await boundedMap(list.connections, 4, async (connection) => {
+      const toolId = checkTools.get(connection.extension);
+      if (!toolId) return { extension: connection.extension, name: connection.name, status: "unsupported", code: "CHECK_UNSUPPORTED" };
       const started = Date.now();
-      const result = await runtime.run(`${connection.extension}.ping`, { connection: connection.name });
-      checks.push(result.ok
+      const result = await runtime.run(toolId, { connection: connection.name });
+      return result.ok
         ? { extension: connection.extension, name: connection.name, status: "ok", durationMs: Date.now() - started }
-        : result.error?.code === "TOOL_NOT_FOUND"
-          ? { extension: connection.extension, name: connection.name, status: "unsupported", code: "CHECK_UNSUPPORTED", durationMs: Date.now() - started }
-          : { extension: connection.extension, name: connection.name, status: "error", code: result.error?.code ?? "CHECK_FAILED", durationMs: Date.now() - started });
-    }
+        : { extension: connection.extension, name: connection.name, status: "error", code: result.error.code ?? "CHECK_FAILED", durationMs: Date.now() - started };
+    });
     return { checks, count: checks.length };
   }, { includeMcp: false });
 }
+
+async function boundedMap<T, R>(values: readonly T[], concurrency: number, worker: (value: T) => Promise<R>): Promise<R[]> {
+  const results = new Array<R>(values.length);
+  let next = 0;
+  async function consume(): Promise<void> {
+    while (true) {
+      const index = next++;
+      if (index >= values.length) return;
+      results[index] = await worker(values[index]);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, () => consume()));
+  return results;
+}

package/src/cli/commands/extension.ts

@@ -1,5 +1,5 @@
 import { discoverExtensions } from "../../extension/discovery";
-import { installLocalExtension, type InstalledRef } from "../../extension/install";
+import { installExtension, type InstalledRef } from "../../extension/install";
 import { homeDir } from "../context";
 
 export interface InstalledInfo {
@@ -19,6 +19,6 @@ export async function runExtensionList(): Promise<InstalledInfo[]> {
 }
 
 export async function runExtensionInstall(spec: string): Promise<InstalledRef> {
-  return installLocalExtension(homeDir(), spec);
+  return installExtension(homeDir(), spec);
 }
 

package/src/cli/commands/run.ts

@@ -1,25 +1,19 @@
 import { coerceInput } from "../parseArgs";
 import { withRuntime } from "../context";
-import type { OmtResult } from "../../core/result";
+import type { ExecutionResult } from "../../runtime/result";
 
 export async function runTool(
   toolName: string,
   keyValues: Record<string, string>,
   useStdin: boolean,
-): Promise<OmtResult> {
+): Promise<ExecutionResult> {
   let input: Record<string, unknown>;
   if (useStdin) {
     input = await readStdinJson();
   } else {
     input = coerceInput(keyValues);
   }
-  return withRuntime(async (runtime) => {
-    const result = await runtime.run(toolName, input);
-    if (result.ok) {
-      return { ok: true, tool: toolName, data: result.output, meta: result.meta ?? {} };
-    }
-    return { ok: false, tool: toolName, error: result.error ?? { code: "EXECUTION_FAILED", message: "execution failed" } };
-  }, { targetTool: toolName });
+  return withRuntime((runtime) => runtime.run(toolName, input), { targetTool: toolName });
 }
 
 function readStdinJson(): Promise<Record<string, unknown>> {

package/src/cli/commands/search.ts

@@ -1,8 +1,9 @@
 import { withRuntime } from "../context";
+import type { ToolSearchOptions } from "../../runtime/provider";
 
-export async function runSearch(query: string): Promise<{ tools: Array<Record<string, unknown>> }> {
+export async function runSearch(query: string, options: ToolSearchOptions = {}): Promise<{ tools: Array<Record<string, unknown>>; meta: { unavailableProviders: Array<Record<string, unknown>> } }> {
   return withRuntime(async (runtime) => {
-    const descriptors = await runtime.search(query);
+    const descriptors = await runtime.search(query, options);
     return {
       tools: descriptors.map((descriptor) => ({
         name: descriptor.id,
@@ -11,6 +12,11 @@ export async function runSearch(query: string): Promise<{ tools: Array<Record<st
         risk: descriptor.risk,
         provider: descriptor.provider,
       })),
+      meta: {
+        unavailableProviders: runtime.providerStatuses()
+          .filter((status) => status.status === "unavailable")
+          .map(({ id, kind, status, code, message }) => ({ id, kind, status, ...(code === undefined ? {} : { code }), ...(message === undefined ? {} : { message }) })),
+      },
     };
   });
 }

package/src/cli/context.ts

@@ -1,11 +1,10 @@
 import { createPaths } from "../paths";
 import { prepareHome } from "../migration";
-import { loadConfig, getConnectionConfig, sanitizeExtensionConnections, type McpEnabledServerConfig } from "../config/config";
+import { loadConfig, getConnectionConfig, sanitizeExtensionConnections, validateConfiguredConnections, type McpEnabledServerConfig } from "../config/config";
 import { SecretsManager } from "../secrets/secrets";
 import { applyLimits, validateConnectionInput } from "../policy/policy";
 import { NativeExtensionProvider } from "../runtime/providers/native/provider";
 import { McpProvider } from "../runtime/providers/mcp/provider";
-import { discoverExtensions } from "../extension/discovery";
 import { createToolRuntime } from "../runtime/runtime";
 import type { ToolDescriptor } from "../runtime/provider";
 
@@ -24,13 +23,14 @@ export async function createRuntime(options: RuntimeOptions = {}) {
   const config = loadConfig(paths.home);
   const secrets = new SecretsManager();
   const extensionConnections = sanitizeExtensionConnections(config);
-  const nativeTarget = options.targetTool !== undefined && discoverExtensions(paths.home)
-    .some((extension) => extension.manifest.tools.some((tool) => tool.name === options.targetTool));
+  const nativeProvider = new NativeExtensionProvider(paths);
+  validateConfiguredConnections(config, nativeProvider.installedExtensions());
+  const nativeTarget = options.targetTool !== undefined && await nativeProvider.hasTool(options.targetTool);
   const mcpProviders = options.includeMcp === false || nativeTarget ? [] : Object.entries(config.mcp.servers)
     .sort(([a], [b]) => a.localeCompare(b))
     .filter((entry): entry is [string, McpEnabledServerConfig] => entry[1].enabled)
     .map(([serverId, server]) => new McpProvider({ serverId, config: server, secrets }));
-  const providers = [new NativeExtensionProvider(paths), ...mcpProviders];
+  const providers = [nativeProvider, ...mcpProviders];
   return createToolRuntime({
     providers,
     policy: {

package/src/cli/index.ts

@@ -30,7 +30,7 @@ Usage:
   ohmytool connection check                check MySQL/Redis connectivity
   ohmytool config check                     validate configuration
   ohmytool extension list                  list installed extensions
-  ohmytool extension install <path>        install an extension from a local dir
+  ohmytool extension install <path|package> install a local or npm extension
   ohmytool secret set <name>               set a secret (interactive hidden prompt or stdin pipe)
   ohmytool secret list                     list secret names (Windows only, values never shown)
   ohmytool mcp list                       list configured MCP servers
@@ -121,6 +121,23 @@ function parseAgentIds(raw?: string): AgentId[] | undefined {
   return [...new Set(values as AgentId[])];
 }
 
+function parseSearchOptions(options: Record<string, string>): { limit?: number; provider?: string; source?: string; risk?: "read" | "write" | "admin" } {
+  const limit = options.limit === undefined ? undefined : Number(options.limit);
+  if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
+    throw new RuntimeError("INVALID_ARGUMENT", "search --limit must be a positive integer");
+  }
+  const risk = options.risk;
+  if (risk !== undefined && risk !== "read" && risk !== "write" && risk !== "admin") {
+    throw new RuntimeError("INVALID_ARGUMENT", `unsupported search risk '${risk}'`);
+  }
+  return {
+    ...(limit === undefined ? {} : { limit }),
+    ...(options.provider === undefined ? {} : { provider: options.provider }),
+    ...(options.source === undefined ? {} : { source: options.source }),
+    ...(risk === undefined ? {} : { risk }),
+  };
+}
+
 function printDetected(agents: AgentDetection[]): void {
   console.log("Detected agents:\n");
   for (const agent of agents) console.log(`✓ ${agent.variant ?? agent.displayName}`);
@@ -169,10 +186,10 @@ function printStatus(results: IntegrationResult[]): void {
   const summary = Object.entries(counts).map(([status, n]) => `${n} ${status}`).join("  ·  ");
   console.log(`\nSummary: ${summary}`);
   if (results.some((item) => item.status === "broken")) {
-    console.log("Tip:   run `omt integrate repair` to recreate broken links");
+    console.log("Tip:   run `ohmytool integrate repair` to recreate broken links");
   }
   if (results.some((item) => item.status === "conflict")) {
-    console.log("Tip:   conflict means OMT refuses to touch an unmanaged path; run `omt integrate --force` only if you accept replacing it");
+    console.log("Tip:   conflict means OMT refuses to touch an unmanaged path; run `ohmytool integrate --force` only if you accept replacing it");
   }
 }
 
@@ -207,7 +224,7 @@ export async function main(argv: string[], dependencies: CliDependencies = defau
     const parsed = parseArgs(argv);
     const cmd = parsed.positional[0];
     const allowedFlags = new Set(["help", "version", "json", "stdin", "yes", "dry-run", "force"]);
-    const allowedOptions = new Set(["format", "json", "agents"]);
+    const allowedOptions = new Set(["format", "json", "agents", "limit", "provider", "source", "risk"]);
     const unknownFlag = parsed.flags.find((flag) => !allowedFlags.has(flag));
     const unknownOption = Object.keys(parsed.options).find((option) => !allowedOptions.has(option));
     if (unknownFlag) throw new RuntimeError("INVALID_ARGUMENT", `unknown option '--${unknownFlag}'`);
@@ -215,7 +232,7 @@ export async function main(argv: string[], dependencies: CliDependencies = defau
     switch (cmd) {
       case "search": {
         const q = parsed.positional.slice(1).join(" ");
-        print(await runSearch(q));
+        print(await runSearch(q, parseSearchOptions(parsed.options)));
         return 0;
       }
       case "describe": {
@@ -235,7 +252,7 @@ export async function main(argv: string[], dependencies: CliDependencies = defau
           return 1;
         }
         const result = action === "list" ? await runConnectionList() : await runConnectionCheck();
-        const wrapped = { ok: true as const, tool: `connection.${action}`, data: result, meta: {} };
+        const wrapped = { ok: true as const, toolId: `connection.${action}`, output: result, meta: {} };
         console.log(formatOutput(wrapped, outputFormat(parsed)));
         return 0;
       }
@@ -245,7 +262,7 @@ export async function main(argv: string[], dependencies: CliDependencies = defau
           return 1;
         }
         const result = await runConfigCheck();
-        const wrapped = { ok: true as const, tool: "config.check", data: result, meta: {} };
+        const wrapped = { ok: true as const, toolId: "config.check", output: result, meta: {} };
         console.log(formatOutput(wrapped, outputFormat(parsed)));
         return 0;
       }

package/src/cli/output.ts

@@ -1,24 +1,24 @@
-import type { OmtResult } from "../core/result";
+import type { ExecutionResult } from "../runtime/result";
 
 export type OutputFormat = "text" | "json" | "table" | "csv";
 
-export function formatAiResult(result: OmtResult): string {
-  const lines = [`status: ${result.ok ? "ok" : "error"}`, `tool: ${result.tool}`];
+export function formatAiResult(result: ExecutionResult): string {
+  const lines = [`status: ${result.ok ? "ok" : "error"}`, `tool: ${result.toolId}`];
   if (!result.ok) {
     lines.push("error:");
     appendObject(lines, result.error, 2);
     return lines.join("\n");
   }
 
-  if (isRowsResult(result.data)) {
+  if (isRowsResult(result.output)) {
     lines.push("rows:");
-    for (const row of result.data.rows) lines.push(formatRow(row));
-    lines.push(`row_count: ${result.data.rows.length}`);
-    if (result.data.truncated === true) lines.push("truncated: true");
+    for (const row of result.output.rows) lines.push(formatRow(row));
+    lines.push(`row_count: ${result.output.rows.length}`);
+    if (result.output.truncated === true) lines.push("truncated: true");
     appendMeta(lines, result.meta, new Set(["returnedRows"]), false);
   } else {
     lines.push("data:");
-    appendValue(lines, result.data, 2);
+    appendValue(lines, result.output, 2);
     appendMeta(lines, result.meta);
   }
   return lines.join("\n");
@@ -36,17 +36,17 @@ export function formatJson(value: unknown): string {
   }, 2) ?? "null";
 }
 
-export function formatOutput(result: OmtResult, format: OutputFormat): string {
+export function formatOutput(result: ExecutionResult, format: OutputFormat): string {
   if (format === "json") return formatJson(result);
   if (format === "csv" || format === "table") return formatDelimited(result, format === "csv" ? "," : "\t");
   return formatAiResult(result);
 }
 
-function formatDelimited(result: OmtResult, delimiter: string): string {
+function formatDelimited(result: ExecutionResult, delimiter: string): string {
   if (!result.ok) return formatAiResult(result);
-  const rows = isRowsResult(result.data)
-    ? { columns: result.data.columns, rows: result.data.rows }
-    : findObjectArray(result.data);
+  const rows = isRowsResult(result.output)
+    ? { columns: result.output.columns, rows: result.output.rows }
+    : findObjectArray(result.output);
   if (!rows) return formatAiResult(result);
   return [rows.columns, ...rows.rows].map((row) => row.map((value) => quoteDelimited(value, delimiter)).join(delimiter)).join("\n");
 }

package/src/config/config.ts

@@ -1,15 +1,19 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { RuntimeError } from "../runtime/errors";
+import { validateInput, type Schema } from "../runtime/schema";
+import type { InstalledExtension } from "../extension/discovery";
 
 export interface ConnectionConfig {
-  environment: string;
-  host: string;
-  port: number;
-  database: string;
-  username: string;
-  secret: string;
-  tls: boolean;
+  environment?: string;
+  settings: Record<string, unknown>;
+  secrets: Record<string, string>;
+}
+
+export interface SanitizedConnectionConfig {
+  environment?: string;
+  settings: Record<string, unknown>;
+  secretsConfigured: Record<string, boolean>;
 }
 
 export interface McpCommonServerConfig { readonly enabled: true; readonly namespace: string; }
@@ -44,32 +48,36 @@ function parseConnection(extensionId: string, name: string, value: unknown): Con
   const path = `extensions.${extensionId}.connections.${name}`;
   if (value === null || typeof value !== "object" || Array.isArray(value)) invalidConnection(path, "must be a table");
   const raw = value as Record<string, unknown>;
-  const stringField = (key: string, fallback = ""): string => {
-    const entry = raw[key];
-    if (entry === undefined) return fallback;
-    if (typeof entry !== "string") invalidConnection(`${path}.${key}`, "must be a string");
-    return entry;
-  };
-  const host = stringField("host");
-  if (host.trim().length === 0) invalidConnection(`${path}.host`, "must be a non-empty string");
-  const defaultPort = extensionId === "redis" ? 6379 : 3306;
-  const port = raw.port === undefined ? defaultPort : raw.port;
-  if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) {
-    invalidConnection(`${path}.port`, "must be an integer from 1 through 65535");
-  }
-  const tls = raw.tls === undefined ? false : raw.tls;
-  if (typeof tls !== "boolean") invalidConnection(`${path}.tls`, "must be a boolean");
+  const allowed = new Set(["environment", "settings", "secrets"]);
+  for (const key of Object.keys(raw)) if (!allowed.has(key)) invalidConnection(`${path}.${key}`, "unknown connection field");
+  const environment = raw.environment;
+  if (environment !== undefined && typeof environment !== "string") invalidConnection(`${path}.environment`, "must be a string");
+  const settings = parseSettingsMap(raw.settings, `${path}.settings`);
+  const secrets = parseSecretMap(raw.secrets, `${path}.secrets`);
   return {
-    environment: stringField("environment"),
-    host,
-    port,
-    database: stringField("database"),
-    username: stringField("username"),
-    secret: stringField("secret"),
-    tls,
+    ...(environment === undefined ? {} : { environment }),
+    settings,
+    secrets,
   };
 }
 
+function parseSettingsMap(value: unknown, path: string): Record<string, unknown> {
+  if (value === undefined) return {};
+  if (value === null || typeof value !== "object" || Array.isArray(value)) invalidConnection(path, "must be a table");
+  return { ...(value as Record<string, unknown>) };
+}
+
+function parseSecretMap(value: unknown, path: string): Record<string, string> {
+  if (value === undefined) return {};
+  if (value === null || typeof value !== "object" || Array.isArray(value)) invalidConnection(path, "must be a table");
+  const result: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof entry !== "string" || entry.length === 0) invalidConnection(`${path}.${key}`, "must be a non-empty string");
+    result[key] = entry;
+  }
+  return result;
+}
+
 function parseStringMap(value: unknown, path: string): Record<string, string> {
   if (value === undefined) return {};
   if (value === null || typeof value !== "object" || Array.isArray(value)) invalid(path, "must be a table");
@@ -191,17 +199,32 @@ export function loadConfig(homeDir: string): Config {
 export function getConnectionConfig(cfg: Config, extensionId: string, connection: string): ConnectionConfig | undefined { return cfg.extensions[extensionId]?.connections[connection]; }
 export function listConnections(cfg: Config, extensionId: string): string[] { return Object.keys(cfg.extensions[extensionId]?.connections ?? {}); }
 
-export function sanitizeExtensionConnections(cfg: Config): Record<string, Record<string, Omit<ConnectionConfig, "secret"> & { secretConfigured: boolean }> > {
+export function sanitizeExtensionConnections(cfg: Config): Record<string, Record<string, SanitizedConnectionConfig>> {
   return Object.fromEntries(Object.entries(cfg.extensions).map(([extensionId, extension]) => [
     extensionId,
     Object.fromEntries(Object.entries(extension.connections).map(([name, connection]) => [name, {
-      environment: connection.environment,
-      host: connection.host,
-      port: connection.port,
-      database: connection.database,
-      username: connection.username,
-      tls: connection.tls,
-      secretConfigured: connection.secret.length > 0,
+      ...(connection.environment === undefined ? {} : { environment: connection.environment }),
+      settings: { ...connection.settings },
+      secretsConfigured: Object.fromEntries(Object.keys(connection.secrets).map((key) => [key, true])),
     }])),
   ]));
 }
+
+export function validateConfiguredConnections(
+  cfg: Config,
+  installedExtensions: readonly InstalledExtension[],
+): void {
+  const manifests = new Map(installedExtensions.map((extension) => [extension.id, extension.manifest]));
+  for (const [extensionId, extension] of Object.entries(cfg.extensions)) {
+    const schema = manifests.get(extensionId)?.connectionSchema;
+    if (schema === undefined) continue;
+    for (const [name, connection] of Object.entries(extension.connections)) {
+      try {
+        validateInput(schema as Schema, connection.settings, { applyDefaults: false });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        invalidConnection(`extensions.${extensionId}.connections.${name}.settings`, message);
+      }
+    }
+  }
+}

package/src/extension/install.ts

@@ -1,24 +1,135 @@
-import { cp, mkdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { cp, mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
 import { parseManifest, validateManifest, checkSdkCompatibility } from "./manifest";
 
+const execFile = promisify(execFileCallback);
+const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const OFFICIAL_PACKAGE_RE = /^@oh-my-tool\/[a-z0-9][a-z0-9._-]*$/;
+const EXTENSION_ID_RE = /^[a-z0-9][a-z0-9_-]*$/;
+
 export interface InstalledRef {
   id: string;
   version: string;
   target: string;
 }
 
-export async function installLocalExtension(home: string, srcDir: string): Promise<InstalledRef> {
+export interface NpmExtensionSpec {
+  packageName: string;
+  npmSpec: string;
+  version?: string;
+}
+
+export class ExtensionInstallError extends Error {}
+
+export interface NpmInstallDependencies {
+  install(spec: string, tempDir: string): Promise<void>;
+}
+
+export function normalizeNpmExtensionSpec(spec: string): NpmExtensionSpec {
+  const trimmed = spec.trim();
+  if (!trimmed) throw new ExtensionInstallError("extension package name must not be empty");
+
+  let packageName = trimmed;
+  let version: string | undefined;
+  const separator = trimmed.startsWith("@") ? trimmed.lastIndexOf("@") : trimmed.indexOf("@");
+  if (separator > 0) {
+    packageName = trimmed.slice(0, separator);
+    version = trimmed.slice(separator + 1);
+    if (!EXACT_VERSION_RE.test(version)) {
+      throw new ExtensionInstallError("npm extension versions must be exact semver values, for example 0.3.1");
+    }
+  }
+
+  if (!trimmed.startsWith("@")) packageName = `@oh-my-tool/${packageName}`;
+  if (!OFFICIAL_PACKAGE_RE.test(packageName)) {
+    throw new ExtensionInstallError("only official @oh-my-tool extension packages are supported");
+  }
+  return { packageName, npmSpec: `${packageName}${version === undefined ? "" : `@${version}`}`, ...(version === undefined ? {} : { version }) };
+}
+
+async function installExtensionDirectory(home: string, srcDir: string, expectedPackage?: NpmExtensionSpec): Promise<InstalledRef> {
   const manifest = parseManifest(await readFile(join(srcDir, "omt.manifest.json"), "utf8"));
   validateManifest(manifest);
   checkSdkCompatibility(manifest.sdkVersion);
+  if (!EXTENSION_ID_RE.test(manifest.id)) throw new ExtensionInstallError(`invalid extension id '${manifest.id}'`);
+  if (expectedPackage !== undefined) {
+    const packageJson = JSON.parse(await readFile(join(srcDir, "package.json"), "utf8")) as { name?: unknown; version?: unknown };
+    if (packageJson.name !== expectedPackage.packageName) {
+      throw new ExtensionInstallError(`package manifest mismatch: expected '${expectedPackage.packageName}'`);
+    }
+    if (packageJson.version !== manifest.version) {
+      throw new ExtensionInstallError("package.json and omt.manifest.json versions do not match");
+    }
+    if (expectedPackage.version !== undefined && packageJson.version !== expectedPackage.version) {
+      throw new ExtensionInstallError(`npm package '${expectedPackage.npmSpec}' resolved to an unexpected version`);
+    }
+  }
   const target = join(home, "extensions", manifest.id, manifest.version);
   await mkdir(target, { recursive: true });
   // 显式 force:true：Bun 的 fs.cp 在带 filter 时默认覆盖失效（重装不更新旧文件）
   await cp(srcDir, target, {
     recursive: true,
     force: true,
-    filter: (s: string) => !s.includes("node_modules"),
+    filter: (s: string) => basename(s) !== "node_modules",
   });
   return { id: manifest.id, version: manifest.version, target };
-}
+}
+
+export async function installLocalExtension(home: string, srcDir: string): Promise<InstalledRef> {
+  return installExtensionDirectory(home, srcDir);
+}
+
+export async function installNpmExtension(
+  home: string,
+  spec: string,
+  dependencies: Partial<NpmInstallDependencies> = {},
+): Promise<InstalledRef> {
+  const normalized = normalizeNpmExtensionSpec(spec);
+  const temp = await mkdtemp(join(tmpdir(), "oh-my-tool-npm-"));
+  try {
+    await writeFile(join(temp, "package.json"), JSON.stringify({ private: true }), "utf8");
+    try {
+      if (dependencies.install !== undefined) {
+        await dependencies.install(normalized.npmSpec, temp);
+      } else {
+        await execFile("npm", [
+          "install",
+          "--prefix", temp,
+          "--ignore-scripts",
+          "--no-save",
+          "--no-package-lock",
+          "--omit=dev",
+          "--registry=https://registry.npmjs.org",
+          "--", normalized.npmSpec,
+        ], { timeout: 120_000, maxBuffer: 4 * 1024 * 1024 });
+      }
+    } catch {
+      throw new ExtensionInstallError(`failed to download npm extension '${normalized.npmSpec}'`);
+    }
+
+    const packageDir = join(temp, "node_modules", ...normalized.packageName.split("/"));
+    try {
+      await stat(packageDir);
+    } catch {
+      throw new ExtensionInstallError(`npm extension '${normalized.npmSpec}' was not installed`);
+    }
+    return await installExtensionDirectory(home, packageDir, normalized);
+  } finally {
+    await rm(temp, { recursive: true, force: true });
+  }
+}
+
+export async function installExtension(home: string, spec: string): Promise<InstalledRef> {
+  const candidate = resolve(spec);
+  let isLocal = false;
+  try {
+    await stat(join(candidate, "omt.manifest.json"));
+    isLocal = true;
+  } catch {
+    // Not a local extension directory; interpret the argument as an npm spec.
+  }
+  return isLocal ? installLocalExtension(home, candidate) : installNpmExtension(home, spec);
+}

package/src/extension/loader.ts

@@ -1,6 +1,6 @@
 import { pathToFileURL } from "node:url";
 import type { ExtensionDefinition } from "@oh-my-tool/sdk";
-import { OmtError } from "../core/registry";
+import { RuntimeError as OmtError } from "../runtime/errors";
 import type { InstalledExtension } from "./discovery";
 import { validateHandlers } from "./manifest";