@tokentop/ttop 0.2.2

package/src/plugins/loader.ts

@@ -0,0 +1,282 @@
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import type {
+  PluginType,
+  PluginLoadResult,
+  PluginValidationResult,
+  AnyPlugin,
+} from './types/index.ts';
+import { CURRENT_API_VERSION } from './types/base.ts';
+import { PATHS } from '@/storage/paths.ts';
+
+const CUSTOM_PLUGINS_DIR = PATHS.config.plugins;
+
+export async function validatePlugin(plugin: unknown): Promise<PluginValidationResult> {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!plugin || typeof plugin !== 'object') {
+    errors.push('Plugin must be an object');
+    return { valid: false, errors, warnings };
+  }
+
+  const p = plugin as Record<string, unknown>;
+
+  if (typeof p.id !== 'string' || p.id.length === 0) {
+    errors.push('Plugin must have a non-empty string "id"');
+  } else if (!/^[a-z][a-z0-9-]*$/.test(p.id)) {
+    errors.push('Plugin id must be kebab-case (lowercase letters, numbers, hyphens)');
+  }
+
+  const validTypes: PluginType[] = ['provider', 'agent', 'theme', 'notification'];
+  if (!validTypes.includes(p.type as PluginType)) {
+    errors.push(`Plugin type must be one of: ${validTypes.join(', ')}`);
+  }
+
+  if (typeof p.name !== 'string' || p.name.length === 0) {
+    errors.push('Plugin must have a non-empty string "name"');
+  }
+
+  if (typeof p.version !== 'string' || !/^\d+\.\d+\.\d+/.test(p.version)) {
+    errors.push('Plugin must have a valid semver "version" (e.g., "1.0.0")');
+  }
+
+  if (!p.permissions || typeof p.permissions !== 'object') {
+    errors.push('Plugin must declare "permissions" object');
+  }
+
+  if (p.apiVersion !== CURRENT_API_VERSION) {
+    if (typeof p.apiVersion === 'number') {
+      errors.push(`Plugin apiVersion ${p.apiVersion} is not compatible (expected ${CURRENT_API_VERSION})`);
+    } else {
+      errors.push(`Plugin must declare "apiVersion: ${CURRENT_API_VERSION}"`);
+    }
+  }
+
+  if (p.type === 'provider') {
+    if (!p.auth || typeof p.auth !== 'object') {
+      errors.push('Provider plugin must declare "auth" object with discover() and isConfigured()');
+    } else {
+      const auth = p.auth as Record<string, unknown>;
+      if (typeof auth.discover !== 'function') {
+        errors.push('Provider plugin auth must implement "discover" method');
+      }
+      if (typeof auth.isConfigured !== 'function') {
+        errors.push('Provider plugin auth must implement "isConfigured" method');
+      }
+    }
+    if (typeof p.fetchUsage !== 'function') {
+      errors.push('Provider plugin must implement "fetchUsage" method');
+    }
+  }
+
+  if (p.type === 'agent') {
+    if (typeof p.isInstalled !== 'function') {
+      errors.push('Agent plugin must implement "isInstalled" method');
+    }
+    if (typeof p.parseSessions !== 'function') {
+      errors.push('Agent plugin must implement "parseSessions" method');
+    }
+    if (p.readCredentials !== undefined && typeof p.readCredentials !== 'function') {
+      errors.push('Agent plugin "readCredentials" must be a function if provided');
+    }
+    if (p.getProviders !== undefined && typeof p.getProviders !== 'function') {
+      errors.push('Agent plugin "getProviders" must be a function if provided');
+    }
+  }
+
+  if (p.type === 'theme') {
+    if (!['light', 'dark'].includes(p.colorScheme as string)) {
+      errors.push('Theme plugin must specify colorScheme as "light" or "dark"');
+    }
+    if (!p.colors || typeof p.colors !== 'object') {
+      errors.push('Theme plugin must provide "colors" object');
+    }
+  }
+
+  if (p.type === 'notification') {
+    if (typeof p.initialize !== 'function') {
+      errors.push('Notification plugin must implement "initialize" method');
+    }
+    if (typeof p.notify !== 'function') {
+      errors.push('Notification plugin must implement "notify" method');
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function expandTilde(filePath: string): string {
+  if (filePath.startsWith('~/') || filePath === '~') {
+    return path.join(os.homedir(), filePath.slice(1));
+  }
+  return filePath;
+}
+
+async function resolvePluginEntryPoint(dirPath: string): Promise<string | null> {
+  try {
+    const pkgJsonPath = path.join(dirPath, 'package.json');
+    const pkgContent = await fs.readFile(pkgJsonPath, 'utf-8');
+    const pkg = JSON.parse(pkgContent) as Record<string, unknown>;
+
+    if (typeof pkg.main === 'string') {
+      return path.resolve(dirPath, pkg.main);
+    }
+
+    if (pkg.exports && typeof pkg.exports === 'object') {
+      const exports = pkg.exports as Record<string, unknown>;
+      const root = exports['.'];
+      if (typeof root === 'string') return path.resolve(dirPath, root);
+      if (root && typeof root === 'object') {
+        const rootObj = root as Record<string, unknown>;
+        const entry = rootObj.import ?? rootObj.default;
+        if (typeof entry === 'string') return path.resolve(dirPath, entry);
+      }
+    }
+  } catch {
+    // no package.json — try convention-based entry points
+  }
+
+  const candidates = ['src/index.ts', 'src/index.js', 'index.ts', 'index.js', 'dist/index.js'];
+  for (const candidate of candidates) {
+    const candidatePath = path.join(dirPath, candidate);
+    try {
+      await fs.access(candidatePath);
+      return candidatePath;
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+export function resolvePluginPath(rawPath: string, relativeTo?: string): string {
+  const expanded = expandTilde(rawPath);
+  if (path.isAbsolute(expanded)) return expanded;
+  const base = relativeTo ?? PATHS.config.dir;
+  return path.resolve(base, expanded);
+}
+
+export async function loadLocalPlugin(filePath: string): Promise<PluginLoadResult<AnyPlugin>> {
+  try {
+    let importPath = filePath;
+
+    const stat = await fs.stat(filePath);
+    if (stat.isDirectory()) {
+      const entryPoint = await resolvePluginEntryPoint(filePath);
+      if (!entryPoint) {
+        return {
+          success: false,
+          error: `Directory "${filePath}" has no recognizable entry point (checked package.json main/exports, src/index.ts, index.ts)`,
+          source: 'local',
+        };
+      }
+      importPath = entryPoint;
+    }
+
+    const module = await import(importPath);
+    const plugin = module.default ?? module.plugin ?? module;
+
+    const validation = await validatePlugin(plugin);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: `Validation failed: ${validation.errors.join('; ')}`,
+        source: 'local',
+      };
+    }
+
+    return {
+      success: true,
+      plugin: plugin as AnyPlugin,
+      source: 'local',
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+      source: 'local',
+    };
+  }
+}
+
+export async function loadNpmPlugin(packageName: string, resolvedPath?: string): Promise<PluginLoadResult<AnyPlugin>> {
+  const pluginTypes = ['provider', 'agent', 'theme', 'notification'];
+
+  const cleanName = packageName.replace(/@[^@]*$/, '');
+
+  const isOfficial = pluginTypes.some((t) => cleanName.startsWith(`@tokentop/${t}-`));
+  const isCommunity = pluginTypes.some((t) => cleanName.startsWith(`tokentop-${t}-`));
+  const isScopedCommunity = pluginTypes.some((t) => {
+    const match = cleanName.match(/^@[^/]+\/tokentop-(\w+)-/);
+    return match?.[1] === t;
+  });
+
+  if (!isOfficial && !isCommunity && !isScopedCommunity) {
+    return {
+      success: false,
+      error: `Invalid npm plugin name "${packageName}". Expected one of:\n` +
+        `  Official:   @tokentop/{provider,agent,theme,notification}-*\n` +
+        `  Community:  tokentop-{provider,agent,theme,notification}-*\n` +
+        `  Scoped:     @yourname/tokentop-{provider,agent,theme,notification}-*`,
+      source: 'npm',
+    };
+  }
+
+  try {
+    const importTarget = resolvedPath ?? cleanName;
+    const module = await import(importTarget);
+    const plugin = module.default ?? module.plugin ?? module;
+
+    const validation = await validatePlugin(plugin);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: `Validation failed: ${validation.errors.join('; ')}`,
+        source: 'npm',
+      };
+    }
+
+    return {
+      success: true,
+      plugin: plugin as AnyPlugin,
+      source: 'npm',
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+      source: 'npm',
+    };
+  }
+}
+
+export async function discoverLocalPlugins(): Promise<string[]> {
+  try {
+    await fs.access(CUSTOM_PLUGINS_DIR);
+  } catch {
+    return [];
+  }
+
+  const entries = await fs.readdir(CUSTOM_PLUGINS_DIR, { withFileTypes: true });
+  const results: string[] = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(CUSTOM_PLUGINS_DIR, entry.name);
+
+    if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.js'))) {
+      results.push(fullPath);
+    } else if (entry.isDirectory()) {
+      const entryPoint = await resolvePluginEntryPoint(fullPath);
+      if (entryPoint) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  return results;
+}
+
+export { CUSTOM_PLUGINS_DIR };

package/src/plugins/notification-bus.ts

@@ -0,0 +1,153 @@
+import type { NotificationPlugin, NotificationEvent } from './types/notification.ts';
+import type { ProviderUsageData } from './types/provider.ts';
+import { safeInvoke } from './plugin-host.ts';
+import { createPluginLogger } from './sandbox.ts';
+import type { AppConfig } from '@/config/schema.ts';
+
+interface DedupEntry {
+  key: string;
+  timestamp: number;
+}
+
+const DEDUP_WINDOW_MS = 5 * 60_000; // 5 minutes — don't re-fire same event within this window
+
+class NotificationBus {
+  private plugins: NotificationPlugin[] = [];
+  private recentEvents = new Map<string, DedupEntry>();
+  private pluginConfigs = new Map<string, Record<string, unknown>>();
+
+  registerPlugins(plugins: NotificationPlugin[]): void {
+    this.plugins = plugins;
+    for (const plugin of plugins) {
+      if (!this.pluginConfigs.has(plugin.id)) {
+        this.pluginConfigs.set(plugin.id, { enabled: true });
+      }
+    }
+  }
+
+  setPluginConfig(pluginId: string, config: Record<string, unknown>): void {
+    this.pluginConfigs.set(pluginId, config);
+  }
+
+  /** @deprecated Lifecycle hooks are now managed by pluginLifecycle. This is a no-op. */
+  async initializePlugins(): Promise<void> {
+    // No-op: lifecycle manager calls initialize/start on all plugins.
+    // Kept for API compatibility — callers can be removed gradually.
+  }
+
+  async checkProviderUsage(
+    providerId: string,
+    providerName: string,
+    usage: ProviderUsageData,
+  ): Promise<void> {
+    if (usage.limitReached) {
+      await this.emit(`provider.limitReached:${providerId}`, {
+        type: 'provider.limitReached',
+        severity: 'critical',
+        title: `${providerName} Rate Limit Reached`,
+        message: `Rate limit reached for ${providerName}. Requests may be throttled.`,
+        timestamp: Date.now(),
+        data: { provider: providerId },
+      });
+    }
+
+    const primaryPercent = usage.limits?.primary?.usedPercent;
+    if (primaryPercent !== null && primaryPercent !== undefined && primaryPercent >= 80 && !usage.limitReached) {
+      await this.emit(`provider.limitReached:warning:${providerId}`, {
+        type: 'provider.limitReached',
+        severity: primaryPercent >= 95 ? 'critical' : 'warning',
+        title: `${providerName} Approaching Limit`,
+        message: `${providerName} usage at ${Math.round(primaryPercent)}%.`,
+        timestamp: Date.now(),
+        data: { provider: providerId, usedPercent: primaryPercent },
+      });
+    }
+  }
+
+  async checkBudget(
+    cost: number,
+    limit: number,
+    budgetType: 'daily' | 'weekly' | 'monthly',
+    config: AppConfig,
+  ): Promise<void> {
+    if (limit <= 0) return;
+
+    const percent = (cost / limit) * 100;
+    const label = capitalize(budgetType);
+
+    if (percent >= config.alerts.criticalPercent) {
+      await this.emit(`budget.limitReached:${budgetType}`, {
+        type: 'budget.limitReached',
+        severity: 'critical',
+        title: `${label} Budget Critical`,
+        message: `${label} spending at ${Math.round(percent)}% ($${cost.toFixed(2)}/$${limit.toFixed(2)}).`,
+        timestamp: Date.now(),
+        data: { budgetType, cost, limit, percent, currency: config.budgets.currency },
+      });
+    } else if (percent >= config.alerts.warningPercent) {
+      await this.emit(`budget.thresholdCrossed:${budgetType}`, {
+        type: 'budget.thresholdCrossed',
+        severity: 'warning',
+        title: `${label} Budget Warning`,
+        message: `${label} spending at ${Math.round(percent)}% ($${cost.toFixed(2)}/$${limit.toFixed(2)}).`,
+        timestamp: Date.now(),
+        data: { budgetType, cost, limit, percent, currency: config.budgets.currency },
+      });
+    }
+  }
+
+  private async emit(dedupKey: string, event: NotificationEvent): Promise<void> {
+    if (this.isDuplicate(dedupKey)) return;
+    this.recordEvent(dedupKey);
+
+    const matchingPlugins = this.plugins.filter((p) => {
+      const config = this.pluginConfigs.get(p.id);
+      if (config && config.enabled === false) return false;
+      if (p.supports) return p.supports(event);
+      return true;
+    });
+
+    await Promise.all(
+      matchingPlugins.map((plugin) => {
+        const config = this.pluginConfigs.get(plugin.id) ?? {};
+        const logger = createPluginLogger(plugin.id);
+        return safeInvoke(plugin.id, 'notify', () =>
+          plugin.notify({ logger, config, signal: AbortSignal.timeout(10_000) }, event),
+        );
+      }),
+    );
+  }
+
+  private isDuplicate(key: string): boolean {
+    const recent = this.recentEvents.get(key);
+    if (!recent) return false;
+    return Date.now() - recent.timestamp < DEDUP_WINDOW_MS;
+  }
+
+  private recordEvent(key: string): void {
+    this.recentEvents.set(key, { key, timestamp: Date.now() });
+    this.pruneOldEvents();
+  }
+
+  private pruneOldEvents(): void {
+    const cutoff = Date.now() - DEDUP_WINDOW_MS;
+    for (const [key, entry] of this.recentEvents) {
+      if (entry.timestamp < cutoff) {
+        this.recentEvents.delete(key);
+      }
+    }
+  }
+
+  destroy(): void {
+    this.plugins = [];
+    this.recentEvents.clear();
+    this.pluginConfigs.clear();
+  }
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+export const notificationBus = new NotificationBus();
+export type { NotificationBus };

package/src/plugins/notifications/index.ts

@@ -0,0 +1,2 @@
+export { terminalBellPlugin } from './terminal-bell.ts';
+export { visualFlashPlugin } from './visual-flash.ts';

package/src/plugins/notifications/terminal-bell.ts

@@ -0,0 +1,66 @@
+import type {
+  NotificationPlugin,
+  NotificationContext,
+  NotificationEvent,
+} from '../types/notification.ts';
+
+export const terminalBellPlugin: NotificationPlugin = {
+  apiVersion: 2,
+  id: 'terminal-bell',
+  type: 'notification',
+  name: 'Terminal Bell',
+  version: '1.0.0',
+
+  meta: {
+    description: 'Simple terminal bell (BEL character) for alerts',
+  },
+
+  permissions: {},
+
+  configSchema: {
+    enabled: { type: 'boolean', default: true, description: 'Enable terminal bell notifications' },
+    minSeverity: { type: 'select', default: 'warning', options: [
+      { value: 'info', label: 'Info' },
+      { value: 'warning', label: 'Warning' },
+      { value: 'critical', label: 'Critical' },
+    ]},
+  },
+
+  supports(event: NotificationEvent): boolean {
+    return event.type.startsWith('budget.') ||
+           event.type.startsWith('provider.') ||
+           event.type === 'plugin.crashed';
+  },
+
+  async initialize(ctx: NotificationContext): Promise<void> {
+    ctx.logger.debug('Terminal bell notification plugin initialized');
+  },
+
+  async notify(ctx: NotificationContext, event: NotificationEvent): Promise<void> {
+    const severityOrder = ['info', 'warning', 'critical'];
+    const minSeverity = (ctx.config.minSeverity as string) ?? 'warning';
+
+    if (severityOrder.indexOf(event.severity) < severityOrder.indexOf(minSeverity)) {
+      return;
+    }
+
+    const bellCount = event.severity === 'critical' ? 3 : 1;
+
+    for (let i = 0; i < bellCount; i++) {
+      process.stdout.write('\x07');
+      if (i < bellCount - 1) {
+        await sleep(200);
+      }
+    }
+  },
+
+  async test(ctx: NotificationContext): Promise<boolean> {
+    ctx.logger.info('Testing terminal bell...');
+    process.stdout.write('\x07');
+    return true;
+  },
+};
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/plugins/notifications/visual-flash.ts

@@ -0,0 +1,57 @@
+import type {
+  NotificationPlugin,
+  NotificationContext,
+  NotificationEvent,
+} from '../types/notification.ts';
+
+export const visualFlashPlugin: NotificationPlugin = {
+  apiVersion: 2,
+  id: 'visual-flash',
+  type: 'notification',
+  name: 'Visual Flash',
+  version: '1.0.0',
+
+  meta: {
+    description: 'Visual screen flash using ANSI escape sequences',
+  },
+
+  permissions: {},
+
+  configSchema: {
+    enabled: { type: 'boolean', default: true, description: 'Enable visual flash notifications' },
+    duration: { type: 'number', default: 100, description: 'Flash duration in milliseconds' },
+  },
+
+  supports(event: NotificationEvent): boolean {
+    return event.type.startsWith('budget.') ||
+           event.type.startsWith('provider.') ||
+           event.type === 'plugin.crashed';
+  },
+
+  async initialize(ctx: NotificationContext): Promise<void> {
+    ctx.logger.debug('Visual flash notification plugin initialized');
+  },
+
+  async notify(ctx: NotificationContext, event: NotificationEvent): Promise<void> {
+    const duration = (ctx.config.duration as number) ?? 100;
+
+    const colorCode = event.severity === 'critical' ? '41' :
+                      event.severity === 'warning' ? '43' : '42';
+
+    process.stdout.write(`\x1b[${colorCode}m`);
+    await sleep(duration);
+    process.stdout.write('\x1b[0m');
+  },
+
+  async test(ctx: NotificationContext): Promise<boolean> {
+    ctx.logger.info('Testing visual flash...');
+    process.stdout.write('\x1b[44m');
+    await sleep(100);
+    process.stdout.write('\x1b[0m');
+    return true;
+  },
+};
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}