@tokentop/ttop 0.2.2

package/src/plugins/agents/index.ts

@@ -0,0 +1,2 @@
+export { default as opencodeAgentPlugin } from '@tokentop/agent-opencode';
+export { default as claudeCodeAgentPlugin } from '@tokentop/agent-claude-code';

package/src/plugins/auth-sources.ts

@@ -0,0 +1,186 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import type { PluginPermissions } from './types/base.ts';
+import type { AuthSources, OpenCodeAuthEntry } from './types/provider.ts';
+import { PluginPermissionError } from './types/base.ts';
+
+const OPENCODE_AUTH_PATH = path.join(os.homedir(), '.local/share/opencode/auth.json');
+const OPENCODE_CONFIG_PATH = path.join(os.homedir(), '.config/opencode/opencode.json');
+
+function expandHome(filePath: string): string {
+  if (filePath.startsWith('~')) {
+    return path.join(os.homedir(), filePath.slice(1));
+  }
+  return filePath;
+}
+
+function isPathAllowed(filePath: string, permissions: PluginPermissions): boolean {
+  const allowedPaths = permissions.filesystem?.paths;
+  if (!allowedPaths || allowedPaths.length === 0) return true;
+
+  const normalized = expandHome(filePath);
+  return allowedPaths.some((allowed: string) => {
+    const normalizedAllowed = expandHome(allowed);
+    return normalized.startsWith(normalizedAllowed);
+  });
+}
+
+function isEnvVarAllowed(name: string, permissions: PluginPermissions): boolean {
+  if (!permissions.env?.read) return false;
+  const allowedVars = permissions.env.vars;
+  if (!allowedVars || allowedVars.length === 0) return true;
+  return allowedVars.includes(name);
+}
+
+async function readJsonFile<T>(filePath: string): Promise<T | null> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(content) as T;
+  } catch {
+    return null;
+  }
+}
+
+interface OpenCodeConfig {
+  provider?: Record<string, {
+    name?: string;
+    key?: string;
+    options?: {
+      apiKey?: string;
+      [key: string]: unknown;
+    };
+  }>;
+}
+
+function resolveEnvValue(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const envMatch = value.match(/^\{env:(\w+)\}$/);
+  if (envMatch?.[1]) {
+    return process.env[envMatch[1]];
+  }
+  return value;
+}
+
+export function createAuthSources(pluginId: string, permissions: PluginPermissions): AuthSources {
+  return {
+    env: {
+      get(name: string): string | undefined {
+        if (!isEnvVarAllowed(name, permissions)) {
+          throw new PluginPermissionError(
+            pluginId,
+            'env',
+            `Environment variable "${name}" not in allowlist`
+          );
+        }
+        return process.env[name];
+      },
+    },
+
+    files: {
+      async readText(filePath: string): Promise<string | null> {
+        const resolved = expandHome(filePath);
+        if (!permissions.filesystem?.read) {
+          throw new PluginPermissionError(
+            pluginId,
+            'filesystem',
+            'Filesystem read access not permitted'
+          );
+        }
+        if (!isPathAllowed(filePath, permissions)) {
+          throw new PluginPermissionError(
+            pluginId,
+            'filesystem',
+            `Path "${filePath}" not in allowlist`
+          );
+        }
+        try {
+          return await fs.readFile(resolved, 'utf-8');
+        } catch {
+          return null;
+        }
+      },
+
+      async readJson<T = unknown>(filePath: string): Promise<T | null> {
+        const resolved = expandHome(filePath);
+        if (!permissions.filesystem?.read) {
+          throw new PluginPermissionError(
+            pluginId,
+            'filesystem',
+            'Filesystem read access not permitted'
+          );
+        }
+        if (!isPathAllowed(filePath, permissions)) {
+          throw new PluginPermissionError(
+            pluginId,
+            'filesystem',
+            `Path "${filePath}" not in allowlist`
+          );
+        }
+        try {
+          const content = await fs.readFile(resolved, 'utf-8');
+          return JSON.parse(content) as T;
+        } catch {
+          return null;
+        }
+      },
+
+      async exists(filePath: string): Promise<boolean> {
+        const resolved = expandHome(filePath);
+        if (!permissions.filesystem?.read) {
+          throw new PluginPermissionError(
+            pluginId,
+            'filesystem',
+            'Filesystem read access not permitted'
+          );
+        }
+        if (!isPathAllowed(filePath, permissions)) {
+          throw new PluginPermissionError(
+            pluginId,
+            'filesystem',
+            `Path "${filePath}" not in allowlist`
+          );
+        }
+        try {
+          await fs.access(resolved);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+    },
+
+    opencode: {
+      async getProviderEntry(key: string): Promise<OpenCodeAuthEntry | null> {
+        const authData = await readJsonFile<Record<string, OpenCodeAuthEntry>>(OPENCODE_AUTH_PATH);
+        if (authData) {
+          const entry = authData[key];
+          if (entry) return entry;
+        }
+
+        const config = await readJsonFile<OpenCodeConfig>(OPENCODE_CONFIG_PATH);
+        if (config?.provider) {
+          const providerConfig = config.provider[key];
+          if (providerConfig) {
+            const apiKey = resolveEnvValue(providerConfig.key) ??
+                           resolveEnvValue(providerConfig.options?.apiKey as string);
+            if (apiKey) {
+              return {
+                type: 'api',
+                key: apiKey,
+              };
+            }
+          }
+        }
+
+        return null;
+      },
+    },
+
+    platform: {
+      os: process.platform as 'darwin' | 'linux' | 'win32',
+      homedir: os.homedir(),
+      arch: process.arch,
+    },
+  };
+}

package/src/plugins/lifecycle.ts

@@ -0,0 +1,177 @@
+/**
+ * Plugin lifecycle manager — orchestrates initialize/start/stop/destroy hooks.
+ *
+ * Maintains per-plugin state and ensures hooks are called in order, wrapped
+ * with safeInvoke for error isolation and circuit breaker protection.
+ */
+
+import type { BasePlugin, PluginLifecycleContext, PluginLogger } from './types/base.ts';
+import { pluginRegistry } from './registry.ts';
+import { safeInvoke } from './plugin-host.ts';
+import { createPluginLogger } from './sandbox.ts';
+import { runInPluginGuard } from './sandbox-guard.ts';
+
+// ---------------------------------------------------------------------------
+// State machine
+// ---------------------------------------------------------------------------
+
+export type PluginLifecycleState =
+  | 'loaded'
+  | 'initialized'
+  | 'started'
+  | 'stopped'
+  | 'destroyed'
+  | 'failed';
+
+interface PluginLifecycleEntry {
+  pluginId: string;
+  state: PluginLifecycleState;
+  config: Record<string, unknown>;
+  logger: PluginLogger;
+}
+
+const HOOK_TIMEOUT_MS = 5_000;
+
+// ---------------------------------------------------------------------------
+// Manager
+// ---------------------------------------------------------------------------
+
+class PluginLifecycleManager {
+  private entries = new Map<string, PluginLifecycleEntry>();
+
+  private getOrCreate(plugin: BasePlugin): PluginLifecycleEntry {
+    let entry = this.entries.get(plugin.id);
+    if (!entry) {
+      entry = {
+        pluginId: plugin.id,
+        state: 'loaded',
+        config: { ...(plugin.defaultConfig ?? {}) },
+        logger: createPluginLogger(plugin.id),
+      };
+      this.entries.set(plugin.id, entry);
+    }
+    return entry;
+  }
+
+  private makeCtx(entry: PluginLifecycleEntry): PluginLifecycleContext {
+    return { config: entry.config, logger: entry.logger };
+  }
+
+  private async invokeHook(
+    plugin: BasePlugin,
+    hook: 'initialize' | 'start' | 'stop' | 'destroy',
+  ): Promise<boolean> {
+    const fn = plugin[hook];
+    if (!fn) return true;
+
+    const entry = this.getOrCreate(plugin);
+    const ctx = this.makeCtx(entry);
+
+    const result = await safeInvoke(plugin.id, hook, () =>
+      runInPluginGuard(plugin.id, plugin.permissions, () =>
+        Promise.race([
+          fn.call(plugin, ctx),
+          new Promise<never>((_, reject) =>
+            setTimeout(() => reject(new Error(`${hook} timed out after ${HOOK_TIMEOUT_MS}ms`)), HOOK_TIMEOUT_MS),
+          ),
+        ]),
+      ),
+    );
+
+    if (!result.ok) {
+      entry.logger.error(`Lifecycle hook "${hook}" failed: ${result.error.message}`);
+      return false;
+    }
+    return true;
+  }
+
+  async initializeAll(): Promise<void> {
+    const plugins = pluginRegistry.getAllPlugins();
+
+    for (const plugin of plugins) {
+      const entry = this.getOrCreate(plugin);
+      if (entry.state !== 'loaded') continue;
+
+      const ok = await this.invokeHook(plugin, 'initialize');
+      entry.state = ok ? 'initialized' : 'failed';
+    }
+  }
+
+  async startAll(): Promise<void> {
+    const plugins = pluginRegistry.getAllPlugins();
+
+    for (const plugin of plugins) {
+      const entry = this.getOrCreate(plugin);
+      if (entry.state !== 'initialized') continue;
+
+      const ok = await this.invokeHook(plugin, 'start');
+      entry.state = ok ? 'started' : 'failed';
+    }
+  }
+
+  async stopAll(): Promise<void> {
+    const plugins = [...pluginRegistry.getAllPlugins()].reverse();
+
+    for (const plugin of plugins) {
+      const entry = this.entries.get(plugin.id);
+      if (!entry || entry.state !== 'started') continue;
+
+      const ok = await this.invokeHook(plugin, 'stop');
+      entry.state = ok ? 'stopped' : 'failed';
+    }
+  }
+
+  async destroyAll(): Promise<void> {
+    const plugins = [...pluginRegistry.getAllPlugins()].reverse();
+
+    for (const plugin of plugins) {
+      const entry = this.entries.get(plugin.id);
+      if (!entry) continue;
+      if (entry.state === 'destroyed') continue;
+
+      await this.invokeHook(plugin, 'destroy');
+      entry.state = 'destroyed';
+    }
+  }
+
+  async notifyConfigChange(
+    pluginId: string,
+    newConfig: Record<string, unknown>,
+  ): Promise<void> {
+    const plugin = pluginRegistry.getAllPlugins().find((p) => p.id === pluginId);
+    if (!plugin?.onConfigChange) return;
+
+    const entry = this.entries.get(pluginId);
+    if (!entry || entry.state === 'destroyed' || entry.state === 'failed') return;
+
+    entry.config = { ...newConfig };
+
+    const ctx = this.makeCtx(entry);
+    await safeInvoke(pluginId, 'onConfigChange', () =>
+      runInPluginGuard(pluginId, plugin.permissions, () =>
+        Promise.resolve(plugin.onConfigChange!(newConfig, ctx)),
+      ),
+    );
+  }
+
+  getState(pluginId: string): PluginLifecycleState | undefined {
+    return this.entries.get(pluginId)?.state;
+  }
+
+  /**
+   * Update the stored config for a plugin (e.g. from user settings).
+   * Does NOT fire onConfigChange — call notifyConfigChange for that.
+   */
+  setPluginConfig(pluginId: string, config: Record<string, unknown>): void {
+    const entry = this.entries.get(pluginId);
+    if (entry) {
+      entry.config = { ...config };
+    }
+  }
+
+  reset(): void {
+    this.entries.clear();
+  }
+}
+
+export const pluginLifecycle = new PluginLifecycleManager();

package/src/plugins/loader.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, test } from 'bun:test';
+import { validatePlugin } from './loader.ts';
+import { CURRENT_API_VERSION } from './types/base.ts';
+
+const validPlugin = {
+  id: 'test-plugin',
+  type: 'notification',
+  name: 'Test Plugin',
+  version: '1.0.0',
+  apiVersion: CURRENT_API_VERSION,
+  permissions: {},
+  initialize: async () => {},
+  notify: async () => {},
+};
+
+function hasError(errors: string[], fragment: string): boolean {
+  return errors.some((error) => error.includes(fragment));
+}
+
+describe('validatePlugin', () => {
+  test('accepts a valid minimal plugin object', async () => {
+    const result = await validatePlugin(validPlugin);
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  test('rejects plugin missing id', async () => {
+    const plugin = {
+      ...validPlugin,
+      id: '',
+    };
+
+    const result = await validatePlugin(plugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, 'non-empty string "id"')).toBe(true);
+  });
+
+  test('rejects plugin with invalid id format', async () => {
+    const plugin = {
+      ...validPlugin,
+      id: 'Bad Plugin',
+    };
+
+    const result = await validatePlugin(plugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, 'kebab-case')).toBe(true);
+  });
+
+  test('rejects plugin missing type', async () => {
+    const plugin = {
+      id: 'test-plugin',
+      name: 'Test Plugin',
+      version: '1.0.0',
+      apiVersion: CURRENT_API_VERSION,
+      permissions: {},
+    };
+
+    const result = await validatePlugin(plugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, 'must be one of')).toBe(true);
+  });
+
+  test('rejects plugin with invalid type', async () => {
+    const plugin = {
+      ...validPlugin,
+      type: 'invalid',
+    };
+
+    const result = await validatePlugin(plugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, 'provider, agent, theme, notification')).toBe(true);
+  });
+
+  test('rejects plugin missing name', async () => {
+    const plugin = {
+      ...validPlugin,
+      name: '',
+    };
+
+    const result = await validatePlugin(plugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, 'non-empty string "name"')).toBe(true);
+  });
+
+  test('rejects plugin missing version', async () => {
+    const plugin = {
+      ...validPlugin,
+      version: '',
+    };
+
+    const result = await validatePlugin(plugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, 'valid semver "version"')).toBe(true);
+  });
+
+  test('rejects plugin with invalid version format', async () => {
+    const plugin = {
+      ...validPlugin,
+      version: 'v1',
+    };
+
+    const result = await validatePlugin(plugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, 'valid semver "version"')).toBe(true);
+  });
+
+  test('rejects plugin missing permissions', async () => {
+    const plugin = {
+      id: 'test-plugin',
+      type: 'notification',
+      name: 'Test Plugin',
+      version: '1.0.0',
+      apiVersion: CURRENT_API_VERSION,
+    };
+
+    const result = await validatePlugin(plugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, 'declare "permissions" object')).toBe(true);
+  });
+
+  test('rejects plugin with wrong apiVersion', async () => {
+    const plugin = {
+      ...validPlugin,
+      apiVersion: CURRENT_API_VERSION + 1,
+    };
+
+    const result = await validatePlugin(plugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, `expected ${CURRENT_API_VERSION}`)).toBe(true);
+  });
+
+  test('rejects provider plugin missing auth', async () => {
+    const providerPlugin = {
+      ...validPlugin,
+      type: 'provider',
+      fetchUsage: async () => [],
+    };
+
+    const result = await validatePlugin(providerPlugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, 'declare "auth" object')).toBe(true);
+  });
+
+  test('accepts valid provider plugin with auth and fetchUsage', async () => {
+    const providerPlugin = {
+      ...validPlugin,
+      type: 'provider',
+      auth: {
+        discover: async () => undefined,
+        isConfigured: () => true,
+      },
+      fetchUsage: async () => [],
+    };
+
+    const result = await validatePlugin(providerPlugin);
+    expect(result.valid).toBe(true);
+  });
+
+  test('rejects theme plugin missing colors object', async () => {
+    const themePlugin = {
+      ...validPlugin,
+      type: 'theme',
+      colorScheme: 'dark',
+    };
+
+    const result = await validatePlugin(themePlugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, '"colors" object')).toBe(true);
+  });
+
+  test('rejects theme plugin missing colorScheme', async () => {
+    const themePlugin = {
+      ...validPlugin,
+      type: 'theme',
+      colors: { primary: '#fff' },
+    };
+
+    const result = await validatePlugin(themePlugin);
+    expect(result.valid).toBe(false);
+    expect(hasError(result.errors, 'colorScheme')).toBe(true);
+  });
+
+  test('accepts valid theme plugin', async () => {
+    const themePlugin = {
+      ...validPlugin,
+      type: 'theme',
+      colorScheme: 'dark',
+      colors: { primary: '#fff' },
+    };
+
+    const result = await validatePlugin(themePlugin);
+    expect(result.valid).toBe(true);
+  });
+});