@tokentop/ttop 0.2.2

package/src/plugins/npm-installer.ts

@@ -0,0 +1,164 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+
+const CACHE_DIR = path.join(os.homedir(), '.cache/tokentop');
+const PACKAGE_JSON_PATH = path.join(CACHE_DIR, 'package.json');
+const NODE_MODULES = path.join(CACHE_DIR, 'node_modules');
+
+interface CachePackageJson {
+  name: string;
+  private: boolean;
+  dependencies: Record<string, string>;
+}
+
+async function ensureCacheDir(): Promise<void> {
+  await fs.mkdir(CACHE_DIR, { recursive: true });
+
+  try {
+    await fs.access(PACKAGE_JSON_PATH);
+  } catch {
+    const skeleton: CachePackageJson = {
+      name: 'tokentop-plugin-cache',
+      private: true,
+      dependencies: {},
+    };
+    await fs.writeFile(PACKAGE_JSON_PATH, JSON.stringify(skeleton, null, 2));
+  }
+}
+
+function parsePackageSpec(spec: string): { name: string; version: string } {
+  const atIndex = spec.lastIndexOf('@');
+  if (atIndex > 0) {
+    return { name: spec.slice(0, atIndex), version: spec.slice(atIndex + 1) };
+  }
+  return { name: spec, version: 'latest' };
+}
+
+async function isInstalled(name: string, version: string): Promise<boolean> {
+  try {
+    const pkgJsonPath = path.join(NODE_MODULES, name, 'package.json');
+    const raw = await fs.readFile(pkgJsonPath, 'utf-8');
+    const pkg = JSON.parse(raw) as { version?: string };
+
+    if (version === 'latest') {
+      return !!pkg.version;
+    }
+    return pkg.version === version;
+  } catch {
+    return false;
+  }
+}
+
+export interface InstallResult {
+  name: string;
+  version: string;
+  installed: boolean;
+  error?: string;
+  resolvedPath: string;
+}
+
+export async function installNpmPlugin(spec: string): Promise<InstallResult> {
+  const { name, version } = parsePackageSpec(spec);
+  const resolvedPath = path.join(NODE_MODULES, name);
+
+  await ensureCacheDir();
+
+  if (await isInstalled(name, version)) {
+    return { name, version, installed: false, resolvedPath };
+  }
+
+  const versionArg = version === 'latest' ? name : `${name}@${version}`;
+
+  try {
+    const proc = Bun.spawn(
+      ['bun', 'add', '--force', '--exact', '--cwd', CACHE_DIR, versionArg],
+      { stdout: 'pipe', stderr: 'pipe' },
+    );
+
+    const exitCode = await proc.exited;
+
+    if (exitCode !== 0) {
+      const stderr = await new Response(proc.stderr).text();
+      return {
+        name,
+        version,
+        installed: false,
+        error: `bun add failed (exit ${exitCode}): ${stderr.trim().slice(0, 200)}`,
+        resolvedPath,
+      };
+    }
+
+    return { name, version, installed: true, resolvedPath };
+  } catch (err) {
+    return {
+      name,
+      version,
+      installed: false,
+      error: err instanceof Error ? err.message : String(err),
+      resolvedPath,
+    };
+  }
+}
+
+export async function installAllNpmPlugins(
+  specs: string[],
+): Promise<InstallResult[]> {
+  if (specs.length === 0) return [];
+
+  await ensureCacheDir();
+
+  const results: InstallResult[] = [];
+  const toInstall: string[] = [];
+
+  for (const spec of specs) {
+    const { name, version } = parsePackageSpec(spec);
+    const resolvedPath = path.join(NODE_MODULES, name);
+
+    if (await isInstalled(name, version)) {
+      results.push({ name, version, installed: false, resolvedPath });
+    } else {
+      toInstall.push(version === 'latest' ? name : `${name}@${version}`);
+      results.push({ name, version, installed: true, resolvedPath });
+    }
+  }
+
+  if (toInstall.length === 0) return results;
+
+  try {
+    const proc = Bun.spawn(
+      ['bun', 'add', '--force', '--exact', '--cwd', CACHE_DIR, ...toInstall],
+      { stdout: 'pipe', stderr: 'pipe' },
+    );
+
+    const exitCode = await proc.exited;
+
+    if (exitCode !== 0) {
+      const stderr = await new Response(proc.stderr).text();
+      const errMsg = `bun add failed (exit ${exitCode}): ${stderr.trim().slice(0, 200)}`;
+      for (const r of results) {
+        if (r.installed) {
+          r.installed = false;
+          r.error = errMsg;
+        }
+      }
+    }
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    for (const r of results) {
+      if (r.installed) {
+        r.installed = false;
+        r.error = errMsg;
+      }
+    }
+  }
+
+  return results;
+}
+
+export function resolveNpmPluginPath(packageName: string): string {
+  const { name } = parsePackageSpec(packageName);
+  return path.join(NODE_MODULES, name);
+}
+
+export { CACHE_DIR, NODE_MODULES };

package/src/plugins/plugin-context-factory.ts

@@ -0,0 +1,67 @@
+import type { PluginPermissions } from './types/base.ts';
+import type { PluginContext, PluginStorage } from './types/provider.ts';
+import { createAuthSources } from './auth-sources.ts';
+import { createSandboxedHttpClient, createPluginLogger } from './sandbox.ts';
+import { deepFreeze } from './sandbox-guard.ts';
+import {
+  pluginStorageGet,
+  pluginStorageSet,
+  pluginStorageDelete,
+  pluginStorageHas,
+  getDatabase,
+} from '@/storage/database.ts';
+
+let dbAvailable: boolean | null = null;
+
+function isDbAvailable(): boolean {
+  if (dbAvailable !== null) return dbAvailable;
+  try {
+    getDatabase();
+    dbAvailable = true;
+  } catch {
+    dbAvailable = false;
+  }
+  return dbAvailable;
+}
+
+function createPluginStorage(pluginId: string): PluginStorage {
+  return {
+    async get(key: string): Promise<string | null> {
+      if (!isDbAvailable()) return null;
+      return pluginStorageGet(pluginId, key);
+    },
+    async set(key: string, value: string): Promise<void> {
+      if (!isDbAvailable()) return;
+      pluginStorageSet(pluginId, key, value);
+    },
+    async delete(key: string): Promise<void> {
+      if (!isDbAvailable()) return;
+      pluginStorageDelete(pluginId, key);
+    },
+    async has(key: string): Promise<boolean> {
+      if (!isDbAvailable()) return false;
+      return pluginStorageHas(pluginId, key);
+    },
+  };
+}
+
+export function resetDbAvailableCache(): void {
+  dbAvailable = null;
+}
+
+export function createPluginContext(
+  pluginId: string,
+  permissions: PluginPermissions,
+  signal?: AbortSignal
+): PluginContext {
+  const ctx: PluginContext = {
+    config: {},
+    logger: createPluginLogger(pluginId),
+    http: createSandboxedHttpClient(pluginId, permissions),
+    authSources: createAuthSources(pluginId, permissions),
+    storage: createPluginStorage(pluginId),
+    signal: signal ?? AbortSignal.timeout(30_000),
+  };
+  deepFreeze(ctx.config);
+  return ctx;
+}

package/src/plugins/plugin-host.ts

@@ -0,0 +1,205 @@
+/**
+ * Plugin host — error isolation and circuit breaker for plugin method calls.
+ *
+ * Every plugin method invocation should go through `safeInvoke` to ensure:
+ * 1. Unhandled errors never crash the app
+ * 2. Plugins that fail repeatedly are temporarily disabled (circuit breaker)
+ * 3. All errors are logged through the scoped plugin logger
+ */
+
+import { createPluginLogger } from './sandbox.ts';
+
+// ---------------------------------------------------------------------------
+// Circuit breaker state
+// ---------------------------------------------------------------------------
+
+interface CircuitState {
+  consecutiveFailures: number;
+  lastFailureAt: number;
+  disabledUntil: number;
+  totalFailures: number;
+  totalCalls: number;
+}
+
+/** How many consecutive failures before disabling a plugin. */
+const MAX_CONSECUTIVE_FAILURES = 5;
+
+/** How long (ms) a tripped plugin stays disabled before retrying. */
+const COOLDOWN_MS = 60_000; // 1 minute
+
+const circuits = new Map<string, CircuitState>();
+
+function getCircuit(pluginId: string): CircuitState {
+  let state = circuits.get(pluginId);
+  if (!state) {
+    state = {
+      consecutiveFailures: 0,
+      lastFailureAt: 0,
+      disabledUntil: 0,
+      totalFailures: 0,
+      totalCalls: 0,
+    };
+    circuits.set(pluginId, state);
+  }
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export type SafeInvokeResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: Error; circuitOpen: boolean };
+
+/**
+ * Safely invoke a plugin method with circuit breaker protection.
+ *
+ * @param pluginId  Unique plugin identifier (for circuit tracking + logging)
+ * @param method    Human-readable method name (for logging, e.g. "fetchUsage")
+ * @param fn        The actual async function to call
+ * @returns         `{ ok: true, value }` or `{ ok: false, error, circuitOpen }`
+ */
+export async function safeInvoke<T>(
+  pluginId: string,
+  method: string,
+  fn: () => Promise<T>,
+): Promise<SafeInvokeResult<T>> {
+  const circuit = getCircuit(pluginId);
+  const log = createPluginLogger(pluginId);
+  circuit.totalCalls++;
+
+  // Check if circuit is open (plugin disabled)
+  if (circuit.disabledUntil > Date.now()) {
+    log.warn(`Circuit open — skipping ${method} (disabled until ${new Date(circuit.disabledUntil).toISOString()})`);
+    return {
+      ok: false,
+      error: new Error(`Plugin "${pluginId}" is temporarily disabled after ${circuit.consecutiveFailures} consecutive failures`),
+      circuitOpen: true,
+    };
+  }
+
+  // If we were disabled but cooldown expired, allow a retry (half-open)
+  if (circuit.disabledUntil > 0 && circuit.disabledUntil <= Date.now()) {
+    log.info(`Circuit half-open — retrying ${method}`);
+  }
+
+  try {
+    const value = await fn();
+
+    // Success — reset consecutive failures
+    if (circuit.consecutiveFailures > 0) {
+      log.info(`${method} succeeded — resetting circuit breaker (was at ${circuit.consecutiveFailures} failures)`);
+    }
+    circuit.consecutiveFailures = 0;
+    circuit.disabledUntil = 0;
+
+    return { ok: true, value };
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+
+    circuit.consecutiveFailures++;
+    circuit.totalFailures++;
+    circuit.lastFailureAt = Date.now();
+
+    log.error(`${method} failed (${circuit.consecutiveFailures}/${MAX_CONSECUTIVE_FAILURES})`, {
+      error: error.message,
+    });
+
+    // Trip the circuit if threshold reached
+    if (circuit.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+      circuit.disabledUntil = Date.now() + COOLDOWN_MS;
+      log.error(
+        `Circuit OPEN — plugin disabled for ${COOLDOWN_MS / 1000}s after ${circuit.consecutiveFailures} consecutive failures`,
+      );
+    }
+
+    return { ok: false, error, circuitOpen: false };
+  }
+}
+
+/**
+ * Synchronous version of safeInvoke for non-async plugin methods.
+ */
+export function safeInvokeSync<T>(
+  pluginId: string,
+  method: string,
+  fn: () => T,
+): SafeInvokeResult<T> {
+  const circuit = getCircuit(pluginId);
+  const log = createPluginLogger(pluginId);
+  circuit.totalCalls++;
+
+  if (circuit.disabledUntil > Date.now()) {
+    log.warn(`Circuit open — skipping ${method}`);
+    return {
+      ok: false,
+      error: new Error(`Plugin "${pluginId}" is temporarily disabled`),
+      circuitOpen: true,
+    };
+  }
+
+  try {
+    const value = fn();
+    circuit.consecutiveFailures = 0;
+    circuit.disabledUntil = 0;
+    return { ok: true, value };
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    circuit.consecutiveFailures++;
+    circuit.totalFailures++;
+    circuit.lastFailureAt = Date.now();
+
+    log.error(`${method} failed (${circuit.consecutiveFailures}/${MAX_CONSECUTIVE_FAILURES})`, {
+      error: error.message,
+    });
+
+    if (circuit.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+      circuit.disabledUntil = Date.now() + COOLDOWN_MS;
+      log.error(`Circuit OPEN — plugin disabled for ${COOLDOWN_MS / 1000}s`);
+    }
+
+    return { ok: false, error, circuitOpen: false };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Health inspection
+// ---------------------------------------------------------------------------
+
+export interface PluginHealth {
+  pluginId: string;
+  healthy: boolean;
+  consecutiveFailures: number;
+  totalFailures: number;
+  totalCalls: number;
+  disabledUntil: number | null;
+}
+
+/** Get health status for a specific plugin. */
+export function getPluginHealth(pluginId: string): PluginHealth {
+  const circuit = getCircuit(pluginId);
+  return {
+    pluginId,
+    healthy: circuit.disabledUntil < Date.now() && circuit.consecutiveFailures < MAX_CONSECUTIVE_FAILURES,
+    consecutiveFailures: circuit.consecutiveFailures,
+    totalFailures: circuit.totalFailures,
+    totalCalls: circuit.totalCalls,
+    disabledUntil: circuit.disabledUntil > Date.now() ? circuit.disabledUntil : null,
+  };
+}
+
+/** Get health status for all tracked plugins. */
+export function getAllPluginHealth(): PluginHealth[] {
+  return [...circuits.keys()].map(getPluginHealth);
+}
+
+/** Reset circuit breaker for a specific plugin (manual recovery). */
+export function resetCircuit(pluginId: string): void {
+  circuits.delete(pluginId);
+}
+
+/** Reset all circuit breakers. */
+export function resetAllCircuits(): void {
+  circuits.clear();
+}