cluvo-plugin

Cluvo

Bug reports should be as easy to file as they are to ignore.

Cluvo is a local-first bug reporting SDK for open-source CLIs and SDKs. It captures errors, sanitizes sensitive data on-device, lets users review everything before it goes anywhere, and publishes debug-ready GitHub issues.

No server, no dashboard, no telemetry. All processing happens on the user's machine until they explicitly choose to submit.

Features

• Automatic Error Capture: Collects error, stack trace, OS, runtime, architecture, command args, and git SHA
• On-Device Sanitization: Strips tokens, passwords, API keys, emails, and home paths before the user ever sees a report
• Duplicate Detection: Searches existing GitHub issues and discussions before creating new ones
• User Consent First: Interactive TTY prompts let users review and decide what happens with their data
• Zero-Server Architecture: No backend, no sign-up, no API keys required to get started
• Fallback Publishing: Browser → gh CLI → GitHub API → local file export, always succeeds
• Local Report Storage: Stores reports at ~/.cluvo/reports/ for later review, submission, or cleanup

Getting Started

Requirements

• Node.js 18 or later (or Bun 1.3+)

Install

npm install @cluvo/sdk
# or
bun add @cluvo/sdk

For the CLI management tool:

npm install -g @cluvo/cli
# or
bun add -g @cluvo/cli

CLI app

Use the cli preset (default) when integrating into an interactive command-line tool. It auto-creates a TerminalPresenter, collects process.argv, and prompts the user on error.

import { Reporter } from '@cluvo/sdk'

const reporter = new Reporter({
  repo: 'myorg/cli-tool',
  app: { name: 'my-cli', version: '1.0.0' },
  // preset: 'cli' is the default
})

// Option A: Wrap entire command (recommended)
await reporter.wrapCommand(async () => {
  await runCLI()
})

// Option B: Report and prompt at a specific catch site
try {
  await runCommand()
} catch (error) {
  await reporter.reportAndPrompt(error)
}

SDK / library

Use the sdk preset when integrating into a library. It disables the presenter and sets interactive: 'never', so errors are stored locally and the parent CLI (if any) handles prompting.

import { Reporter } from '@cluvo/sdk'

const reporter = new Reporter({
  repo: 'myorg/my-lib',
  app: { name: 'my-lib', version: '2.0.0' },
  preset: 'sdk',
})

// Errors are stored; rethrow is optional
await reporter.wrap(async () => {
  await riskyOperation()
}, { rethrow: false })

TUI app

Pass a custom presenter to integrate with your TUI framework:

import { Reporter } from '@cluvo/sdk'
import type { PresenterAdapter, PromptContext, PresenterAction } from '@cluvo/core'

class MyTuiPresenter implements PresenterAdapter {
  async prompt(context: PromptContext): Promise<PresenterAction | null> {
    // Pause TUI rendering, show error prompt, resume
    return { type: 'cancel' }
  }
}

const reporter = new Reporter({
  repo: 'myorg/cli-tool',
  app: { name: 'my-cli', version: '1.0.0' },
  presenter: new MyTuiPresenter(),
})

Usage

New API

reportAndPrompt(error, context?)

Combines reportError and promptAndSubmit into a single call. The most common pattern for catch blocks:

try {
  await deploy()
} catch (error) {
  await reporter.reportAndPrompt(error)
}

wrap(fn, opts?)

Wraps an async function with try/catch. Reports errors automatically.

await reporter.wrap(async () => {
  await riskyOperation()
}, { rethrow: false }) // rethrow: true by default

wrapCommand(fn)

Like wrap, but also captures process.argv as command context:

await reporter.wrapCommand(async () => {
  await runCLI()
})

installExitHandler(opts?)

Catches unreported errors at process exit via process.on('beforeExit'). Optionally intercepts process.exit() calls.

reporter.installExitHandler({ interceptProcessExit: true, timeout: 5000 })

receiveChildReport(report)

Receives an error report forwarded from a child SDK library (used automatically by the registry):

reporter.receiveChildReport(report)

Wrap a command (recommended)

import { Reporter } from '@cluvo/sdk'

const cluvo = new Reporter({
  repo: 'acme/my-tool',
  app: { name: 'my-tool', version: '2.0.0' },
})

await cluvo.wrapCommand(async () => {
  await deploy(options)
})
// If deploy() throws, cluvo catches it, builds a report,
// and prompts the user to submit a GitHub issue

Report errors manually

try {
  await riskyOperation()
} catch (error) {
  const report = await cluvo.reportError(error, {
    command: 'deploy',
    argv: process.argv.slice(2),
  })