tissues 0.3.0

package/src/lib/attribution.js

@@ -0,0 +1,216 @@
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import fs from 'node:fs'
+
+// ---------------------------------------------------------------------------
+// Package version (read once at module load)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the package version from the nearest package.json.
+ * Falls back to '0.0.0' if unavailable.
+ *
+ * @returns {string}
+ */
+function resolvePackageVersion() {
+  try {
+    const require = createRequire(import.meta.url)
+    // Walk up from this file to find package.json
+    let dir = path.dirname(fileURLToPath(import.meta.url))
+    const { root } = path.parse(dir)
+    while (dir !== root) {
+      const pkgPath = path.join(dir, 'package.json')
+      if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+        if ((pkg.name === 'ghissue' || pkg.name === 'gitissues') && pkg.version) return pkg.version
+      }
+      dir = path.dirname(dir)
+    }
+  } catch {
+    // ignore
+  }
+  return '0.0.0'
+}
+
+const PKG_VERSION = resolvePackageVersion()
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the current UTC timestamp in ISO 8601 format.
+ *
+ * @returns {string}
+ */
+function nowISO() {
+  return new Date().toISOString()
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} AttributionOpts
+ * @property {string}  [agent]          - agent identifier (e.g. 'claude-opus-4-6')
+ * @property {string}  [session]        - session or conversation ID
+ * @property {number}  [pid]            - process ID of the creating process
+ * @property {string}  [model]          - AI model used (if any)
+ * @property {string}  [trigger]        - how the issue was created (e.g. 'cli-create')
+ * @property {string}  [fingerprint]    - content fingerprint (sha256:...)
+ * @property {string}  [idempotencyKey] - deterministic idempotency key
+ * @property {number}  [risk]           - risk score [0,1]
+ * @property {number}  [complexity]     - complexity estimate [0,1]
+ * @property {number}  [confidence]     - AI confidence score [0,1]
+ * @property {string[]} [contextTags]   - free-form tags for filtering/search
+ * @property {string}  [createdAt]      - override timestamp (defaults to now)
+ */
+
+/**
+ * Build a normalized attribution metadata object from raw options.
+ *
+ * The returned object includes all provided fields plus automatic defaults
+ * (`created_at`, `created_via`, `pid`). Undefined/null fields are omitted.
+ *
+ * @param {AttributionOpts} opts
+ * @returns {object} metadata record
+ */
+export function buildAttribution(opts = {}) {
+  const {
+    agent,
+    session,
+    pid,
+    model,
+    trigger,
+    fingerprint,
+    idempotencyKey,
+    risk,
+    complexity,
+    confidence,
+    contextTags,
+    createdAt,
+  } = opts
+
+  const meta = {}
+
+  // Identity
+  if (agent != null) meta.agent = String(agent)
+  if (session != null) meta.session = String(session)
+  if (model != null) meta.model = String(model)
+
+  // Process info
+  meta.pid = pid != null ? Number(pid) : process.pid
+  meta.trigger = trigger != null ? String(trigger) : 'cli-create'
+
+  // Deduplication handles
+  if (fingerprint != null) meta.fingerprint = String(fingerprint)
+  if (idempotencyKey != null) meta.idempotency_key = String(idempotencyKey)
+
+  // Scoring (numeric, clamped to [0,1])
+  if (risk != null) meta.risk = Math.max(0, Math.min(1, Number(risk)))
+  if (complexity != null) meta.complexity = Math.max(0, Math.min(1, Number(complexity)))
+  if (confidence != null) meta.confidence = Math.max(0, Math.min(1, Number(confidence)))
+
+  // Tags
+  if (Array.isArray(contextTags) && contextTags.length > 0) {
+    meta.context_tags = contextTags.map(String)
+  }
+
+  // Timestamps / versioning
+  meta.created_at = createdAt ?? nowISO()
+  meta.created_via = `ghissue-cli/${PKG_VERSION}`
+
+  return meta
+}
+
+/**
+ * Render attribution metadata as an HTML comment block for inclusion at the
+ * bottom of a GitHub issue body.
+ *
+ * The format is a YAML-like key: value listing inside an HTML comment, which
+ * GitHub renders as invisible text. Other tools (including gitissues itself)
+ * can parse it back via `parseAttribution`.
+ *
+ * @example
+ * <!-- gitissues-meta
+ * agent: claude-opus-4-6
+ * session: abc123
+ * pid: 12345
+ * trigger: cli-create
+ * fingerprint: sha256:deadbeef
+ * created_at: 2026-02-19T15:30:00Z
+ * created_via: gitissues-cli/0.1.0
+ * -->
+ *
+ * @param {AttributionOpts} opts
+ * @returns {string}
+ */
+export function renderAttribution(opts = {}) {
+  const meta = buildAttribution(opts)
+  const lines = ['<!-- gitissues-meta']
+
+  for (const [key, value] of Object.entries(meta)) {
+    if (Array.isArray(value)) {
+      // Render arrays as comma-separated values on a single line
+      lines.push(`${key}: ${value.join(', ')}`)
+    } else {
+      lines.push(`${key}: ${value}`)
+    }
+  }
+
+  lines.push('-->')
+  return lines.join('\n')
+}
+
+/**
+ * Parse a `<!-- gitissues-meta ... -->` attribution block from an issue body.
+ *
+ * Returns the parsed key/value pairs as a plain object, or `null` if no
+ * attribution block is present in `issueBody`.
+ *
+ * Numeric fields (`pid`, `risk`, `complexity`, `confidence`) are coerced to
+ * numbers. The `context_tags` field is split back into an array.
+ *
+ * @param {string} issueBody - raw GitHub issue body markdown
+ * @returns {object|null} parsed metadata, or null if not found
+ */
+export function parseAttribution(issueBody) {
+  if (!issueBody) return null
+
+  // Match the comment block (non-greedy, handle CRLF)
+  const match = issueBody.match(/<!--\s*gitissues-meta\s*([\s\S]*?)-->/m)
+  if (!match) return null
+
+  const block = match[1]
+  const meta = {}
+
+  for (const line of block.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+
+    const colonIdx = trimmed.indexOf(':')
+    if (colonIdx === -1) continue
+
+    const key = trimmed.slice(0, colonIdx).trim()
+    const rawValue = trimmed.slice(colonIdx + 1).trim()
+
+    if (!key) continue
+
+    // Type coercions
+    if (['pid'].includes(key)) {
+      const n = Number(rawValue)
+      meta[key] = Number.isNaN(n) ? rawValue : n
+    } else if (['risk', 'complexity', 'confidence'].includes(key)) {
+      const n = parseFloat(rawValue)
+      meta[key] = Number.isNaN(n) ? rawValue : n
+    } else if (key === 'context_tags') {
+      meta[key] = rawValue.split(',').map((t) => t.trim()).filter(Boolean)
+    } else {
+      meta[key] = rawValue
+    }
+  }
+
+  return Object.keys(meta).length > 0 ? meta : null
+}

package/src/lib/config.js

@@ -0,0 +1,16 @@
+import Conf from 'conf'
+
+// Conf handles OS-appropriate storage path + creates dir automatically
+// macOS: ~/Library/Preferences/gitissues-nodejs/config.json
+// Linux: ~/.config/gitissues-nodejs/config.json
+export const store = new Conf({ projectName: 'gitissues' })
+
+export function getConfig() {
+  return store.store
+}
+
+export function setConfig(updates) {
+  for (const [key, value] of Object.entries(updates)) {
+    store.set(key, value)
+  }
+}

package/src/lib/db.js

@@ -0,0 +1,436 @@
+/**
+ * SQLite state database for ghissue CLI.
+ *
+ * Stores fingerprints (deduplication), idempotency keys, circuit breaker
+ * state, and rate-limit event log. Uses better-sqlite3 (synchronous API).
+ *
+ * Database path: .gitissues/data/gitissues.db (relative to repo root).
+ * Created automatically on first use. Users can .gitignore the data dir
+ * for personal-only state, or commit it for shared team dedup history.
+ */
+
+import Database from 'better-sqlite3'
+import path from 'path'
+import fs from 'fs'
+
+// ---------------------------------------------------------------------------
+// Path resolution — repo-local .gitissues/data/gitissues.db
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the repo root by walking up from cwd looking for .git.
+ * @param {string} [startDir]
+ * @returns {string|null}
+ */
+function findRepoRootForDb(startDir) {
+  let dir = startDir || process.cwd()
+  const { root } = path.parse(dir)
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir
+    dir = path.dirname(dir)
+  }
+  return null
+}
+
+function getDbPath() {
+  const repoRoot = findRepoRootForDb()
+  if (repoRoot) {
+    return path.join(repoRoot, '.gitissues', 'data', 'gitissues.db')
+  }
+  // Fallback: user home config dir (outside a git repo)
+  const home = process.env.HOME || process.env.USERPROFILE || ''
+  return path.join(home, '.config', 'gitissues', 'gitissues.db')
+}
+
+const DB_PATH = getDbPath()
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS fingerprints (
+  fingerprint     TEXT PRIMARY KEY,
+  repo            TEXT NOT NULL,
+  issue_number    INTEGER NOT NULL,
+  title           TEXT NOT NULL,
+  created_by      TEXT,
+  created_at      TEXT DEFAULT (datetime('now')),
+  expires_at      TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_fp_repo ON fingerprints(repo);
+
+CREATE TABLE IF NOT EXISTS idempotency_keys (
+  key             TEXT PRIMARY KEY,
+  repo            TEXT NOT NULL,
+  issue_number    INTEGER NOT NULL,
+  created_at      TEXT DEFAULT (datetime('now')),
+  expires_at      TEXT DEFAULT (datetime('now', '+48 hours'))
+);
+
+CREATE TABLE IF NOT EXISTS circuit_breaker (
+  id              TEXT PRIMARY KEY,
+  repo            TEXT NOT NULL,
+  agent           TEXT NOT NULL DEFAULT 'human',
+  status          TEXT NOT NULL DEFAULT 'closed',
+  failure_count   INTEGER DEFAULT 0,
+  last_trip_at    TEXT,
+  cooldown_until  TEXT,
+  updated_at      TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS rate_events (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  repo            TEXT NOT NULL,
+  agent           TEXT NOT NULL DEFAULT 'human',
+  event_type      TEXT NOT NULL DEFAULT 'create',
+  created_at      TEXT DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_rate_repo_agent ON rate_events(repo, agent, created_at);
+
+CREATE TABLE IF NOT EXISTS _meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`
+
+// ---------------------------------------------------------------------------
+// Lazy singleton
+// ---------------------------------------------------------------------------
+
+/** @type {import('better-sqlite3').Database | null} */
+let _db = null
+
+/**
+ * Return the initialised Database instance, creating it on first call.
+ * Also runs periodic cleanup (fingerprints + idempotency keys) at most once
+ * per hour.
+ *
+ * @returns {import('better-sqlite3').Database}
+ */
+export function getDb() {
+  if (_db) return _db
+
+  fs.mkdirSync(path.dirname(DB_PATH), { recursive: true })
+
+  _db = new Database(DB_PATH)
+
+  // WAL mode for better concurrent read performance
+  _db.pragma('journal_mode = WAL')
+  _db.pragma('foreign_keys = ON')
+
+  // Create tables
+  _db.exec(SCHEMA_SQL)
+
+  // Lazy cleanup — run at most once per hour
+  _runPeriodicCleanup()
+
+  return _db
+}
+
+function _runPeriodicCleanup() {
+  const db = _db
+  const now = Date.now()
+  const oneHourMs = 60 * 60 * 1000
+
+  const row = db
+    .prepare("SELECT value FROM _meta WHERE key = 'last_cleanup_at'")
+    .get()
+  const lastCleanup = row ? Number(row.value) : 0
+
+  if (now - lastCleanup < oneHourMs) return
+
+  expireOldFingerprints()
+  cleanExpiredKeys()
+
+  db.prepare("INSERT OR REPLACE INTO _meta (key, value) VALUES ('last_cleanup_at', ?)").run(
+    String(now),
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Fingerprint operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a fingerprint already exists for a given repo.
+ *
+ * @param {string} repo        - e.g. 'owner/repo'
+ * @param {string} fingerprint - SHA-256 hex or similar unique string
+ * @returns {{ exists: true, issueNumber: number, title: string } | null}
+ */
+export function checkFingerprint(repo, fingerprint) {
+  const db = getDb()
+  const row = db
+    .prepare(
+      `SELECT issue_number, title
+         FROM fingerprints
+        WHERE fingerprint = ? AND repo = ?
+          AND (expires_at IS NULL OR expires_at > datetime('now'))`,
+    )
+    .get(fingerprint, repo)
+
+  if (!row) return null
+  return { exists: true, issueNumber: row.issue_number, title: row.title }
+}
+
+/**
+ * Persist a new fingerprint entry.
+ *
+ * @param {string}      repo
+ * @param {string}      fingerprint
+ * @param {number}      issueNumber
+ * @param {string}      title
+ * @param {string|null} createdBy   - agent identifier or null
+ */
+export function storeFingerprint(repo, fingerprint, issueNumber, title, createdBy = null) {
+  const db = getDb()
+  db.prepare(
+    `INSERT OR REPLACE INTO fingerprints
+       (fingerprint, repo, issue_number, title, created_by)
+     VALUES (?, ?, ?, ?, ?)`,
+  ).run(fingerprint, repo, issueNumber, title, createdBy)
+}
+
+/**
+ * Delete fingerprints whose expires_at is in the past.
+ */
+export function expireOldFingerprints() {
+  const db = getDb()
+  db.prepare(
+    `DELETE FROM fingerprints WHERE expires_at IS NOT NULL AND expires_at < datetime('now')`,
+  ).run()
+}
+
+// ---------------------------------------------------------------------------
+// Idempotency keys
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up an idempotency key.
+ *
+ * @param {string} key
+ * @returns {number | null} issueNumber if the key exists and is unexpired, else null
+ */
+export function checkIdempotencyKey(key) {
+  const db = getDb()
+  const row = db
+    .prepare(
+      `SELECT issue_number FROM idempotency_keys
+        WHERE key = ? AND expires_at > datetime('now')`,
+    )
+    .get(key)
+
+  return row ? row.issue_number : null
+}
+
+/**
+ * Store a new idempotency key (expires after 48 hours via schema default).
+ *
+ * @param {string} key
+ * @param {string} repo
+ * @param {number} issueNumber
+ */
+export function storeIdempotencyKey(key, repo, issueNumber) {
+  const db = getDb()
+  db.prepare(
+    `INSERT OR IGNORE INTO idempotency_keys (key, repo, issue_number)
+     VALUES (?, ?, ?)`,
+  ).run(key, repo, issueNumber)
+}
+
+/**
+ * Delete idempotency keys that have passed their expires_at.
+ */
+export function cleanExpiredKeys() {
+  const db = getDb()
+  db.prepare(`DELETE FROM idempotency_keys WHERE expires_at < datetime('now')`).run()
+}
+
+// ---------------------------------------------------------------------------
+// Circuit breaker
+// ---------------------------------------------------------------------------
+
+/** @typedef {{ status: 'closed'|'open'|'half-open', failureCount: number, cooldownUntil: string|null }} CircuitState */
+
+/**
+ * Get current circuit state for a repo+agent pair.
+ * Returns a default closed state if no record exists yet.
+ *
+ * @param {string} repo
+ * @param {string} [agent='human']
+ * @returns {CircuitState}
+ */
+export function getCircuitState(repo, agent = 'human') {
+  const db = getDb()
+  const id = `${repo}:${agent}`
+  const row = db.prepare(`SELECT * FROM circuit_breaker WHERE id = ?`).get(id)
+
+  if (!row) {
+    return { status: 'closed', failureCount: 0, cooldownUntil: null }
+  }
+
+  return {
+    status: row.status,
+    failureCount: row.failure_count,
+    cooldownUntil: row.cooldown_until,
+  }
+}
+
+/**
+ * Trip (open) the circuit breaker and set a cooldown window.
+ *
+ * @param {string} repo
+ * @param {string} [agent='human']
+ * @param {number} [cooldownMinutes=30]
+ */
+export function tripCircuit(repo, agent = 'human', cooldownMinutes = 30) {
+  const db = getDb()
+  const id = `${repo}:${agent}`
+  db.prepare(
+    `INSERT INTO circuit_breaker (id, repo, agent, status, failure_count, last_trip_at, cooldown_until, updated_at)
+     VALUES (?, ?, ?, 'open', 1, datetime('now'), datetime('now', ?), datetime('now'))
+     ON CONFLICT(id) DO UPDATE SET
+       status         = 'open',
+       failure_count  = failure_count + 1,
+       last_trip_at   = datetime('now'),
+       cooldown_until = datetime('now', ?),
+       updated_at     = datetime('now')`,
+  ).run(id, repo, agent, `+${cooldownMinutes} minutes`, `+${cooldownMinutes} minutes`)
+}
+
+/**
+ * Reset the circuit breaker to closed state.
+ *
+ * @param {string} repo
+ * @param {string} [agent='human']
+ */
+export function resetCircuit(repo, agent = 'human') {
+  const db = getDb()
+  const id = `${repo}:${agent}`
+  db.prepare(
+    `INSERT INTO circuit_breaker (id, repo, agent, status, failure_count, cooldown_until, updated_at)
+     VALUES (?, ?, ?, 'closed', 0, NULL, datetime('now'))
+     ON CONFLICT(id) DO UPDATE SET
+       status        = 'closed',
+       failure_count = 0,
+       cooldown_until = NULL,
+       updated_at    = datetime('now')`,
+  ).run(id, repo, agent)
+}
+
+/**
+ * Transition an open circuit to half-open if the cooldown has expired.
+ * No-op if the circuit is not open or cooldown has not elapsed.
+ *
+ * @param {string} repo
+ * @param {string} [agent='human']
+ * @returns {CircuitState} updated state
+ */
+export function probeCircuit(repo, agent = 'human') {
+  const db = getDb()
+  const id = `${repo}:${agent}`
+
+  db.prepare(
+    `UPDATE circuit_breaker
+        SET status     = 'half-open',
+            updated_at = datetime('now')
+      WHERE id          = ?
+        AND status      = 'open'
+        AND cooldown_until IS NOT NULL
+        AND cooldown_until < datetime('now')`,
+  ).run(id)
+
+  return getCircuitState(repo, agent)
+}
+
+// ---------------------------------------------------------------------------
+// Rate limiting
+// ---------------------------------------------------------------------------
+
+/**
+ * Record a new rate-limit event (e.g. issue creation).
+ *
+ * @param {string} repo
+ * @param {string} [agent='human']
+ * @param {string} [eventType='create']
+ */
+export function recordRateEvent(repo, agent = 'human', eventType = 'create') {
+  const db = getDb()
+  db.prepare(
+    `INSERT INTO rate_events (repo, agent, event_type) VALUES (?, ?, ?)`,
+  ).run(repo, agent, eventType)
+}
+
+/**
+ * Count events within a sliding window.
+ *
+ * @param {string} repo
+ * @param {string} [agent='human']
+ * @param {number} windowMinutes
+ * @returns {number}
+ */
+export function countRecentEvents(repo, agent = 'human', windowMinutes = 60) {
+  const db = getDb()
+  const row = db
+    .prepare(
+      `SELECT COUNT(*) AS cnt
+         FROM rate_events
+        WHERE repo    = ?
+          AND agent   = ?
+          AND created_at > datetime('now', ?)`,
+    )
+    .get(repo, agent, `-${windowMinutes} minutes`)
+
+  return row ? row.cnt : 0
+}
+
+/**
+ * Check whether a new event is allowed given a rate-limit config.
+ *
+ * @param {string} repo
+ * @param {string} [agent='human']
+ * @param {{ maxPerHour?: number, burstLimit?: number, burstWindowMinutes?: number }} [config]
+ * @returns {{ allowed: boolean, remaining: number, resetIn: number }}
+ *   remaining — how many more events are allowed in the current hour window
+ *   resetIn   — seconds until the oldest event in the window falls out
+ */
+export function checkRateLimit(
+  repo,
+  agent = 'human',
+  config = {},
+) {
+  const { maxPerHour = 10, burstLimit = 5, burstWindowMinutes = 5 } = config
+  const db = getDb()
+
+  const hourCount = countRecentEvents(repo, agent, 60)
+  const burstCount = countRecentEvents(repo, agent, burstWindowMinutes)
+
+  const hourBlocked = hourCount >= maxPerHour
+  const burstBlocked = burstCount >= burstLimit
+  const allowed = !hourBlocked && !burstBlocked
+
+  const remaining = Math.max(0, maxPerHour - hourCount)
+
+  // Seconds until the oldest hourly event falls out of the 60-minute window
+  let resetIn = 0
+  if (!allowed) {
+    const oldest = db
+      .prepare(
+        `SELECT created_at FROM rate_events
+          WHERE repo = ? AND agent = ?
+            AND created_at > datetime('now', '-60 minutes')
+          ORDER BY created_at ASC
+          LIMIT 1`,
+      )
+      .get(repo, agent)
+
+    if (oldest) {
+      const oldestMs = new Date(oldest.created_at + 'Z').getTime()
+      const windowEndMs = oldestMs + 60 * 60 * 1000
+      resetIn = Math.max(0, Math.ceil((windowEndMs - Date.now()) / 1000))
+    }
+  }
+
+  return { allowed, remaining, resetIn }
+}