meter-ai 0.1.2 → 0.3.0

package/src/index.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { runInit } from './commands/init.js'
+import { runStatus } from './commands/status.js'
+import { runReport } from './commands/report.js'
+import { runHistory } from './commands/history.js'
+import { runConfig } from './commands/config.js'
+import { runUninstall } from './commands/uninstall.js'
+import { runWrap } from './commands/wrap.js'
+import { METER_DIR } from './constants.js'
+
+const [,, command, ...args] = process.argv
+
+const commands: Record<string, () => Promise<void>> = {
+  init: () => runInit({ meterDir: METER_DIR }),
+  status: runStatus,
+  report: runReport,
+  history: () => runHistory(args),
+  config: () => runConfig(args),
+  uninstall: runUninstall,
+  wrap: () => runWrap(args),
+}
+
+async function main() {
+  if (!command || command === '--help' || command === '-h') {
+    console.log(`
+◆ meter — intelligent wrapper for Claude Code
+
+  meter init        Set up PATH shim and config
+  meter status      Show current mode, usage, and config
+  meter report      Weekly digest of usage and costs
+  meter history     Browse past task records
+  meter config      View and set configuration values
+  meter uninstall   Remove meter completely
+`)
+    return
+  }
+
+  const handler = commands[command]
+  if (!handler) {
+    console.error(`Unknown command: ${command}`)
+    process.exit(1)
+  }
+
+  await handler()
+}
+
+main().catch(err => {
+  console.error('[meter error]', err.message)
+  process.exit(1)
+})

package/src/pty/resize.ts

@@ -0,0 +1,15 @@
+export interface TerminalSize {
+  cols: number
+  rows: number
+}
+
+export function getTerminalSize(): TerminalSize {
+  return {
+    cols: process.stdout.columns ?? 80,
+    rows: process.stdout.rows ?? 24,
+  }
+}
+
+export function calculateStatusBarLines(statusBarCharCount: number, cols: number): number {
+  return Math.ceil(statusBarCharCount / cols)
+}

package/src/pty/screen.ts

@@ -0,0 +1,15 @@
+const ENTER_ALT_SCREEN = '\x1b[?1049h'
+const EXIT_ALT_SCREEN = '\x1b[?1049l'
+
+export class AlternateScreenTracker {
+  private _isActive = false
+
+  get isActive(): boolean {
+    return this._isActive
+  }
+
+  process(chunk: string): void {
+    if (chunk.includes(ENTER_ALT_SCREEN)) this._isActive = true
+    if (chunk.includes(EXIT_ALT_SCREEN)) this._isActive = false
+  }
+}

package/src/pty/wrapper.ts

@@ -0,0 +1,143 @@
+import { EventEmitter } from 'events'
+import { spawn as cpSpawn, type ChildProcess } from 'child_process'
+import { AlternateScreenTracker } from './screen.js'
+import { getTerminalSize } from './resize.js'
+
+export interface WrapperEvents {
+  data: (chunk: string) => void
+  input: (prompt: string) => void
+  exit: (code: number, signal: number) => void
+}
+
+type PtyModule = typeof import('node-pty')
+
+/**
+ * PtyWrapper with automatic fallback and input capture.
+ *
+ * In PTY mode:
+ *   - Captures all user input keystroke by keystroke
+ *   - Buffers input and emits 'input' event on Enter (prompt submission)
+ *   - This enables per-prompt estimation during interactive sessions
+ *
+ * In fallback mode:
+ *   - stdio is inherited, no input capture possible
+ */
+export class PtyWrapper extends EventEmitter {
+  private ptyProcess: import('node-pty').IPty | null = null
+  private childProcess: ChildProcess | null = null
+  private screenTracker = new AlternateScreenTracker()
+  private _usingFallback = false
+  private inputBuffer = ''
+
+  get isInAlternateScreen(): boolean {
+    return this.screenTracker.isActive
+  }
+
+  get usingFallback(): boolean {
+    return this._usingFallback
+  }
+
+  spawn(binary: string, args: string[], env: NodeJS.ProcessEnv): void {
+    try {
+      const pty: PtyModule = require('node-pty')
+      this._spawnWithPty(pty, binary, args, env)
+    } catch {
+      this._usingFallback = true
+      this._spawnWithChildProcess(binary, args, env)
+    }
+  }
+
+  private _spawnWithPty(pty: PtyModule, binary: string, args: string[], env: NodeJS.ProcessEnv): void {
+    const size = getTerminalSize()
+
+    this.ptyProcess = pty.spawn(binary, args, {
+      name: process.env.TERM ?? 'xterm-256color',
+      cols: size.cols,
+      rows: size.rows,
+      env: { ...env },
+      cwd: process.cwd(),
+    })
+
+    this.ptyProcess.onData((data: string) => {
+      this.screenTracker.process(data)
+      this.emit('data', data)
+      process.stdout.write(data)
+    })
+
+    this.ptyProcess.onExit(({ exitCode, signal }: { exitCode: number; signal?: number }) => {
+      this.emit('exit', exitCode, signal ?? 0)
+    })
+
+    // Forward stdin to PTY and capture input for per-prompt estimation
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true)
+    }
+    process.stdin.on('data', (data: Buffer) => {
+      const str = data.toString()
+      this.ptyProcess?.write(str)
+
+      // Track user input for prompt detection
+      for (const char of str) {
+        if (char === '\r' || char === '\n') {
+          // Enter pressed — emit the buffered input as a prompt
+          const prompt = this.inputBuffer.trim()
+          if (prompt.length > 0) {
+            this.emit('input', prompt)
+          }
+          this.inputBuffer = ''
+        } else if (char === '\x7f' || char === '\b') {
+          // Backspace — remove last char from buffer
+          this.inputBuffer = this.inputBuffer.slice(0, -1)
+        } else if (char === '\x03') {
+          // Ctrl+C — clear buffer
+          this.inputBuffer = ''
+        } else if (char === '\x15') {
+          // Ctrl+U — clear line
+          this.inputBuffer = ''
+        } else if (char.charCodeAt(0) >= 32) {
+          // Printable character — append to buffer
+          this.inputBuffer += char
+        }
+        // Ignore other control characters (arrows, escape sequences, etc.)
+      }
+    })
+
+    // Handle terminal resize
+    process.on('SIGWINCH', () => {
+      const newSize = getTerminalSize()
+      this.ptyProcess?.resize(newSize.cols, newSize.rows)
+    })
+  }
+
+  private _spawnWithChildProcess(binary: string, args: string[], env: NodeJS.ProcessEnv): void {
+    this.childProcess = cpSpawn(binary, args, {
+      env: { ...env },
+      cwd: process.cwd(),
+      stdio: 'inherit',
+    })
+
+    this.childProcess.on('exit', (code, signal) => {
+      this.emit('exit', code ?? 1, signal ? 1 : 0)
+    })
+  }
+
+  write(data: string): void {
+    if (this.ptyProcess) {
+      this.ptyProcess.write(data)
+    } else if (this.childProcess) {
+      this.childProcess.stdin?.write(data)
+    }
+  }
+
+  kill(signal: NodeJS.Signals = 'SIGTERM'): void {
+    if (this.ptyProcess) {
+      this.ptyProcess.kill(signal)
+    } else if (this.childProcess) {
+      this.childProcess.kill(signal)
+    }
+  }
+
+  resize(cols: number, rows: number): void {
+    this.ptyProcess?.resize(cols, rows)
+  }
+}

package/src/shell/binary-resolver.ts

@@ -0,0 +1,21 @@
+import { access, constants } from 'fs/promises'
+import { join } from 'path'
+
+export async function resolveTrueBinary(
+  name: string,
+  skipDir: string
+): Promise<string | null> {
+  const pathEnv = process.env.PATH ?? ''
+  const dirs = pathEnv.split(':').filter(d => d !== skipDir && d !== '')
+
+  for (const dir of dirs) {
+    const fullPath = join(dir, name)
+    try {
+      await access(fullPath, constants.X_OK)
+      return fullPath
+    } catch {
+      // not found or not executable, continue
+    }
+  }
+  return null
+}

package/src/shell/detect.ts

@@ -0,0 +1,33 @@
+import { homedir } from 'os'
+import { join } from 'path'
+
+export type ShellType = 'zsh' | 'bash' | 'fish' | 'nushell'
+
+export function detectShell(): ShellType {
+  const shell = process.env.SHELL ?? ''
+  if (shell.includes('zsh')) return 'zsh'
+  if (shell.includes('fish')) return 'fish'
+  if (shell.includes('nu')) return 'nushell'
+  return 'bash'
+}
+
+export function getShellConfigPath(shell: ShellType): string {
+  const home = homedir()
+  const paths: Record<ShellType, string> = {
+    zsh: join(home, '.zshrc'),
+    bash: join(home, '.bashrc'),
+    fish: join(home, '.config', 'fish', 'config.fish'),
+    nushell: join(home, '.config', 'nushell', 'env.nu'),
+  }
+  return paths[shell]
+}
+
+export function getPathInjectLine(shell: ShellType): string {
+  const lines: Record<ShellType, string> = {
+    zsh: `export PATH="$HOME/.meter/bin:$PATH" # added by meter`,
+    bash: `export PATH="$HOME/.meter/bin:$PATH" # added by meter`,
+    fish: `fish_add_path ~/.meter/bin # added by meter`,
+    nushell: `$env.PATH = ($env.PATH | prepend ($env.HOME + "/.meter/bin")) # added by meter`,
+  }
+  return lines[shell]
+}

package/src/shell/path-inject.ts

@@ -0,0 +1,31 @@
+import { readFile, writeFile, appendFile } from 'fs/promises'
+import type { ShellType } from './detect.js'
+import { getPathInjectLine } from './detect.js'
+
+const METER_MARKER = '# added by meter'
+
+export async function isPathAlreadyInjected(configPath: string): Promise<boolean> {
+  try {
+    const content = await readFile(configPath, 'utf-8')
+    return content.includes(METER_MARKER)
+  } catch {
+    return false
+  }
+}
+
+export async function injectPath(shell: ShellType, configPath: string): Promise<void> {
+  const already = await isPathAlreadyInjected(configPath)
+  if (already) return
+  const line = getPathInjectLine(shell)
+  await appendFile(configPath, `\n${line}\n`, 'utf-8')
+}
+
+export async function removePath(configPath: string): Promise<void> {
+  try {
+    const content = await readFile(configPath, 'utf-8')
+    const cleaned = content.split('\n').filter(line => !line.includes(METER_MARKER)).join('\n')
+    await writeFile(configPath, cleaned, 'utf-8')
+  } catch {
+    // file may not exist, that's fine
+  }
+}

package/src/shell/shim-writer.ts

@@ -0,0 +1,28 @@
+import { writeFile, mkdir, chmod, access } from 'fs/promises'
+import { dirname } from 'path'
+
+const SHIM_EXEC_TEMPLATE = (trueBinary: string, meterBin: string) =>
+`#!/bin/sh
+# meter shim — do not edit manually
+exec "${meterBin}" wrap "${trueBinary}" "$@"
+`
+
+export async function writeShim(
+  shimPath: string,
+  trueBinary: string,
+  meterEntrypoint?: string
+): Promise<void> {
+  await mkdir(dirname(shimPath), { recursive: true })
+  const content = SHIM_EXEC_TEMPLATE(trueBinary, meterEntrypoint ?? 'meter')
+  await writeFile(shimPath, content, 'utf-8')
+  await chmod(shimPath, 0o755)
+}
+
+export async function shimExists(shimPath: string): Promise<boolean> {
+  try {
+    await access(shimPath)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/storage/config-store.ts

@@ -0,0 +1,46 @@
+import { readFile, writeFile, mkdir } from 'fs/promises'
+import { dirname } from 'path'
+import { DEFAULT_CONFIG_VALUES } from '../constants.js'
+import type { MeterConfig, UserMode } from '../types.js'
+
+export async function readConfig(path: string): Promise<MeterConfig | null> {
+  try {
+    const raw = await readFile(path, 'utf-8')
+    return JSON.parse(raw) as MeterConfig
+  } catch {
+    return null
+  }
+}
+
+export async function writeConfig(path: string, config: MeterConfig): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, JSON.stringify(config, null, 2), 'utf-8')
+}
+
+export function ensureConfigDefaults(
+  partial: Partial<MeterConfig> & { mode: UserMode; resolved_binaries: { claude: string } }
+): MeterConfig {
+  return {
+    version: 1,
+    org_id: partial.org_id,
+    budget: {
+      per_task_usd: DEFAULT_CONFIG_VALUES.budget_per_task_usd,
+      threshold_pct: DEFAULT_CONFIG_VALUES.threshold_pct,
+      action: 'notify',
+    },
+    plan: {
+      window_threshold_pct: DEFAULT_CONFIG_VALUES.window_threshold_pct,
+      action: 'notify',
+    },
+    models: {
+      claude_chain: DEFAULT_CONFIG_VALUES.claude_chain,
+    },
+    estimation: {
+      use_llm_precheck: true,
+      llm_precheck_model: DEFAULT_CONFIG_VALUES.llm_precheck_model,
+      min_confidence_to_skip_llm: DEFAULT_CONFIG_VALUES.min_confidence_to_skip_llm,
+    },
+    poll_interval_seconds: DEFAULT_CONFIG_VALUES.poll_interval_seconds,
+    ...partial,
+  }
+}

package/src/storage/db.ts

@@ -0,0 +1,63 @@
+import { mkdirSync } from 'fs'
+import { dirname } from 'path'
+import type { TaskRecord } from '../types.js'
+import Database from 'better-sqlite3'
+
+export type DB = import('better-sqlite3').Database
+
+export function initDb(path: string): DB {
+  mkdirSync(dirname(path), { recursive: true })
+  const db = new Database(path)
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS tasks (
+      id                INTEGER PRIMARY KEY AUTOINCREMENT,
+      created_at        INTEGER NOT NULL,
+      repo              TEXT,
+      prompt_hash       TEXT NOT NULL,
+      prompt_text       TEXT NOT NULL,
+      model             TEXT NOT NULL,
+      complexity        TEXT NOT NULL,
+      est_layer         INTEGER NOT NULL,
+      est_cost          REAL,
+      actual_tokens_in  INTEGER,
+      actual_tokens_out INTEGER,
+      actual_cost       REAL,
+      window_pct_start  REAL,
+      window_pct_end    REAL,
+      model_switched    INTEGER DEFAULT 0,
+      exit_code         INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_tasks_created_at ON tasks(created_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_tasks_repo ON tasks(repo);
+    CREATE INDEX IF NOT EXISTS idx_tasks_prompt_hash ON tasks(prompt_hash);
+  `)
+
+  return db
+}
+
+export function insertTask(db: DB, task: Omit<TaskRecord, 'id'>): number {
+  const stmt = db.prepare(`
+    INSERT INTO tasks (
+      created_at, repo, prompt_hash, prompt_text, model, complexity,
+      est_layer, est_cost, actual_tokens_in, actual_tokens_out, actual_cost,
+      window_pct_start, window_pct_end, model_switched, exit_code
+    ) VALUES (
+      @created_at, @repo, @prompt_hash, @prompt_text, @model, @complexity,
+      @est_layer, @est_cost, @actual_tokens_in, @actual_tokens_out, @actual_cost,
+      @window_pct_start, @window_pct_end, @model_switched, @exit_code
+    )
+  `)
+  const result = stmt.run(task)
+  return result.lastInsertRowid as number
+}
+
+export function getRecentTasks(db: DB, limit: number): TaskRecord[] {
+  return db.prepare(
+    'SELECT * FROM tasks ORDER BY created_at DESC LIMIT ?'
+  ).all(limit) as TaskRecord[]
+}
+
+export async function openDb(path: string): Promise<DB> {
+  return initDb(path)
+}

package/src/tracking/cost.ts

@@ -0,0 +1,7 @@
+import type { ModelPricing } from '../types.js'
+
+export function calculateCost(tokens: { input: number; output: number }, pricing: ModelPricing): number {
+  const inputCost = (tokens.input / 1_000_000) * pricing.input_per_million
+  const outputCost = (tokens.output / 1_000_000) * pricing.output_per_million
+  return inputCost + outputCost
+}

package/src/tracking/plan-usage.ts

@@ -0,0 +1,57 @@
+import { appendFile, mkdir } from 'fs/promises'
+import { dirname } from 'path'
+import { ERRORS_LOG_PATH, CLAUDE_BOOTSTRAP_API, CLAUDE_USAGE_API } from '../constants.js'
+import type { PlanUsage } from '../types.js'
+import type { ClaudeCredentials } from '../auth/credentials.js'
+
+async function logError(message: string): Promise<void> {
+  await mkdir(dirname(ERRORS_LOG_PATH), { recursive: true })
+  await appendFile(ERRORS_LOG_PATH, `[${new Date().toISOString()}] ${message}\n`)
+}
+
+export async function resolveOrgId(creds: ClaudeCredentials): Promise<string | null> {
+  try {
+    const res = await fetch(CLAUDE_BOOTSTRAP_API, {
+      headers: { Authorization: `Bearer ${creds.accessToken}` }
+    })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const data = await res.json() as { account?: { memberships?: Array<{ organization?: { id: string } }> } }
+    return data?.account?.memberships?.[0]?.organization?.id ?? null
+  } catch (err) {
+    await logError(`bootstrap failed: ${err}`)
+    return null
+  }
+}
+
+export async function fetchPlanUsage(orgId: string, creds: ClaudeCredentials): Promise<PlanUsage | null> {
+  try {
+    const res = await fetch(`${CLAUDE_USAGE_API}/${orgId}/usage`, {
+      headers: { Authorization: `Bearer ${creds.accessToken}` }
+    })
+    if (!res.ok) {
+      await logError(`usage API returned ${res.status}`)
+      return null
+    }
+    const data = await res.json() as {
+      five_hour?: { utilization_pct: number; reset_at: string }
+      seven_day?: { utilization_pct: number }
+    }
+    return {
+      five_hour_pct: data.five_hour?.utilization_pct ?? 0,
+      five_hour_reset_at: data.five_hour?.reset_at ?? '',
+      seven_day_pct: data.seven_day?.utilization_pct ?? 0,
+      fetched_at: Date.now(),
+    }
+  } catch (err) {
+    await logError(`fetchPlanUsage failed: ${err}`)
+    return null
+  }
+}
+
+export function formatResetCountdown(resetAt: string): string {
+  const ms = new Date(resetAt).getTime() - Date.now()
+  if (ms <= 0) return 'resetting...'
+  const h = Math.floor(ms / 3_600_000)
+  const m = Math.floor((ms % 3_600_000) / 60_000)
+  return h > 0 ? `${h}h ${m}m` : `${m}m`
+}

package/src/tracking/tokens.ts

@@ -0,0 +1,16 @@
+export interface TokenCounts { input: number; output: number }
+
+const TOKEN_PATTERN = /tokens?:\s*([\d,]+)\s*input,\s*([\d,]+)\s*output/i
+
+export function parseTokensFromOutput(output: string): TokenCounts | null {
+  const match = TOKEN_PATTERN.exec(output)
+  if (!match) return null
+  return {
+    input: parseInt(match[1].replace(/,/g, ''), 10),
+    output: parseInt(match[2].replace(/,/g, ''), 10),
+  }
+}
+
+export function estimateInputTokens(charCount: number): number {
+  return Math.ceil(charCount / 4)
+}

package/src/types.ts

@@ -0,0 +1,73 @@
+export type UserMode = 'api' | 'plan'
+export type Complexity = 'low' | 'medium' | 'heavy' | 'critical'
+export type EstimationLayer = 1 | 2 | 3
+
+export interface MeterConfig {
+  version: number
+  mode: UserMode
+  resolved_binaries: { claude: string }
+  org_id?: string
+  budget: {
+    per_task_usd: number
+    threshold_pct: number
+    action: 'notify'
+  }
+  plan: {
+    window_threshold_pct: number
+    action: 'notify'
+  }
+  models: {
+    claude_chain: string[]
+  }
+  estimation: {
+    use_llm_precheck: boolean
+    llm_precheck_model: string
+    min_confidence_to_skip_llm: number
+  }
+  poll_interval_seconds: number
+}
+
+export interface TaskRecord {
+  id?: number
+  created_at: number
+  repo: string | null
+  prompt_hash: string
+  prompt_text: string
+  model: string
+  complexity: Complexity
+  est_layer: EstimationLayer
+  est_cost: number | null
+  actual_tokens_in: number | null
+  actual_tokens_out: number | null
+  actual_cost: number | null
+  window_pct_start: number | null
+  window_pct_end: number | null
+  model_switched: number
+  exit_code: number | null
+}
+
+export interface EstimationResult {
+  complexity: Complexity
+  confidence: number
+  estimated_cost: number | null
+  layer_used: EstimationLayer
+}
+
+export interface PlanUsage {
+  five_hour_pct: number
+  five_hour_reset_at: string
+  seven_day_pct: number
+  fetched_at: number
+}
+
+export interface ModelPricing {
+  model: string
+  input_per_million: number
+  output_per_million: number
+  updated_at: number
+}
+
+export interface TokenCounts {
+  input: number
+  output: number
+}

package/src/ui/keypress.ts

@@ -0,0 +1,27 @@
+export type KeypressAction = 's' | 'd' | 'c'
+
+export function waitForKeypress(
+  validKeys: KeypressAction[],
+  timeoutMs: number
+): Promise<KeypressAction | 'timeout'> {
+  return new Promise(resolve => {
+    const cleanup = () => {
+      process.stdin.removeListener('data', onData)
+      clearTimeout(timer)
+    }
+
+    const timer = timeoutMs > 0
+      ? setTimeout(() => { cleanup(); resolve('timeout') }, timeoutMs)
+      : undefined
+
+    const onData = (data: Buffer) => {
+      const key = data.toString().toLowerCase().trim() as KeypressAction
+      if (validKeys.includes(key)) {
+        cleanup()
+        resolve(key)
+      }
+    }
+
+    process.stdin.on('data', onData)
+  })
+}

package/src/ui/notification.ts

@@ -0,0 +1,31 @@
+import type { UserMode } from '../types.js'
+
+export interface NotificationState {
+  mode: UserMode
+  thresholdPct: number
+  elapsedCost: number | null
+  budgetUsd: number | null
+  windowPct: number | null
+  nextModel: string | null
+}
+
+const YELLOW = '\x1b[33m'
+const BOLD = '\x1b[1m'
+const RESET = '\x1b[0m'
+const DIM = '\x1b[2m'
+
+export function renderNotification(state: NotificationState): string {
+  let message: string
+
+  if (state.mode === 'api' && state.elapsedCost !== null && state.budgetUsd !== null) {
+    message = `${YELLOW}⚠  ${state.thresholdPct}% budget hit${RESET}  ($${state.elapsedCost.toFixed(2)} / $${state.budgetUsd.toFixed(2)})`
+  } else {
+    message = `${YELLOW}⚠  ${state.windowPct}% window used${RESET}`
+  }
+
+  const actions = state.nextModel
+    ? `  ${BOLD}[s]${RESET}${DIM}witch to ${state.nextModel}${RESET}  ${BOLD}[d]${RESET}${DIM}ismiss${RESET}  ${BOLD}[c]${RESET}${DIM}ancel${RESET}`
+    : `  ${BOLD}[d]${RESET}${DIM}ismiss${RESET}  ${BOLD}[c]${RESET}${DIM}ancel${RESET}`
+
+  return message + actions
+}