@tokentop/ttop 0.2.2

package/src/plugins/types/provider.ts

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

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

package/src/plugins/update-checker.ts

@@ -0,0 +1,177 @@
+/**
+ * Plugin update checker.
+ *
+ * Queries the npm registry for the latest published version of each
+ * npm-sourced plugin and compares it to the currently installed version.
+ * Results are cached for the lifetime of the process (one check per plugin).
+ *
+ * Only npm-published plugins are checked — builtin and local plugins are
+ * skipped because they have no registry entry to compare against.
+ */
+
+import type { PluginType } from './types/base.ts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PluginUpdateInfo {
+  /** npm package name (e.g. "@tokentop/agent-opencode") */
+  packageName: string;
+  /** Currently installed version */
+  currentVersion: string;
+  /** Latest version on the registry, or null if the lookup failed */
+  latestVersion: string | null;
+  /** True when latestVersion is newer than currentVersion */
+  hasUpdate: boolean;
+  /** Non-null when the registry fetch failed */
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Simple semver comparison (major.minor.patch only, no pre-release)
+// ---------------------------------------------------------------------------
+
+function parseVersion(v: string): [number, number, number] | null {
+  const clean = v.replace(/^v/, '');
+  const match = clean.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/**
+ * Returns true if `latest` is strictly newer than `current`.
+ */
+function isNewer(current: string, latest: string): boolean {
+  const a = parseVersion(current);
+  const b = parseVersion(latest);
+  if (!a || !b) return false;
+  if (b[0] !== a[0]) return b[0] > a[0];
+  if (b[1] !== a[1]) return b[1] > a[1];
+  return b[2] > a[2];
+}
+
+// ---------------------------------------------------------------------------
+// npm registry fetcher
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch the latest dist-tag version for `packageName` from the npm registry.
+ * Uses the abbreviated metadata endpoint for minimal payload.
+ */
+async function fetchLatestVersion(packageName: string): Promise<string> {
+  const url = `https://registry.npmjs.org/${encodeURIComponent(packageName).replace('%40', '@')}`;
+  const res = await fetch(url, {
+    headers: { Accept: 'application/vnd.npm.install-v1+json' },
+    signal: AbortSignal.timeout(8_000),
+  });
+
+  if (!res.ok) {
+    throw new Error(`npm registry returned ${res.status} for ${packageName}`);
+  }
+
+  const data = (await res.json()) as { 'dist-tags'?: { latest?: string } };
+  const latest = data?.['dist-tags']?.latest;
+  if (!latest) {
+    throw new Error(`No dist-tags.latest found for ${packageName}`);
+  }
+  return latest;
+}
+
+// ---------------------------------------------------------------------------
+// Package name convention
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the npm package name from a plugin's id and type.
+ *
+ * Convention:
+ *   Official → @tokentop/{type}-{id}   (e.g. @tokentop/agent-opencode)
+ *   Community → tokentop-{type}-{id}   (e.g. tokentop-provider-replicate)
+ *
+ * Since we can't know whether a given plugin is official or community from
+ * the plugin object alone, we check the official name first and fall back
+ * to the community pattern if the registry 404s.
+ */
+export function derivePackageName(pluginId: string, pluginType: PluginType): string {
+  return `@tokentop/${pluginType}-${pluginId}`;
+}
+
+// ---------------------------------------------------------------------------
+// Update checker
+// ---------------------------------------------------------------------------
+
+/** In-memory cache: packageName → PluginUpdateInfo */
+const cache = new Map<string, PluginUpdateInfo>();
+
+/**
+ * Check a single plugin for updates.
+ * Returns cached result if already checked this session.
+ */
+export async function checkPluginUpdate(
+  pluginId: string,
+  pluginType: PluginType,
+  currentVersion: string,
+  packageName?: string,
+): Promise<PluginUpdateInfo> {
+  const pkg = packageName ?? derivePackageName(pluginId, pluginType);
+
+  const cached = cache.get(pkg);
+  if (cached) return cached;
+
+  try {
+    const latestVersion = await fetchLatestVersion(pkg);
+    const info: PluginUpdateInfo = {
+      packageName: pkg,
+      currentVersion,
+      latestVersion,
+      hasUpdate: isNewer(currentVersion, latestVersion),
+    };
+    cache.set(pkg, info);
+    return info;
+  } catch (err) {
+    const info: PluginUpdateInfo = {
+      packageName: pkg,
+      currentVersion,
+      latestVersion: null,
+      hasUpdate: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+    cache.set(pkg, info);
+    return info;
+  }
+}
+
+export interface CheckablePlugin {
+  id: string;
+  type: PluginType;
+  version: string;
+  /** Override the derived package name (for npm-installed plugins whose spec is known) */
+  packageName?: string;
+}
+
+/**
+ * Check multiple plugins for updates in parallel.
+ * Only checks plugins that appear to be npm-published (official or community naming).
+ * Returns a Map keyed by `{type}-{id}` for easy lookup.
+ */
+export async function checkAllPluginUpdates(
+  plugins: CheckablePlugin[],
+): Promise<Map<string, PluginUpdateInfo>> {
+  const results = new Map<string, PluginUpdateInfo>();
+
+  const checks = plugins.map(async (p) => {
+    const info = await checkPluginUpdate(p.id, p.type, p.version, p.packageName);
+    results.set(`${p.type}-${p.id}`, info);
+  });
+
+  await Promise.allSettled(checks);
+  return results;
+}
+
+/**
+ * Clear the in-memory cache (useful for manual refresh).
+ */
+export function clearUpdateCache(): void {
+  cache.clear();
+}

package/src/pricing/estimator.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, test } from 'bun:test';
+import type { ModelPricing } from '@/plugins/types/provider.ts';
+import {
+  estimateCost,
+  estimateSessionCost,
+  formatCost,
+  formatTokenCount,
+} from './estimator.ts';
+
+describe('estimateCost()', () => {
+  test('calculates input and output costs for a typical coding session', () => {
+    const usage = { input: 150_000, output: 50_000 };
+    const pricing: ModelPricing = { input: 3, output: 15 };
+
+    expect(estimateCost(usage, pricing)).toEqual({
+      total: 1.2,
+      input: 0.45,
+      output: 0.75,
+      currency: 'USD',
+    });
+  });
+
+  test('includes cache read and write costs when both usage and pricing are present', () => {
+    const usage = { input: 100_000, output: 25_000, cacheRead: 80_000, cacheWrite: 40_000 };
+    const pricing: ModelPricing = {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3,
+      cacheWrite: 3.75,
+    };
+
+    expect(estimateCost(usage, pricing)).toEqual({
+      total: 0.849,
+      input: 0.3,
+      output: 0.375,
+      cacheRead: 0.024,
+      cacheWrite: 0.15,
+      currency: 'USD',
+    });
+  });
+
+  test('does not include cache fields when cache pricing is unavailable', () => {
+    const usage = { input: 10_000, output: 20_000, cacheRead: 5_000, cacheWrite: 7_000 };
+    const pricing: ModelPricing = { input: 2, output: 8 };
+
+    expect(estimateCost(usage, pricing)).toEqual({
+      total: 0.18,
+      input: 0.02,
+      output: 0.16,
+      currency: 'USD',
+    });
+  });
+
+  test('returns zero cost for zero token usage', () => {
+    const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+    const pricing: ModelPricing = { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 };
+
+    expect(estimateCost(usage, pricing)).toEqual({
+      total: 0,
+      input: 0,
+      output: 0,
+      currency: 'USD',
+    });
+  });
+
+  test('handles very large token counts correctly', () => {
+    const usage = {
+      input: 123_456_789,
+      output: 987_654_321,
+      cacheRead: 55_555_555,
+      cacheWrite: 44_444_444,
+    };
+    const pricing: ModelPricing = {
+      input: 1.25,
+      output: 10,
+      cacheRead: 0.1,
+      cacheWrite: 1,
+    };
+
+    expect(estimateCost(usage, pricing)).toEqual({
+      total: 10080.864196,
+      input: 154.320986,
+      output: 9876.54321,
+      cacheRead: 5.555556,
+      cacheWrite: 44.444444,
+      currency: 'USD',
+    });
+  });
+
+  test('rounds costs to six decimal places', () => {
+    const usage = { input: 1, output: 1 };
+    const pricing: ModelPricing = { input: 1.234567, output: 2.345678 };
+
+    expect(estimateCost(usage, pricing)).toEqual({
+      total: 0.000004,
+      input: 0.000001,
+      output: 0.000002,
+      currency: 'USD',
+    });
+  });
+});
+
+describe('estimateSessionCost()', () => {
+  test('aggregates multiple sessions before estimating cost', () => {
+    const sessions = [
+      { input: 100_000, output: 20_000, cacheRead: 10_000, cacheWrite: 5_000 },
+      { input: 50_000, output: 10_000, cacheRead: 5_000, cacheWrite: 10_000 },
+      { input: 25_000, output: 5_000 },
+    ];
+    const pricing: ModelPricing = {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3,
+      cacheWrite: 3.75,
+    };
+
+    expect(estimateSessionCost(sessions, pricing)).toEqual({
+      total: 1.11075,
+      input: 0.525,
+      output: 0.525,
+      cacheRead: 0.0045,
+      cacheWrite: 0.05625,
+      currency: 'USD',
+    });
+  });
+
+  test('returns zero cost for an empty session list', () => {
+    const pricing: ModelPricing = { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 };
+
+    expect(estimateSessionCost([], pricing)).toEqual({
+      total: 0,
+      input: 0,
+      output: 0,
+      currency: 'USD',
+    });
+  });
+
+  test('matches estimateCost for a single session', () => {
+    const session = { input: 150_000, output: 50_000, cacheRead: 80_000, cacheWrite: 40_000 };
+    const pricing: ModelPricing = {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3,
+      cacheWrite: 3.75,
+    };
+
+    expect(estimateSessionCost([session], pricing)).toEqual(estimateCost(session, pricing));
+  });
+});
+
+describe('formatCost()', () => {
+  test('formats USD costs below $0.01 with 4 decimal places', () => {
+    expect(formatCost(0.009876)).toBe('$0.0099');
+  });
+
+  test('formats USD costs below $1 with 3 decimal places', () => {
+    expect(formatCost(0.45678)).toBe('$0.457');
+  });
+
+  test('formats USD costs at or above $1 with 2 decimal places', () => {
+    expect(formatCost(12.3456)).toBe('$12.35');
+  });
+
+  test('formats non-USD currency with 4 decimals and currency suffix', () => {
+    expect(formatCost(12.3456, 'EUR')).toBe('12.3456 EUR');
+  });
+});
+
+describe('formatTokenCount()', () => {
+  test('returns raw token count for values below 1K', () => {
+    expect(formatTokenCount(999)).toBe('999');
+  });
+
+  test('formats token count in K for values below 1M', () => {
+    expect(formatTokenCount(12_500)).toBe('12.5K');
+  });
+
+  test('formats token count in M for values at or above 1M', () => {
+    expect(formatTokenCount(2_345_678)).toBe('2.35M');
+  });
+});