@tokentop/ttop 0.4.0 → 0.5.0

package/src/plugins/types/base.ts

@@ -1,278 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-export * from "./agent.ts";
-export * from "./base.ts";
-export * from "./notification.ts";
-export * from "./provider.ts";
-export * from "./theme.ts";
-
-import type { AgentPlugin } from "./agent.ts";
-import type { NotificationPlugin } from "./notification.ts";
-import type { ProviderPlugin } from "./provider.ts";
-import type { ThemePlugin } from "./theme.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

@@ -1,51 +0,0 @@
-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>;
-}

package/src/plugins/types/provider.ts

@@ -1,237 +0,0 @@
-import type { BasePlugin, PluginHttpClient, PluginLogger } from "./base.ts";
-
-export interface ProviderCapabilities {
-  usageLimits: boolean;
-  apiRateLimits: boolean;
-  tokenUsage: boolean;
-  actualCosts: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Credential types
-// ---------------------------------------------------------------------------
-
-export interface Credentials {
-  apiKey?: string;
-  oauth?: OAuthCredentials;
-  groupId?: string;
-  source: "env" | "opencode" | "external" | "config";
-}
-
-export interface OAuthCredentials {
-  accessToken: string;
-  refreshToken?: string;
-  expiresAt?: number;
-  accountId?: string;
-  managedProjectId?: string;
-}
-
-export interface RefreshedCredentials {
-  accessToken: string;
-  refreshToken: string;
-  expiresAt: number;
-}
-
-// ---------------------------------------------------------------------------
-// Auth (plugin-owned discovery)
-// ---------------------------------------------------------------------------
-
-/** Result of a credential discovery attempt. */
-export interface CredentialResult {
-  ok: boolean;
-  credentials?: Credentials;
-  reason?: "missing" | "expired" | "invalid" | "error";
-  message?: string;
-}
-
-/**
- * Shape of an entry in OpenCode's auth.json file.
- * Used by AuthSources.opencode.getProviderEntry().
- */
-export interface OpenCodeAuthEntry {
-  type: "api" | "oauth" | "codex" | "github" | "wellknown";
-  key?: string;
-  access?: string;
-  refresh?: string;
-  expires?: number;
-  token?: string;
-  accessToken?: string;
-  refreshToken?: string;
-  expiresAt?: number;
-  accountId?: string;
-  groupId?: string;
-}
-
-/**
- * Sandboxed auth source helpers injected into plugins.
- * All methods respect the plugin's declared permissions.
- */
-export interface AuthSources {
-  /** Read an environment variable (sandboxed to `permissions.env.vars`). */
-  env: {
-    get(name: string): string | undefined;
-  };
-
-  /** Read files from the filesystem (sandboxed to `permissions.filesystem.paths`). */
-  files: {
-    readText(path: string): Promise<string | null>;
-    readJson<T = unknown>(path: string): Promise<T | null>;
-    exists(path: string): Promise<boolean>;
-  };
-
-  /**
-   * Read from OpenCode's auth storage.
-   * Core handles locating the auth file; plugin provides the provider key.
-   */
-  opencode: {
-    getProviderEntry(key: string): Promise<OpenCodeAuthEntry | null>;
-  };
-
-  /** Platform information for cross-platform credential path resolution. */
-  platform: {
-    os: "darwin" | "linux" | "win32";
-    homedir: string;
-    arch: string;
-  };
-}
-
-/** Per-plugin key-value storage (namespaced by plugin ID). */
-export interface PluginStorage {
-  get(key: string): Promise<string | null>;
-  set(key: string, value: string): Promise<void>;
-  delete(key: string): Promise<void>;
-  has(key: string): Promise<boolean>;
-}
-
-/** Full runtime context provided to plugin methods like `auth.discover()`. */
-export interface PluginContext {
-  /** Plugin's validated configuration values. */
-  readonly config: Record<string, unknown>;
-  /** Scoped logger. */
-  readonly logger: PluginLogger;
-  /** Sandboxed HTTP client. */
-  readonly http: PluginHttpClient;
-  /** Credential discovery helpers. */
-  readonly authSources: AuthSources;
-  /** Per-plugin persistent key-value storage. */
-  readonly storage: PluginStorage;
-  /** Abort signal — fired when the plugin is being stopped or the app is shutting down. */
-  readonly signal: AbortSignal;
-}
-
-export interface ProviderAuth {
-  /** Discover credentials using the provided context helpers. */
-  discover(ctx: PluginContext): Promise<CredentialResult>;
-  /** Check whether discovered credentials are sufficient to operate. */
-  isConfigured(credentials: Credentials): boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Pricing
-// ---------------------------------------------------------------------------
-
-export interface ModelPricing {
-  input: number;
-  output: number;
-  cacheRead?: number;
-  cacheWrite?: number;
-  source?: string;
-}
-
-/** Pricing configuration for a provider's models. */
-export interface ProviderPricing {
-  /**
-   * Map a model ID to the identifier used by the pricing service.
-   * Return `undefined` to use the model ID as-is.
-   */
-  mapModelId?(modelId: string): string | undefined;
-  /**
-   * The provider ID to use when querying models.dev.
-   * Defaults to `plugin.id` if not specified.
-   */
-  modelsDevProviderId?: string;
-  /** Static fallback prices keyed by model ID. */
-  staticPrices?: Record<string, ModelPricing>;
-}
-
-// ---------------------------------------------------------------------------
-// Usage data
-// ---------------------------------------------------------------------------
-
-export interface UsageLimit {
-  usedPercent: number | null;
-  resetsAt?: number;
-  label?: string;
-  windowMinutes?: number;
-}
-
-export interface CostBreakdown {
-  total: number;
-  input?: number;
-  output?: number;
-  cacheRead?: number;
-  cacheWrite?: number;
-  currency: string;
-}
-
-export interface ProviderUsageData {
-  planType?: string;
-  allowed?: boolean;
-  limitReached?: boolean;
-  limits?: {
-    primary?: UsageLimit;
-    secondary?: UsageLimit;
-    items?: UsageLimit[];
-  };
-  tokens?: {
-    input: number;
-    output: number;
-    cacheRead?: number;
-    cacheWrite?: number;
-  };
-  credits?: {
-    hasCredits: boolean;
-    unlimited: boolean;
-    balance?: string;
-  };
-  cost?: {
-    actual?: CostBreakdown;
-    estimated?: CostBreakdown;
-    /** Session-derived daily cost (today only). Set by enrichment hook. */
-    estimatedDaily?: CostBreakdown;
-    /** Session-derived monthly cost (MTD). Set by enrichment hook. */
-    estimatedMonthly?: CostBreakdown;
-    source: "api" | "estimated";
-  };
-  fetchedAt: number;
-  error?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Fetch context
-// ---------------------------------------------------------------------------
-
-export interface ProviderFetchContext {
-  readonly credentials: Credentials;
-  readonly http: PluginHttpClient;
-  readonly logger: PluginLogger;
-  readonly config: Record<string, unknown>;
-  readonly signal: AbortSignal;
-  readonly options?: {
-    timePeriod?: "session" | "daily" | "weekly" | "monthly";
-    sessionId?: string;
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Provider Plugin
-// ---------------------------------------------------------------------------
-
-export interface ProviderPlugin extends BasePlugin {
-  readonly type: "provider";
-  readonly capabilities: ProviderCapabilities;
-  readonly auth: ProviderAuth;
-  readonly pricing?: ProviderPricing;
-  fetchUsage(ctx: ProviderFetchContext): Promise<ProviderUsageData>;
-  refreshToken?(auth: OAuthCredentials): Promise<RefreshedCredentials>;
-}

package/src/plugins/types/theme.ts

@@ -1,78 +0,0 @@
-import { z } from "zod";
-import type { BasePlugin } from "./base.ts";
-
-export const ThemeColorsSchema = z.object({
-  background: z.string(),
-  foreground: z.string(),
-  text: z.string(),
-  textMuted: z.string(),
-  textSubtle: z.string(),
-  primary: z.string(),
-  secondary: z.string(),
-  accent: z.string(),
-  success: z.string(),
-  warning: z.string(),
-  error: z.string(),
-  info: z.string(),
-  border: z.string(),
-  borderMuted: z.string(),
-  selection: z.string(),
-  highlight: z.string(),
-  gaugeBackground: z.string(),
-  gaugeFill: z.string(),
-  gaugeWarning: z.string(),
-  gaugeDanger: z.string(),
-});
-
-export type ThemeColors = z.infer<typeof ThemeColorsSchema>;
-
-export const ThemeComponentsSchema = z.object({
-  header: z
-    .object({
-      background: z.string().optional(),
-      foreground: z.string().optional(),
-      titleColor: z.string().optional(),
-      titleAccentColor: z.string().optional(),
-    })
-    .optional(),
-  statusBar: z
-    .object({
-      background: z.string().optional(),
-      foreground: z.string().optional(),
-    })
-    .optional(),
-  commandPalette: z
-    .object({
-      background: z.string().optional(),
-      border: z.string().optional(),
-    })
-    .optional(),
-  gauge: z
-    .object({
-      height: z.number().optional(),
-      borderRadius: z.number().optional(),
-    })
-    .optional(),
-});
-
-export type ThemeComponents = z.infer<typeof ThemeComponentsSchema>;
-
-export type ColorScheme = "light" | "dark";
-
-export type ColorSchemePreference = "auto" | "light" | "dark";
-
-export interface ThemePlugin extends BasePlugin {
-  readonly type: "theme";
-  readonly family: string;
-  readonly colorScheme: ColorScheme;
-  readonly colors: ThemeColors;
-  readonly components?: ThemeComponents;
-}
-
-export interface ResolvedTheme {
-  id: string;
-  name: string;
-  colorScheme: ColorScheme;
-  colors: ThemeColors;
-  components: ThemeComponents;
-}