@tokentop/ttop 0.2.2 → 0.4.0

package/src/plugins/registry.ts

@@ -1,17 +1,22 @@
+import type { PluginsConfig } from "@/config/schema.ts";
+import {
+  discoverLocalPlugins,
+  loadLocalPlugin,
+  loadNpmPlugin,
+  resolvePluginPath,
+} from "./loader.ts";
+import { installAllNpmPlugins, resolveNpmPluginPath } from "./npm-installer.ts";
 import type {
+  AgentPlugin,
   AnyPlugin,
-  PluginType,
+  NotificationPlugin,
   PluginByType,
+  PluginType,
   ProviderPlugin,
-  AgentPlugin,
   ThemePlugin,
-  NotificationPlugin,
-} from './types/index.ts';
-import { loadLocalPlugin, loadNpmPlugin, discoverLocalPlugins, resolvePluginPath } from './loader.ts';
-import { installAllNpmPlugins, resolveNpmPluginPath } from './npm-installer.ts';
-import type { PluginsConfig } from '@/config/schema.ts';
+} from "./types/index.ts";
 
-export type PluginSource = 'builtin' | 'local' | 'npm';
+export type PluginSource = "builtin" | "local" | "npm";
 
 type PluginStore = {
   provider: Map<string, ProviderPlugin>;
@@ -30,46 +35,30 @@ class PluginRegistryImpl {
 
   private sources = new Map<string, PluginSource>();
   private initialized = false;
+  private officialIds = new Set<string>();
 
   private sourceKey(type: string, id: string): string {
     return `${type}-${id}`;
   }
 
-  register(plugin: AnyPlugin, source: PluginSource = 'builtin'): void {
+  register(plugin: AnyPlugin, source: PluginSource = "builtin"): void {
     const key = this.sourceKey(plugin.type, plugin.id);
     const existingSource = this.sources.get(key);
 
-    if (existingSource === 'builtin' && source !== 'builtin') {
+    // Priority: local > npm > builtin
+    // If a higher-priority source already registered this plugin, skip.
+    const priority: Record<PluginSource, number> = { local: 2, npm: 1, builtin: 0 };
+    if (existingSource && priority[existingSource] > priority[source]) {
       return;
     }
 
-    this.sources.set(key, source);
-    switch (plugin.type) {
-      case 'provider':
-        if (this.plugins.provider.has(plugin.id)) {
-          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
-        }
-        this.plugins.provider.set(plugin.id, plugin);
-        break;
-      case 'agent':
-        if (this.plugins.agent.has(plugin.id)) {
-          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
-        }
-        this.plugins.agent.set(plugin.id, plugin);
-        break;
-      case 'theme':
-        if (this.plugins.theme.has(plugin.id)) {
-          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
-        }
-        this.plugins.theme.set(plugin.id, plugin);
-        break;
-      case 'notification':
-        if (this.plugins.notification.has(plugin.id)) {
-          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
-        }
-        this.plugins.notification.set(plugin.id, plugin);
-        break;
+    if (existingSource && existingSource !== source) {
+      console.info(`Plugin "${plugin.id}" overridden by ${source} (was ${existingSource})`);
     }
+
+    this.sources.set(key, source);
+    const map = this.plugins[plugin.type] as Map<string, AnyPlugin>;
+    map.set(plugin.id, plugin);
   }
 
   unregister(type: PluginType, id: string): boolean {
@@ -113,43 +102,59 @@ class PluginRegistryImpl {
     return this.sources.get(this.sourceKey(type, id));
   }
 
+  isOfficial(type: PluginType, id: string): boolean {
+    return this.officialIds.has(this.sourceKey(type, id));
+  }
+
   async loadBuiltinPlugins(): Promise<void> {
     const [providers, agents, themes, notifications] = await Promise.all([
-      import('./providers/index.ts'),
-      import('./agents/index.ts'),
-      import('./themes/index.ts'),
-      import('./notifications/index.ts'),
+      import("./providers/index.ts"),
+      import("./agents/index.ts"),
+      import("./themes/index.ts"),
+      import("./notifications/index.ts"),
     ]);
 
     for (const plugin of Object.values(providers)) {
-      if (isProviderPlugin(plugin)) this.register(plugin, 'builtin');
+      if (isProviderPlugin(plugin)) {
+        this.register(plugin, "builtin");
+        this.officialIds.add(this.sourceKey(plugin.type, plugin.id));
+      }
     }
 
     for (const plugin of Object.values(agents)) {
-      if (isAgentPlugin(plugin)) this.register(plugin, 'builtin');
+      if (isAgentPlugin(plugin)) {
+        this.register(plugin, "builtin");
+        this.officialIds.add(this.sourceKey(plugin.type, plugin.id));
+      }
     }
 
     for (const plugin of Object.values(themes)) {
-      if (isThemePlugin(plugin)) this.register(plugin, 'builtin');
+      if (isThemePlugin(plugin)) {
+        this.register(plugin, "builtin");
+        this.officialIds.add(this.sourceKey(plugin.type, plugin.id));
+      }
     }
 
     for (const plugin of Object.values(notifications)) {
-      if (isNotificationPlugin(plugin)) this.register(plugin, 'builtin');
+      if (isNotificationPlugin(plugin)) {
+        this.register(plugin, "builtin");
+        this.officialIds.add(this.sourceKey(plugin.type, plugin.id));
+      }
     }
   }
 
   async loadLocalPlugins(extraPaths: string[] = []): Promise<void> {
     const discoveredPaths = await discoverLocalPlugins();
-    const resolvedExtraPaths = extraPaths.map(p => resolvePluginPath(p));
+    const resolvedExtraPaths = extraPaths.map((p) => resolvePluginPath(p));
     const allPaths = [...discoveredPaths, ...resolvedExtraPaths];
 
-    for (const pluginPath of allPaths) {
-      const result = await loadLocalPlugin(pluginPath);
+    const results = await Promise.all(allPaths.map((p) => loadLocalPlugin(p)));
+    for (const [i, result] of results.entries()) {
       if (result.success && result.plugin) {
-        this.register(result.plugin, 'local');
+        this.register(result.plugin, "local");
         console.info(`Loaded local plugin: ${result.plugin.name} (${result.plugin.id})`);
       } else {
-        console.warn(`Failed to load plugin from ${pluginPath}: ${result.error}`);
+        console.warn(`Failed to load plugin from ${allPaths[i]}: ${result.error}`);
       }
     }
   }
@@ -166,11 +171,16 @@ class PluginRegistryImpl {
       }
     }
 
-    for (const packageName of packages) {
-      const resolvedPath = resolveNpmPluginPath(packageName);
-      const result = await loadNpmPlugin(packageName, resolvedPath);
+    const loadResults = await Promise.all(
+      packages.map(async (packageName) => {
+        const resolvedPath = resolveNpmPluginPath(packageName);
+        const result = await loadNpmPlugin(packageName, resolvedPath);
+        return { packageName, result };
+      }),
+    );
+    for (const { packageName, result } of loadResults) {
       if (result.success && result.plugin) {
-        this.register(result.plugin, 'npm');
+        this.register(result.plugin, "npm");
         console.info(`Loaded npm plugin: ${result.plugin.name} (${packageName})`);
       } else {
         console.warn(`Failed to load npm plugin ${packageName}: ${result.error}`);
@@ -190,10 +200,7 @@ class PluginRegistryImpl {
 
     await this.loadBuiltinPlugins();
 
-    const localPaths = [
-      ...(config?.plugins?.local ?? []),
-      ...(config?.cliPlugins ?? []),
-    ];
+    const localPaths = [...(config?.plugins?.local ?? []), ...(config?.cliPlugins ?? [])];
     await this.loadLocalPlugins(localPaths);
 
     const npmPackages = config?.plugins?.npm ?? [];
@@ -203,7 +210,7 @@ class PluginRegistryImpl {
 
     const disabled = config?.plugins?.disabled ?? [];
     for (const pluginId of disabled) {
-      for (const type of ['provider', 'agent', 'theme', 'notification'] as PluginType[]) {
+      for (const type of ["provider", "agent", "theme", "notification"] as PluginType[]) {
         if (this.has(type, pluginId)) {
           this.disablePlugin(type, pluginId);
           console.info(`Disabled plugin: ${pluginId}`);
@@ -213,38 +220,40 @@ class PluginRegistryImpl {
 
     this.initialized = true;
     console.info(
-      `Plugin registry initialized: ${this.count('provider')} providers, ` +
-        `${this.count('agent')} agents, ${this.count('theme')} themes, ` +
-        `${this.count('notification')} notifications`
+      `Plugin registry initialized: ${this.count("provider")} providers, ` +
+        `${this.count("agent")} agents, ${this.count("theme")} themes, ` +
+        `${this.count("notification")} notifications`,
     );
   }
 }
 
-function hasPluginShape(obj: unknown): obj is { id: string; type: string; name: string; version: string } {
+function hasPluginShape(
+  obj: unknown,
+): obj is { id: string; type: string; name: string; version: string } {
   return (
     obj !== null &&
-    typeof obj === 'object' &&
-    'id' in obj &&
-    'type' in obj &&
-    'name' in obj &&
-    'version' in obj
+    typeof obj === "object" &&
+    "id" in obj &&
+    "type" in obj &&
+    "name" in obj &&
+    "version" in obj
   );
 }
 
 function isProviderPlugin(obj: unknown): obj is ProviderPlugin {
-  return hasPluginShape(obj) && obj.type === 'provider';
+  return hasPluginShape(obj) && obj.type === "provider";
 }
 
 function isAgentPlugin(obj: unknown): obj is AgentPlugin {
-  return hasPluginShape(obj) && obj.type === 'agent';
+  return hasPluginShape(obj) && obj.type === "agent";
 }
 
 function isThemePlugin(obj: unknown): obj is ThemePlugin {
-  return hasPluginShape(obj) && obj.type === 'theme';
+  return hasPluginShape(obj) && obj.type === "theme";
 }
 
 function isNotificationPlugin(obj: unknown): obj is NotificationPlugin {
-  return hasPluginShape(obj) && obj.type === 'notification';
+  return hasPluginShape(obj) && obj.type === "notification";
 }
 
 export const pluginRegistry = new PluginRegistryImpl();

package/src/plugins/sandbox-guard.test.ts

@@ -1,37 +1,34 @@
-import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import {
   deepFreeze,
   getActivePluginGuard,
   installGlobalFetchGuard,
   runInPluginGuard,
-} from './sandbox-guard.ts';
-import { PluginPermissionError } from './types/base.ts';
+} from "./sandbox-guard.ts";
+import { PluginPermissionError } from "./types/base.ts";
 
 const originalFetch = globalThis.fetch;
 const fetchCalls: string[] = [];
 
 const mockFetch: typeof fetch = Object.assign(
   (input: string | URL | Request, _init?: RequestInit): Promise<Response> => {
-    const url = typeof input === 'string'
-      ? input
-      : input instanceof URL
-        ? input.toString()
-        : input.url;
+    const url =
+      typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
     fetchCalls.push(url);
-    return Promise.resolve(new Response('ok', { status: 200 }));
+    return Promise.resolve(new Response("ok", { status: 200 }));
   },
   { preconnect: originalFetch.preconnect },
 );
 
-describe('deepFreeze', () => {
-  test('freezes a plain object', () => {
+describe("deepFreeze", () => {
+  test("freezes a plain object", () => {
     const obj = { a: 1 };
     deepFreeze(obj);
 
     expect(Object.isFrozen(obj)).toBe(true);
   });
 
-  test('freezes nested objects recursively', () => {
+  test("freezes nested objects recursively", () => {
     const obj = {
       top: {
         child: {
@@ -47,19 +44,19 @@ describe('deepFreeze', () => {
     expect(Object.isFrozen(obj.top.child)).toBe(true);
   });
 
-  test('returns the same reference', () => {
+  test("returns the same reference", () => {
     const obj = { nested: { value: 1 } };
     const frozen = deepFreeze(obj);
 
     expect(frozen).toBe(obj);
   });
 
-  test('handles null and undefined gracefully', () => {
+  test("handles null and undefined gracefully", () => {
     expect(deepFreeze(null)).toBeNull();
     expect(deepFreeze(undefined)).toBeUndefined();
   });
 
-  test('handles circular references without infinite loop', () => {
+  test("handles circular references without infinite loop", () => {
     const obj: { self?: unknown; nested: { parent?: unknown } } = {
       nested: {},
     };
@@ -73,7 +70,7 @@ describe('deepFreeze', () => {
     expect(Object.isFrozen(obj.nested)).toBe(true);
   });
 
-  test('handles already-frozen objects', () => {
+  test("handles already-frozen objects", () => {
     const obj = Object.freeze({ already: true });
 
     const frozen = deepFreeze(obj);
@@ -83,44 +80,44 @@ describe('deepFreeze', () => {
   });
 });
 
-describe('runInPluginGuard and getActivePluginGuard', () => {
-  test('returns undefined outside guard', () => {
+describe("runInPluginGuard and getActivePluginGuard", () => {
+  test("returns undefined outside guard", () => {
     expect(getActivePluginGuard()).toBeUndefined();
   });
 
-  test('returns plugin context inside guard', () => {
-    const context = runInPluginGuard('plugin-a', {}, () => getActivePluginGuard());
+  test("returns plugin context inside guard", () => {
+    const context = runInPluginGuard("plugin-a", {}, () => getActivePluginGuard());
 
     expect(context).toBeDefined();
-    expect(context?.pluginId).toBe('plugin-a');
+    expect(context?.pluginId).toBe("plugin-a");
   });
 
-  test('preserves context across async/await', async () => {
-    const context = await runInPluginGuard('plugin-async', {}, async () => {
+  test("preserves context across async/await", async () => {
+    const context = await runInPluginGuard("plugin-async", {}, async () => {
       await Promise.resolve();
       return getActivePluginGuard();
     });
 
     expect(context).toBeDefined();
-    expect(context?.pluginId).toBe('plugin-async');
+    expect(context?.pluginId).toBe("plugin-async");
   });
 
-  test('nested guards use the innermost context', () => {
-    const contexts = runInPluginGuard('outer-plugin', {}, () => {
+  test("nested guards use the innermost context", () => {
+    const contexts = runInPluginGuard("outer-plugin", {}, () => {
       const outerBefore = getActivePluginGuard();
-      const inner = runInPluginGuard('inner-plugin', {}, () => getActivePluginGuard());
+      const inner = runInPluginGuard("inner-plugin", {}, () => getActivePluginGuard());
       const outerAfter = getActivePluginGuard();
 
       return { outerBefore, inner, outerAfter };
     });
 
-    expect(contexts.outerBefore?.pluginId).toBe('outer-plugin');
-    expect(contexts.inner?.pluginId).toBe('inner-plugin');
-    expect(contexts.outerAfter?.pluginId).toBe('outer-plugin');
+    expect(contexts.outerBefore?.pluginId).toBe("outer-plugin");
+    expect(contexts.inner?.pluginId).toBe("inner-plugin");
+    expect(contexts.outerAfter?.pluginId).toBe("outer-plugin");
   });
 });
 
-describe('installGlobalFetchGuard', () => {
+describe("installGlobalFetchGuard", () => {
   beforeAll(() => {
     globalThis.fetch = mockFetch;
     installGlobalFetchGuard();
@@ -130,62 +127,62 @@ describe('installGlobalFetchGuard', () => {
     globalThis.fetch = originalFetch;
   });
 
-  test('outside guard, fetch calls pass through', async () => {
+  test("outside guard, fetch calls pass through", async () => {
     fetchCalls.length = 0;
 
-    const response = await fetch('https://outside-guard.example');
+    const response = await fetch("https://outside-guard.example");
 
     expect(response.status).toBe(200);
     expect(fetchCalls).toHaveLength(1);
-    expect(fetchCalls[0]).toContain('outside-guard.example');
+    expect(fetchCalls[0]).toContain("outside-guard.example");
   });
 
-  test('inside guard with no network permission throws PluginPermissionError', () => {
+  test("inside guard with no network permission throws PluginPermissionError", () => {
     expect(() => {
-      runInPluginGuard('plugin-no-network', {}, () => {
-        void fetch('https://blocked.example');
+      runInPluginGuard("plugin-no-network", {}, () => {
+        void fetch("https://blocked.example");
       });
     }).toThrow(PluginPermissionError);
   });
 
-  test('inside guard with allowedDomains blocks unlisted domains', () => {
+  test("inside guard with allowedDomains blocks unlisted domains", () => {
     expect(() => {
       runInPluginGuard(
-        'plugin-allowlist',
+        "plugin-allowlist",
         {
           network: {
             enabled: true,
-            allowedDomains: ['allowed.example'],
+            allowedDomains: ["allowed.example"],
           },
         },
         () => {
-          void fetch('https://not-allowed.example/path');
+          void fetch("https://not-allowed.example/path");
         },
       );
     }).toThrow(PluginPermissionError);
   });
 
-  test('inside guard with allowedDomains allows listed domains and subdomains', async () => {
+  test("inside guard with allowedDomains allows listed domains and subdomains", async () => {
     fetchCalls.length = 0;
 
     const response = await runInPluginGuard(
-      'plugin-allowlist',
+      "plugin-allowlist",
       {
         network: {
           enabled: true,
-          allowedDomains: ['allowed.example'],
+          allowedDomains: ["allowed.example"],
         },
       },
       async () => {
-        const rootResponse = await fetch('https://allowed.example/path');
-        await fetch('https://api.allowed.example/path');
+        const rootResponse = await fetch("https://allowed.example/path");
+        await fetch("https://api.allowed.example/path");
         return rootResponse;
       },
     );
 
     expect(response.status).toBe(200);
     expect(fetchCalls).toHaveLength(2);
-    expect(fetchCalls[0]).toContain('allowed.example/path');
-    expect(fetchCalls[1]).toContain('api.allowed.example/path');
+    expect(fetchCalls[0]).toContain("allowed.example/path");
+    expect(fetchCalls[1]).toContain("api.allowed.example/path");
   });
 });

package/src/plugins/sandbox-guard.ts

@@ -11,9 +11,9 @@
  * 2. **Deep-freeze** — prevents plugins from mutating the PluginContext.
  */
 
-import { AsyncLocalStorage } from 'async_hooks';
-import { PluginPermissionError, type PluginPermissions } from './types/base.ts';
-import { createPluginLogger } from './sandbox.ts';
+import { AsyncLocalStorage } from "async_hooks";
+import { createPluginLogger } from "./sandbox.ts";
+import { PluginPermissionError, type PluginPermissions } from "./types/base.ts";
 
 // ---------------------------------------------------------------------------
 // Plugin execution context (AsyncLocalStorage)
@@ -68,10 +68,7 @@ export function installGlobalFetchGuard(): void {
   const originalFetch = globalThis.fetch;
 
   const guardedFetch: typeof fetch = Object.assign(
-    function guardedFetch(
-      input: string | URL | Request,
-      init?: RequestInit,
-    ): Promise<Response> {
+    function guardedFetch(input: string | URL | Request, init?: RequestInit): Promise<Response> {
       const guard = pluginGuardStorage.getStore();
 
       if (!guard) {
@@ -82,34 +79,32 @@ export function installGlobalFetchGuard(): void {
 
       if (!permissions.network?.enabled) {
         const log = createPluginLogger(pluginId);
-        log.error('Network access blocked — plugin has not declared network permissions');
-        throw new PluginPermissionError(
-          pluginId,
-          'network',
-          'Network access not permitted',
-        );
+        log.error("Network access blocked — plugin has not declared network permissions");
+        throw new PluginPermissionError(pluginId, "network", "Network access not permitted");
       }
 
       const allowedDomains = permissions.network.allowedDomains;
       if (allowedDomains && allowedDomains.length > 0) {
-        const url = typeof input === 'string'
-          ? new URL(input)
-          : input instanceof URL
-            ? input
-            : new URL(input.url);
+        const url =
+          typeof input === "string"
+            ? new URL(input)
+            : input instanceof URL
+              ? input
+              : new URL(input.url);
 
         const isAllowed = allowedDomains.some(
-          (domain) =>
-            url.hostname === domain || url.hostname.endsWith(`.${domain}`),
+          (domain) => url.hostname === domain || url.hostname.endsWith(`.${domain}`),
         );
 
         if (!isAllowed) {
           const log = createPluginLogger(pluginId);
-          log.error(`Network blocked: domain "${url.hostname}" not in allowlist [${allowedDomains.join(', ')}]`);
+          log.error(
+            `Network blocked: domain "${url.hostname}" not in allowlist [${allowedDomains.join(", ")}]`,
+          );
           throw new PluginPermissionError(
             pluginId,
-            'network',
-            `Domain "${url.hostname}" not in allowlist: ${allowedDomains.join(', ')}`,
+            "network",
+            `Domain "${url.hostname}" not in allowlist: ${allowedDomains.join(", ")}`,
           );
         }
       }
@@ -136,7 +131,7 @@ const frozenObjects = new WeakSet<object>();
  */
 export function deepFreeze<T>(obj: T): T {
   if (obj === null || obj === undefined) return obj;
-  if (typeof obj !== 'object') return obj;
+  if (typeof obj !== "object") return obj;
 
   const o = obj as object;
 
@@ -146,7 +141,7 @@ export function deepFreeze<T>(obj: T): T {
   Object.freeze(o);
 
   for (const value of Object.values(o)) {
-    if (value !== null && typeof value === 'object') {
+    if (value !== null && typeof value === "object") {
       deepFreeze(value);
     }
   }