tissues 0.3.0

package/src/lib/gh.js

@@ -0,0 +1,273 @@
+/**
+ * Thin wrapper around the `gh` CLI.
+ * All GitHub operations go through `gh` — auth, API calls, issue creation.
+ */
+
+import { execFileSync, execSync } from 'node:child_process'
+import chalk from 'chalk'
+
+// ---------------------------------------------------------------------------
+// gh availability
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if `gh` is installed and return its path. Exits with install
+ * instructions if not found.
+ */
+export function requireGh() {
+  try {
+    const path = execFileSync('which', ['gh'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    return path
+  } catch {
+    console.error(chalk.red('\n  gh CLI is required but not installed.\n'))
+    console.error('  Install it with one of:')
+    console.error(chalk.cyan('    brew install gh                  ') + chalk.dim('# macOS'))
+    console.error(chalk.cyan('    sudo apt install gh              ') + chalk.dim('# Debian/Ubuntu'))
+    console.error(chalk.cyan('    winget install GitHub.cli         ') + chalk.dim('# Windows'))
+    console.error(chalk.cyan('    conda install -c conda-forge gh  ') + chalk.dim('# conda'))
+    console.error()
+    console.error(chalk.dim('  More: https://cli.github.com'))
+    console.error()
+    process.exit(1)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the active auth token from `gh`. Returns null if not authenticated.
+ * @returns {string | null}
+ */
+export function getToken() {
+  // Env vars take priority (CI/CD)
+  const envToken = process.env.GH_TOKEN || process.env.GITHUB_TOKEN
+  if (envToken) return envToken
+
+  try {
+    return execFileSync('gh', ['auth', 'token'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Require a valid auth token. Exits with instructions if not authenticated.
+ * @returns {string}
+ */
+export function requireAuth() {
+  const token = getToken()
+  if (token) return token
+
+  console.error(chalk.red('\n  Not authenticated with GitHub.\n'))
+  console.error('  Run:')
+  console.error(chalk.cyan('    gh auth login'))
+  console.error()
+  process.exit(1)
+}
+
+/**
+ * Get auth status from `gh auth status`. Returns parsed account info.
+ * @returns {{ accounts: Array<{ login: string, active: boolean, scopes: string[], tokenType: string }> }}
+ */
+export function getAuthStatus() {
+  try {
+    const raw = execFileSync('gh', ['auth', 'status', '--json'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    return JSON.parse(raw)
+  } catch {
+    // Older gh versions may not support --json, fall back to text parsing
+    try {
+      const text = execFileSync('gh', ['auth', 'status'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      return { raw: text }
+    } catch {
+      return { accounts: [] }
+    }
+  }
+}
+
+/**
+ * Get the authenticated user's login.
+ * @returns {string | null}
+ */
+export function getAuthenticatedUser() {
+  try {
+    const raw = execFileSync('gh', ['api', 'user', '--jq', '.login'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    return raw || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Check if the current token has the required scopes for issue creation.
+ * @returns {{ ok: boolean, scopes: string[], missing: string[] }}
+ */
+export function checkScopes() {
+  try {
+    // gh api returns headers including X-OAuth-Scopes
+    const raw = execFileSync('gh', ['api', '-i', 'user'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+
+    const scopeLine = raw.split('\n').find((l) => l.toLowerCase().startsWith('x-oauth-scopes:'))
+    if (!scopeLine) {
+      // Fine-grained PATs don't have X-OAuth-Scopes header — they use permissions
+      // If the API call succeeded, the token is valid
+      return { ok: true, scopes: ['fine-grained'], missing: [] }
+    }
+
+    const scopes = scopeLine
+      .replace(/^x-oauth-scopes:\s*/i, '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+
+    const required = ['repo']
+    const missing = required.filter(
+      (r) => !scopes.includes(r) && !scopes.includes('admin:org'), // admin:org implies repo
+    )
+
+    return { ok: missing.length === 0, scopes, missing }
+  } catch {
+    return { ok: false, scopes: [], missing: ['repo'] }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auth commands (delegate to gh)
+// ---------------------------------------------------------------------------
+
+/**
+ * Run `gh auth login` interactively.
+ */
+export function authLogin() {
+  execSync('gh auth login', { stdio: 'inherit' })
+}
+
+/**
+ * Run `gh auth status` and print to stdout.
+ */
+export function authStatus() {
+  try {
+    execSync('gh auth status', { stdio: 'inherit' })
+  } catch {
+    // gh auth status exits non-zero when not logged in, output already printed
+  }
+}
+
+/**
+ * Run `gh auth switch` interactively.
+ */
+export function authSwitch() {
+  execSync('gh auth switch', { stdio: 'inherit' })
+}
+
+/**
+ * Run `gh auth logout` interactively.
+ */
+export function authLogout() {
+  execSync('gh auth logout', { stdio: 'inherit' })
+}
+
+// ---------------------------------------------------------------------------
+// GitHub API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an issue via `gh issue create`.
+ * @param {string} repo - owner/name
+ * @param {{ title: string, body: string, labels?: string[] }} opts
+ * @returns {{ number: number, url: string }}
+ */
+export function createIssue(repo, { title, body, labels }) {
+  const args = [
+    'issue', 'create',
+    '--repo', repo,
+    '--title', title,
+    '--body', body,
+  ]
+
+  if (labels?.length) {
+    args.push('--label', labels.join(','))
+  }
+
+  const output = execFileSync('gh', args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim()
+
+  // gh issue create prints the URL on success
+  const url = output.trim()
+  const numberMatch = url.match(/\/issues\/(\d+)$/)
+  const number = numberMatch ? parseInt(numberMatch[1], 10) : 0
+
+  return { number, url }
+}
+
+/**
+ * List open issues for a repo.
+ * @param {string} repo - owner/name
+ * @param {{ limit?: number }} [opts]
+ * @returns {Array<{ number: number, title: string, url: string, labels: string[], createdAt: string }>}
+ */
+export function listIssues(repo, opts = {}) {
+  const limit = opts.limit ?? 100
+  const raw = execFileSync('gh', [
+    'issue', 'list',
+    '--repo', repo,
+    '--state', 'open',
+    '--limit', String(limit),
+    '--json', 'number,title,url,labels,createdAt',
+  ], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim()
+
+  if (!raw) return []
+  const issues = JSON.parse(raw)
+  return issues.map((i) => ({
+    number: i.number,
+    title: i.title,
+    url: i.url,
+    labels: (i.labels || []).map((l) => l.name),
+    createdAt: i.createdAt,
+  }))
+}
+
+/**
+ * List repos the user has access to.
+ * @param {{ limit?: number }} [opts]
+ * @returns {string[]} - array of "owner/name"
+ */
+export function listRepos(opts = {}) {
+  const limit = opts.limit ?? 100
+  const raw = execFileSync('gh', [
+    'repo', 'list',
+    '--limit', String(limit),
+    '--json', 'nameWithOwner',
+    '--jq', '.[].nameWithOwner',
+  ], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim()
+
+  if (!raw) return []
+  return raw.split('\n').filter(Boolean)
+}

package/src/lib/repo-picker.js

@@ -0,0 +1,54 @@
+import { search } from '@inquirer/prompts'
+import { store, setConfig } from './config.js'
+import { listRepos } from './gh.js'
+import ora from 'ora'
+
+const USAGE_KEY = 'repoUsage'
+
+function getRepoUsage() {
+  return store.get(USAGE_KEY) || {}
+}
+
+function trackRepoUsage(repo) {
+  const usage = getRepoUsage()
+  usage[repo] = { count: (usage[repo]?.count || 0) + 1, lastUsed: Date.now() }
+  store.set(USAGE_KEY, usage)
+}
+
+function sortByUsage(repos, usage) {
+  return [...repos].sort((a, b) => {
+    const ua = usage[a] || { count: 0, lastUsed: 0 }
+    const ub = usage[b] || { count: 0, lastUsed: 0 }
+    if (ub.count !== ua.count) return ub.count - ua.count
+    return ub.lastUsed - ua.lastUsed
+  })
+}
+
+export async function pickRepo() {
+  const spinner = ora('Fetching repos...').start()
+  let repos
+  try {
+    repos = listRepos()
+    spinner.stop()
+  } catch (err) {
+    spinner.fail('Failed to fetch repos')
+    throw err
+  }
+
+  const usage = getRepoUsage()
+  const sorted = sortByUsage(repos, usage)
+
+  const repo = await search({
+    message: 'Select a repository',
+    source: (input) => {
+      const term = (input || '').toLowerCase()
+      return sorted
+        .filter((r) => r.toLowerCase().includes(term))
+        .map((r) => ({ name: r, value: r }))
+    },
+  })
+
+  trackRepoUsage(repo)
+  setConfig({ activeRepo: repo })
+  return repo
+}

package/src/lib/safety.js

@@ -0,0 +1,259 @@
+/**
+ * Circuit breaker and rate limiter for ghissue CLI.
+ *
+ * Prevents runaway issue creation loops by:
+ * - Rate limiting per agent (hourly + burst window)
+ * - Rate limiting globally across all agents
+ * - Circuit breaker that trips after repeated failures and enters cooldown
+ *
+ * All functions are synchronous (better-sqlite3 is sync).
+ */
+
+import {
+  getCircuitState,
+  tripCircuit,
+  resetCircuit,
+  probeCircuit,
+  recordRateEvent,
+  countRecentEvents,
+  getDb,
+} from './db.js'
+
+const DEFAULT_SAFETY_CONFIG = {
+  // Rate limits
+  maxPerHour: 10,           // max issues per hour per agent
+  burstLimit: 5,            // max issues in burst window
+  burstWindowMinutes: 5,    // burst window size
+
+  // Circuit breaker
+  tripThreshold: 3,         // trip after N blocked attempts (dedup hits count as failures)
+  cooldownMinutes: 30,      // time before half-open probe
+
+  // Global limits
+  globalMaxPerHour: 30,     // across all agents for this repo
+}
+
+/**
+ * Format a future Date as a human-readable remaining duration.
+ * e.g. "23 minutes remaining" or "1 minute remaining"
+ *
+ * @param {Date|string|number} until - The end time
+ * @returns {string}
+ */
+function formatCooldownRemaining(until) {
+  const end = new Date(until)
+  const now = new Date()
+  const diffMs = end - now
+  if (diffMs <= 0) return '0 minutes remaining'
+  const minutes = Math.ceil(diffMs / 60_000)
+  return `${minutes} ${minutes === 1 ? 'minute' : 'minutes'} remaining`
+}
+
+/**
+ * Count recent issue creation events across ALL agents for a repo.
+ * Uses getDb() directly because countRecentEvents only filters by agent.
+ *
+ * @param {string} repo - e.g. "owner/repo"
+ * @param {number} windowMinutes
+ * @returns {number}
+ */
+function countAllRecentEvents(repo, windowMinutes) {
+  const db = getDb()
+  const row = db
+    .prepare(
+      `SELECT COUNT(*) AS cnt
+       FROM rate_events
+       WHERE repo = ? AND event_type = 'create' AND created_at > datetime('now', ?)`
+    )
+    .get(repo, `-${windowMinutes} minutes`)
+  return row ? row.cnt : 0
+}
+
+/**
+ * Check if issue creation is allowed for the given repo/agent.
+ *
+ * Steps:
+ * 1. Probe the circuit (transitions open → half-open if cooldown expired).
+ * 2. If circuit is open, block immediately.
+ * 3. If circuit is half-open, allow exactly one probe through.
+ * 4. Check per-agent hourly rate limit.
+ * 5. Check per-agent burst rate limit.
+ * 6. Check global (all-agent) hourly rate limit.
+ *
+ * @param {string} repo   - e.g. "owner/repo"
+ * @param {string} agent  - identifier for the calling agent/user
+ * @param {object} [config] - overrides for DEFAULT_SAFETY_CONFIG
+ * @returns {{ allowed: boolean, reason?: string, circuitState: string, rateInfo: object }}
+ */
+export function checkSafety(repo, agent, config = {}) {
+  const cfg = { ...DEFAULT_SAFETY_CONFIG, ...config }
+
+  // Step 1: probe — may transition open → half-open if cooldown expired
+  probeCircuit(repo, agent)
+
+  // Step 2: read current circuit state
+  const circuit = getCircuitState(repo, agent)
+  const circuitState = circuit.status ?? 'closed'
+
+  if (circuitState === 'open') {
+    const remaining = circuit.cooldownUntil
+      ? formatCooldownRemaining(circuit.cooldownUntil)
+      : 'unknown'
+    return {
+      allowed: false,
+      reason: `Circuit breaker is open. Cooldown until: ${circuit.cooldownUntil} (${remaining})`,
+      circuitState,
+      rateInfo: {},
+    }
+  }
+
+  // Step 3: half-open → log and allow the probe through (no rate checks)
+  if (circuitState === 'half-open') {
+    console.warn(`[safety] Circuit is half-open for ${repo}/${agent} — allowing probe request through.`)
+    return {
+      allowed: true,
+      circuitState,
+      rateInfo: { probe: true },
+    }
+  }
+
+  // Step 4: per-agent hourly limit
+  const agentHourCount = countRecentEvents(repo, agent, 60)
+  if (agentHourCount >= cfg.maxPerHour) {
+    return {
+      allowed: false,
+      reason: `Hourly rate limit reached: ${agentHourCount}/${cfg.maxPerHour} issues created in the last 60 minutes.`,
+      circuitState,
+      rateInfo: { agentHourCount, maxPerHour: cfg.maxPerHour },
+    }
+  }
+
+  // Step 5: per-agent burst limit
+  const agentBurstCount = countRecentEvents(repo, agent, cfg.burstWindowMinutes)
+  if (agentBurstCount >= cfg.burstLimit) {
+    return {
+      allowed: false,
+      reason: `Burst rate limit reached: ${agentBurstCount}/${cfg.burstLimit} issues created in the last ${cfg.burstWindowMinutes} minutes.`,
+      circuitState,
+      rateInfo: { agentBurstCount, burstLimit: cfg.burstLimit, burstWindowMinutes: cfg.burstWindowMinutes },
+    }
+  }
+
+  // Step 6: global (all-agent) hourly limit
+  const globalHourCount = countAllRecentEvents(repo, 60)
+  if (globalHourCount >= cfg.globalMaxPerHour) {
+    return {
+      allowed: false,
+      reason: `Global hourly rate limit reached: ${globalHourCount}/${cfg.globalMaxPerHour} issues created across all agents in the last 60 minutes.`,
+      circuitState,
+      rateInfo: { globalHourCount, globalMaxPerHour: cfg.globalMaxPerHour },
+    }
+  }
+
+  return {
+    allowed: true,
+    circuitState,
+    rateInfo: {
+      agentHourCount,
+      agentBurstCount,
+      globalHourCount,
+      maxPerHour: cfg.maxPerHour,
+      burstLimit: cfg.burstLimit,
+      globalMaxPerHour: cfg.globalMaxPerHour,
+    },
+  }
+}
+
+/**
+ * Record a successful issue creation.
+ *
+ * - Appends a 'create' rate event so future rate checks account for this issue.
+ * - If the circuit was half-open (probe succeeded), resets it to closed.
+ *
+ * @param {string} repo
+ * @param {string} agent
+ */
+export function recordSuccess(repo, agent) {
+  recordRateEvent(repo, agent, 'create')
+
+  const circuit = getCircuitState(repo, agent)
+  if ((circuit.status ?? 'closed') === 'half-open') {
+    resetCircuit(repo, agent)
+    console.info(`[safety] Half-open probe succeeded — circuit reset to closed for ${repo}/${agent}.`)
+  }
+}
+
+/**
+ * Record a safety failure (e.g., dedup block, validation error).
+ *
+ * Increments the failure count toward the trip threshold. Once
+ * tripThreshold is reached the circuit opens and enters cooldown.
+ *
+ * @param {string} repo
+ * @param {string} agent
+ * @param {object} [config] - overrides for DEFAULT_SAFETY_CONFIG
+ */
+export function recordFailure(repo, agent, config = {}) {
+  const cfg = { ...DEFAULT_SAFETY_CONFIG, ...config }
+
+  const circuit = getCircuitState(repo, agent)
+  const newFailureCount = (circuit.failureCount ?? 0) + 1
+
+  if (newFailureCount >= cfg.tripThreshold) {
+    tripCircuit(repo, agent, cfg.cooldownMinutes)
+    console.warn(
+      `[safety] Circuit tripped for ${repo}/${agent} after ${newFailureCount} failures. ` +
+      `Cooldown: ${cfg.cooldownMinutes} minutes.`
+    )
+  } else {
+    // Update failure count without tripping — db.tripCircuit handles the trip;
+    // for intermediate increments we record a 'failure' rate event so the count
+    // is persisted across calls.
+    recordRateEvent(repo, agent, 'failure')
+  }
+}
+
+/**
+ * Get a human-readable safety status summary for a repo/agent pair.
+ *
+ * @param {string} repo
+ * @param {string} agent
+ * @param {object} [config] - overrides for DEFAULT_SAFETY_CONFIG
+ * @returns {string}
+ */
+export function getSafetyStatus(repo, agent, config = {}) {
+  const cfg = { ...DEFAULT_SAFETY_CONFIG, ...config }
+
+  probeCircuit(repo, agent)
+  const circuit = getCircuitState(repo, agent)
+  const circuitState = circuit.status ?? 'closed'
+
+  const agentHourCount = countRecentEvents(repo, agent, 60)
+  const agentBurstCount = countRecentEvents(repo, agent, cfg.burstWindowMinutes)
+  const globalHourCount = countAllRecentEvents(repo, 60)
+
+  const lines = [
+    `Safety status for ${repo} / agent: ${agent}`,
+    `  Circuit breaker : ${circuitState.toUpperCase()}` +
+      (circuitState === 'open' && circuit.cooldownUntil
+        ? ` (${formatCooldownRemaining(circuit.cooldownUntil)})`
+        : ''),
+    `  Failures        : ${circuit.failureCount ?? 0} / ${cfg.tripThreshold} (trip threshold)`,
+    `  Hourly (agent)  : ${agentHourCount} / ${cfg.maxPerHour}`,
+    `  Burst (agent)   : ${agentBurstCount} / ${cfg.burstLimit} (last ${cfg.burstWindowMinutes} min)`,
+    `  Hourly (global) : ${globalHourCount} / ${cfg.globalMaxPerHour}`,
+  ]
+
+  return lines.join('\n')
+}
+
+/**
+ * Force-reset the circuit breaker to closed state (admin override).
+ *
+ * @param {string} repo
+ * @param {string} agent
+ */
+export function forceReset(repo, agent) {
+  resetCircuit(repo, agent)
+  console.info(`[safety] Circuit breaker force-reset to closed for ${repo}/${agent}.`)
+}