@tokentop/ttop 0.2.2

package/src/plugins/themes/rose-pine-dawn.ts

@@ -0,0 +1,45 @@
+import type { ThemePlugin } from '../types/theme.ts';
+
+export const rosePineDawnTheme: ThemePlugin = {
+  apiVersion: 2,
+  id: 'rose-pine-dawn',
+  type: 'theme',
+  name: 'Rosé Pine Dawn',
+  family: 'rose-pine',
+  version: '1.0.0',
+  permissions: {},
+
+  colorScheme: 'light',
+
+  colors: {
+    background: '#faf4ed',
+    foreground: '#fffaf3',
+    text: '#575279',
+    textMuted: '#797593',
+    textSubtle: '#9893a5',
+    primary: '#907aa9',
+    secondary: '#d7827e',
+    accent: '#56949f',
+    success: '#286983',
+    warning: '#ea9d34',
+    error: '#b4637a',
+    info: '#56949f',
+    border: '#cecacd',
+    borderMuted: '#dfdad9',
+    selection: '#dfdad9',
+    highlight: '#f2e9e1',
+    gaugeBackground: '#dfdad9',
+    gaugeFill: '#907aa9',
+    gaugeWarning: '#ea9d34',
+    gaugeDanger: '#b4637a',
+  },
+
+  components: {
+    header: {
+      background: '#f2e9e1',
+    },
+    statusBar: {
+      background: '#f2e9e1',
+    },
+  },
+};

package/src/plugins/themes/rose-pine.ts

@@ -0,0 +1,45 @@
+import type { ThemePlugin } from '../types/theme.ts';
+
+export const rosePineTheme: ThemePlugin = {
+  apiVersion: 2,
+  id: 'rose-pine',
+  type: 'theme',
+  name: 'Rosé Pine',
+  family: 'rose-pine',
+  version: '1.0.0',
+  permissions: {},
+
+  colorScheme: 'dark',
+
+  colors: {
+    background: '#191724',
+    foreground: '#1f1d2e',
+    text: '#e0def4',
+    textMuted: '#908caa',
+    textSubtle: '#6e6a86',
+    primary: '#c4a7e7',
+    secondary: '#ebbcba',
+    accent: '#9ccfd8',
+    success: '#31748f',
+    warning: '#f6c177',
+    error: '#eb6f92',
+    info: '#9ccfd8',
+    border: '#403d52',
+    borderMuted: '#26233a',
+    selection: '#403d52',
+    highlight: '#26233a',
+    gaugeBackground: '#1f1d2e',
+    gaugeFill: '#c4a7e7',
+    gaugeWarning: '#f6c177',
+    gaugeDanger: '#eb6f92',
+  },
+
+  components: {
+    header: {
+      background: '#1f1d2e',
+    },
+    statusBar: {
+      background: '#1f1d2e',
+    },
+  },
+};

package/src/plugins/themes/solarized-light.ts

@@ -0,0 +1,45 @@
+import type { ThemePlugin } from '../types/theme.ts';
+
+export const solarizedLightTheme: ThemePlugin = {
+  apiVersion: 2,
+  id: 'solarized-light',
+  type: 'theme',
+  name: 'Solarized Light',
+  family: 'solarized',
+  version: '1.0.0',
+  permissions: {},
+
+  colorScheme: 'light',
+
+  colors: {
+    background: '#fdf6e3',
+    foreground: '#eee8d5',
+    text: '#657b83',
+    textMuted: '#839496',
+    textSubtle: '#93a1a1',
+    primary: '#268bd2',
+    secondary: '#6c71c4',
+    accent: '#2aa198',
+    success: '#859900',
+    warning: '#b58900',
+    error: '#dc322f',
+    info: '#268bd2',
+    border: '#93a1a1',
+    borderMuted: '#eee8d5',
+    selection: '#eee8d5',
+    highlight: '#eee8d5',
+    gaugeBackground: '#eee8d5',
+    gaugeFill: '#268bd2',
+    gaugeWarning: '#b58900',
+    gaugeDanger: '#dc322f',
+  },
+
+  components: {
+    header: {
+      background: '#eee8d5',
+    },
+    statusBar: {
+      background: '#eee8d5',
+    },
+  },
+};

package/src/plugins/themes/tokyo-night.ts

@@ -0,0 +1,49 @@
+import type { ThemePlugin } from '../types/theme.ts';
+
+export const tokyoNightTheme: ThemePlugin = {
+  apiVersion: 2,
+  id: 'tokyo-night',
+  type: 'theme',
+  name: 'Tokyo Night',
+  family: 'tokyo-night',
+  version: '1.0.0',
+  permissions: {},
+
+  colorScheme: 'dark',
+
+  colors: {
+    background: '#1a1b26',
+    foreground: '#24283b',
+    text: '#c0caf5',
+    textMuted: '#737aa2',
+    textSubtle: '#565f89',
+    primary: '#7aa2f7',
+    secondary: '#bb9af7',
+    accent: '#7dcfff',
+    success: '#9ece6a',
+    warning: '#e0af68',
+    error: '#f7768e',
+    info: '#7aa2f7',
+    border: '#414868',
+    borderMuted: '#292e42',
+    selection: '#33467c',
+    highlight: '#2f3549',
+    gaugeBackground: '#24283b',
+    gaugeFill: '#7aa2f7',
+    gaugeWarning: '#e0af68',
+    gaugeDanger: '#f7768e',
+  },
+
+  components: {
+    header: {
+      background: '#16161e',
+    },
+    statusBar: {
+      background: '#1f2335',
+    },
+    gauge: {
+      height: 1,
+      borderRadius: 0,
+    },
+  },
+};

package/src/plugins/types/agent.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import type { BasePlugin, PluginHttpClient, PluginLogger } from './base.ts';
+import type { Credentials, OAuthCredentials, PluginContext } from './provider.ts';
+
+export const AgentCapabilitiesSchema = z.object({
+  sessionParsing: z.boolean(),
+  authReading: z.boolean(),
+  realTimeTracking: z.boolean(),
+  multiProvider: z.boolean(),
+});
+
+export type AgentCapabilities = z.infer<typeof AgentCapabilitiesSchema>;
+
+export interface AgentConfig {
+  /** Display name for this coding agent (e.g. "OpenCode", "Cursor"). */
+  name: string;
+  /** CLI command that launches the agent (for display/detection). */
+  command?: string;
+  /** Path to the agent's config directory (for display/debugging). */
+  configPath?: string;
+  /** Path to the agent's session storage. */
+  sessionPath?: string;
+  /** Path to the agent's auth file (for credential reading). */
+  authPath?: string;
+}
+
+export interface AgentCredentials {
+  providers: Record<string, Credentials | undefined>;
+  oauth?: Record<string, OAuthCredentials>;
+}
+
+export interface AgentProviderConfig {
+  id: string;
+  name: string;
+  configured: boolean;
+  enabled?: boolean;
+}
+
+export interface SessionParseOptions {
+  sessionId?: string;
+  timePeriod?: 'session' | 'daily' | 'weekly' | 'monthly';
+  limit?: number;
+  /** Epoch ms — only return sessions updated after this timestamp. */
+  since?: number;
+}
+
+export interface SessionUsageData {
+  sessionId: string;
+  sessionName?: string;
+  providerId: string;
+  modelId: string;
+  tokens: {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  timestamp: number;
+  sessionUpdatedAt?: number;
+  projectPath?: string;
+  cost?: number;
+}
+
+export interface AgentFetchContext {
+  readonly http: PluginHttpClient;
+  readonly logger: PluginLogger;
+  readonly config: Record<string, unknown>;
+  readonly signal: AbortSignal;
+}
+
+export interface ActivityUpdate {
+  sessionId: string;
+  messageId: string;
+  tokens: {
+    input: number;
+    output: number;
+    reasoning?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  timestamp: number;
+}
+
+export type ActivityCallback = (update: ActivityUpdate) => void;
+
+export interface AgentPlugin extends BasePlugin {
+  readonly type: 'agent';
+  readonly agent: AgentConfig;
+  readonly capabilities: AgentCapabilities;
+
+  /** Check if this coding agent is installed on the user's machine. */
+  isInstalled(ctx: PluginContext): Promise<boolean>;
+
+  /** Read credentials that the coding agent has stored. */
+  readCredentials?(ctx: AgentFetchContext): Promise<AgentCredentials>;
+
+  /** Parse session usage data from the agent's local storage. */
+  parseSessions(options: SessionParseOptions, ctx: AgentFetchContext): Promise<SessionUsageData[]>;
+
+  /** List which model providers this agent is configured to use. */
+  getProviders?(ctx: AgentFetchContext): Promise<AgentProviderConfig[]>;
+
+  /** Start watching for real-time activity updates. */
+  startActivityWatch?(ctx: PluginContext, callback: ActivityCallback): void;
+
+  /** Stop watching for real-time activity updates. */
+  stopActivityWatch?(ctx: PluginContext): void;
+}

package/src/plugins/types/base.ts

@@ -0,0 +1,267 @@
+/**
+ * Base plugin types and interfaces for the tokentop plugin system.
+ *
+ * These types mirror the Plugin SDK (@tokentop/plugin-sdk) — the SDK is the
+ * authoritative contract for community developers; core adapts to match.
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+
+/**
+ * Plugin type discriminator
+ */
+export type PluginType = 'provider' | 'agent' | 'theme' | 'notification';
+
+/**
+ * Current API contract version.
+ * Core checks this at load time to ensure compatibility.
+ */
+export const CURRENT_API_VERSION = 2;
+
+// ---------------------------------------------------------------------------
+// Permissions
+// ---------------------------------------------------------------------------
+
+/**
+ * Plugin permissions schema - defines what a plugin can access
+ */
+export const PluginPermissionsSchema = z.object({
+  network: z.object({
+    enabled: z.boolean(),
+    allowedDomains: z.array(z.string()).optional(),
+  }).optional(),
+  filesystem: z.object({
+    read: z.boolean().optional(),
+    write: z.boolean().optional(),
+    paths: z.array(z.string()).optional(),
+  }).optional(),
+  env: z.object({
+    read: z.boolean().optional(),
+    vars: z.array(z.string()).optional(),
+  }).optional(),
+  system: z.object({
+    notifications: z.boolean().optional(),
+    clipboard: z.boolean().optional(),
+  }).optional(),
+});
+
+export type PluginPermissions = z.infer<typeof PluginPermissionsSchema>;
+
+// ---------------------------------------------------------------------------
+// Metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * Plugin metadata
+ */
+export const PluginMetaSchema = z.object({
+  author: z.string().optional(),
+  description: z.string().optional(),
+  homepage: z.string().url().optional(),
+  repository: z.string().url().optional(),
+  license: z.string().optional(),
+  /**
+   * Brand color as a hex string (e.g. `"#d97757"`).
+   * Used by the TUI for provider cards, charts, and status indicators.
+   */
+  brandColor: z.string().optional(),
+  /**
+   * Single-character icon or short glyph for compact displays.
+   * Example: `"◆"`, `"▲"`, `"⚡"`
+   */
+  icon: z.string().optional(),
+  /**
+   * Additional provider IDs that should resolve to this plugin.
+   * Coding agents may tag sessions with provider IDs that differ from
+   * the plugin's `id` (e.g. OpenCode uses `"openai"` but the plugin
+   * registers as `"openai-api"`). List those alternate IDs here so the
+   * TUI can resolve brand colors and other metadata correctly.
+   */
+  providerAliases: z.array(z.string()).optional(),
+});
+
+export type PluginMeta = z.infer<typeof PluginMetaSchema>;
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Plugin configuration field definition (for plugin settings UI)
+ */
+export interface ConfigField {
+  /** Data type of the setting value. */
+  type: 'string' | 'number' | 'boolean' | 'select';
+  /** Label shown in the settings UI. */
+  label?: string;
+  /** Help text shown below the field. */
+  description?: string;
+  /** Whether the field must have a value. */
+  required?: boolean;
+  /** Default value when no user config exists. */
+  default?: unknown;
+  /** Available options (for `select` type only). */
+  options?: Array<{ value: string; label: string }>;
+  /** Minimum value (for `number` type only). */
+  min?: number;
+  /** Maximum value (for `number` type only). */
+  max?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle Context
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal context provided to lifecycle hooks.
+ */
+export interface PluginLifecycleContext {
+  /** Plugin's validated configuration values. */
+  readonly config: Record<string, unknown>;
+  /** Scoped logger that prefixes all output with the plugin ID. */
+  readonly logger: PluginLogger;
+}
+
+// ---------------------------------------------------------------------------
+// Base Plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * Base plugin interface - all plugins must implement this.
+ *
+ * Provides identity, metadata, permissions, optional configuration schema,
+ * and lifecycle hooks.
+ */
+export interface BasePlugin {
+  /** API version this plugin targets. Must equal {@link CURRENT_API_VERSION}. */
+  readonly apiVersion: 2;
+
+  /** Unique plugin identifier (kebab-case) */
+  readonly id: string;
+
+  /** Plugin type discriminator */
+  readonly type: PluginType;
+
+  /** Human-readable display name */
+  readonly name: string;
+
+  /** Semantic version string */
+  readonly version: string;
+
+  /** Plugin metadata */
+  readonly meta?: PluginMeta;
+
+  /** Required permissions */
+  readonly permissions: PluginPermissions;
+
+  /** Plugin-declared configuration fields, rendered in Settings UI */
+  readonly configSchema?: Record<string, ConfigField>;
+
+  /**
+   * Default config values. Used when no user configuration exists.
+   * Keys must match those in {@link configSchema}.
+   */
+  readonly defaultConfig?: Record<string, unknown>;
+
+  // -- Lifecycle Hooks (all optional) -------------------------------------
+
+  /**
+   * Called once after the plugin is loaded and validated.
+   * Use for one-time setup (open connections, allocate resources).
+   */
+  initialize?(ctx: PluginLifecycleContext): Promise<void>;
+
+  /**
+   * Called when the plugin should begin active work (e.g. polling).
+   * Called after `initialize()` during app startup, and after re-enable.
+   */
+  start?(ctx: PluginLifecycleContext): Promise<void>;
+
+  /**
+   * Called when the plugin should pause active work.
+   * Called before `destroy()` during app shutdown, and on disable.
+   */
+  stop?(ctx: PluginLifecycleContext): Promise<void>;
+
+  /**
+   * Called once before the plugin is unloaded.
+   * Use for cleanup (close connections, flush buffers).
+   */
+  destroy?(ctx: PluginLifecycleContext): Promise<void>;
+
+  /**
+   * Called when the user changes this plugin's configuration.
+   * Receive the new validated config values.
+   */
+  onConfigChange?(config: Record<string, unknown>, ctx: PluginLifecycleContext): Promise<void> | void;
+}
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+/**
+ * Logger interface provided to plugins
+ */
+export interface PluginLogger {
+  debug(message: string, data?: Record<string, unknown>): void;
+  info(message: string, data?: Record<string, unknown>): void;
+  warn(message: string, data?: Record<string, unknown>): void;
+  error(message: string, data?: Record<string, unknown>): void;
+}
+
+// ---------------------------------------------------------------------------
+// HTTP Client
+// ---------------------------------------------------------------------------
+
+/**
+ * HTTP client interface provided to plugins (sandboxed)
+ */
+export interface PluginHttpClient {
+  fetch(url: string, init?: RequestInit): Promise<Response>;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Plugin validation result
+ */
+export interface PluginValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Plugin load result
+ */
+export interface PluginLoadResult<T extends BasePlugin = BasePlugin> {
+  success: boolean;
+  plugin?: T;
+  error?: string;
+  source: 'builtin' | 'local' | 'npm';
+}
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+/**
+ * Plugin permission error
+ */
+export class PluginPermissionError extends Error {
+  constructor(
+    public readonly pluginId: string,
+    public readonly permission: keyof PluginPermissions,
+    message: string
+  ) {
+    super(`Plugin "${pluginId}" permission denied: ${message}`);
+    this.name = 'PluginPermissionError';
+  }
+}

package/src/plugins/types/index.ts

@@ -0,0 +1,19 @@
+export * from './base.ts';
+export * from './provider.ts';
+export * from './agent.ts';
+export * from './theme.ts';
+export * from './notification.ts';
+
+import type { ProviderPlugin } from './provider.ts';
+import type { AgentPlugin } from './agent.ts';
+import type { ThemePlugin } from './theme.ts';
+import type { NotificationPlugin } from './notification.ts';
+
+export type AnyPlugin = ProviderPlugin | AgentPlugin | ThemePlugin | NotificationPlugin;
+
+export type PluginByType = {
+  provider: ProviderPlugin;
+  agent: AgentPlugin;
+  theme: ThemePlugin;
+  notification: NotificationPlugin;
+};

package/src/plugins/types/notification.ts

@@ -0,0 +1,51 @@
+import type { BasePlugin, PluginLogger } from './base.ts';
+
+// ---------------------------------------------------------------------------
+// Notification Events
+// ---------------------------------------------------------------------------
+
+export type NotificationSeverity = 'info' | 'warning' | 'critical';
+
+export type NotificationEventType =
+  | 'budget.thresholdCrossed'
+  | 'budget.limitReached'
+  | 'provider.fetchFailed'
+  | 'provider.limitReached'
+  | 'provider.recovered'
+  | 'plugin.crashed'
+  | 'plugin.disabled'
+  | 'app.started'
+  | 'app.updated';
+
+export interface NotificationEvent {
+  type: NotificationEventType;
+  severity: NotificationSeverity;
+  title: string;
+  message: string;
+  timestamp: number;
+  data?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Notification Context
+// ---------------------------------------------------------------------------
+
+export interface NotificationContext {
+  readonly logger: PluginLogger;
+  readonly config: Record<string, unknown>;
+  readonly signal: AbortSignal;
+}
+
+// ---------------------------------------------------------------------------
+// Notification Plugin
+// ---------------------------------------------------------------------------
+
+export interface NotificationPlugin extends BasePlugin {
+  readonly type: 'notification';
+
+  initialize(ctx: NotificationContext): Promise<void>;
+  notify(ctx: NotificationContext, event: NotificationEvent): Promise<void>;
+  test?(ctx: NotificationContext): Promise<boolean>;
+  supports?(event: NotificationEvent): boolean;
+  destroy?(): Promise<void>;
+}