tissues 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caleb Ogden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,353 @@
+# ghissue
+
+AI-enhanced GitHub issue creation with built-in safety guardrails.
+
+Create structured, deduplicated GitHub issues from the command line — with circuit breakers and rate limiting to prevent runaway issue creation when used inside AI agent workflows.
+
+[![npm version](https://img.shields.io/npm/v/ghissue)](https://www.npmjs.com/package/ghissue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Install
+
+```bash
+npm install -g ghissue
+```
+
+Requires Node.js >= 18.
+
+---
+
+## Quick Start
+
+```bash
+# Authenticate (auto-detects gh CLI token)
+ghissue auth
+
+# Set your active repo
+ghissue open
+
+# Create an issue interactively
+ghissue create
+
+# Check safety status before running in CI
+ghissue status
+```
+
+---
+
+## Commands
+
+### `ghissue auth`
+
+Authenticate with GitHub. Auto-detects your `gh` CLI token if you're already logged in via `gh`. Falls back to GitHub OAuth Device Flow if not.
+
+```bash
+ghissue auth
+```
+
+### `ghissue open`
+
+Set the active repository context. All subsequent commands use this repo unless overridden with `--repo`.
+
+```bash
+ghissue open
+# prompts: pick a repo from your GitHub account
+```
+
+### `ghissue create`
+
+Create a new GitHub issue. Runs dedup checks and safety gates before creating anything.
+
+```bash
+ghissue create [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--repo <owner/name>` | Override active repo |
+| `--template <name>` | Template to use: `bug`, `feature`, `security`, `performance`, `refactor` |
+| `--title <title>` | Issue title (skips interactive prompt) |
+| `--body <text>` | Issue body / description (skips interactive prompt) |
+| `--labels <labels>` | Comma-separated labels to apply |
+| `--agent <name>` | Agent identifier for attribution (default: `human`) |
+| `--session <id>` | Session ID for attribution and idempotency |
+| `--force` | Skip dedup warnings (still blocks on exact matches) |
+| `--dry-run` | Check dedup and safety without creating the issue |
+
+**Examples:**
+
+```bash
+# Interactive
+ghissue create
+
+# Fully scripted (no prompts)
+ghissue create \
+  --repo owner/my-repo \
+  --template bug \
+  --title "Login fails on Safari 17" \
+  --body "Reproducible on fresh profile. Console shows CORS error." \
+  --labels "bug,P1"
+
+# From an AI agent
+ghissue create \
+  --agent claude-opus-4-6 \
+  --session abc123 \
+  --template feature \
+  --title "Add dark mode toggle" \
+  --dry-run
+```
+
+### `ghissue list`
+
+Browse open issues for the active repo.
+
+```bash
+ghissue list
+ghissue list --repo owner/other-repo
+```
+
+### `ghissue status`
+
+Show circuit breaker state and rate limit usage for the active repo.
+
+```bash
+ghissue status
+ghissue status --agent claude-opus-4-6
+ghissue status --reset   # force-reset circuit breaker to closed
+```
+
+Output:
+
+```
+Circuit Breaker: closed ✓
+Rate Limit: 3/10 per hour (7 remaining)
+Burst: 1/5 in last 5 min
+Global: 3/30 per hour (27 remaining)
+
+Last issue created: 12 minutes ago
+Fingerprints stored: 47
+```
+
+---
+
+## Safety Features
+
+ghissue is designed to be called from AI agent loops. The safety infrastructure prevents one misconfigured agent from flooding a repo with issues.
+
+### Circuit Breaker
+
+Three-state machine (closed / half-open / open) per repo+agent pair.
+
+- **Closed** — normal operation
+- **Open** — creation blocked; cooldown in effect (default: 30 minutes)
+- **Half-open** — one probe request allowed through to test recovery
+
+The circuit trips after 3 blocked attempts (dedup blocks count as failures). If the probe succeeds, the circuit resets to closed automatically.
+
+To inspect or reset:
+
+```bash
+ghissue status
+ghissue status --reset
+```
+
+### Rate Limiting
+
+Three independent rate limits, all checked before creating:
+
+| Limit | Default | Scope |
+|---|---|---|
+| Per-agent hourly | 10 issues/hour | per repo + agent |
+| Per-agent burst | 5 issues / 5 minutes | per repo + agent |
+| Global hourly | 30 issues/hour | per repo, all agents combined |
+
+All limits are configurable in `.gitissues/config.json`.
+
+### Deduplication (3 layers)
+
+Dedup runs cheapest-first before every `create`:
+
+1. **Idempotency key** (O(1) DB lookup) — blocks if the same `agent + trigger + issueType + repo` combination has already created an issue this session.
+2. **Content fingerprint** (O(1) DB lookup) — SHA-256 of normalized title + first 500 chars of body. Blocks exact re-submissions even across sessions.
+3. **Fuzzy title match** (O(n) GitHub API) — Levenshtein similarity against all open issues. Blocks at >95% similarity; warns at >80%.
+
+A `block` always prevents creation. A `warn` prompts interactively (or is skipped with `--force`).
+
+### Attribution Tracking
+
+Every issue created by ghissue includes a machine-readable `<!-- gitissues-meta -->` block. See [Attribution](#attribution) below.
+
+---
+
+## Configuration
+
+Configuration is loaded and merged from four sources in ascending priority order:
+
+1. Built-in defaults
+2. User-level config: `~/.config/gitissues/config.json`
+3. Repo-level config: `.gitissues/config.json`
+4. Environment variables: `GITISSUES_*`
+
+### Example `.gitissues/config.json`
+
+```json
+{
+  "safety": {
+    "maxPerHour": 5,
+    "burstLimit": 3,
+    "burstWindowMinutes": 5,
+    "tripThreshold": 3,
+    "cooldownMinutes": 30,
+    "globalMaxPerHour": 20
+  },
+  "dedup": {
+    "blockAbove": 0.95,
+    "warnAbove": 0.80,
+    "fingerprintTTLDays": 90
+  },
+  "attribution": {
+    "required": false,
+    "defaultAgent": "human"
+  },
+  "templates": {
+    "dir": ".gitissues/templates",
+    "default": "bug"
+  },
+  "hooks": {
+    "postCreate": "scripts/notify-slack.sh"
+  }
+}
+```
+
+### Environment Variables
+
+Environment variables follow the pattern `GITISSUES_<SECTION>_<KEY>`:
+
+```bash
+GITISSUES_SAFETY_MAX_PER_HOUR=5
+GITISSUES_SAFETY_BURST_LIMIT=3
+GITISSUES_SAFETY_GLOBAL_MAX_PER_HOUR=20
+GITISSUES_ATTRIBUTION_DEFAULT_AGENT=my-agent
+```
+
+### Hooks
+
+`postCreate` runs a shell command after every successful issue creation. Three environment variables are injected:
+
+```bash
+GITISSUES_REPO          # owner/repo
+GITISSUES_ISSUE_NUMBER  # 142
+GITISSUES_ISSUE_URL     # https://github.com/owner/repo/issues/142
+```
+
+---
+
+## Templates
+
+### Built-in Templates
+
+| Key | Description |
+|---|---|
+| `default` | Generic summary + details + additional context |
+| `bug` | Steps to reproduce, expected vs actual behavior, environment |
+| `feature` | Motivation, proposed solution, alternatives |
+| `security` | Severity, affected components, suggested fix |
+| `performance` | Current metric, target metric, affected area |
+| `refactor` | Motivation, scope, risk assessment |
+
+### Custom Templates
+
+Place `.md` files in `.gitissues/templates/` (repo-level) or `~/.config/gitissues/templates/` (user-level). Repo templates take priority over user templates, which take priority over built-ins.
+
+Template files support `{{variable}}` substitution:
+
+| Variable | Value |
+|---|---|
+| `{{title}}` | Issue title |
+| `{{description}}` | User's description |
+| `{{agent}}` | Agent identifier |
+| `{{session}}` | Session ID |
+| `{{date}}` | ISO date (YYYY-MM-DD) |
+| `{{repo}}` | Repository (owner/name) |
+
+**Example** `.gitissues/templates/incident.md`:
+
+```markdown
+name: Incident Report
+
+## Incident: {{title}}
+
+**Date:** {{date}}
+**Reported by:** {{agent}}
+
+## What happened
+
+{{description}}
+
+## Impact
+
+## Timeline
+
+## Resolution
+
+## Prevention
+```
+
+Use it with `--template incident`.
+
+---
+
+## Attribution
+
+Every issue created by ghissue includes a machine-readable HTML comment at the bottom of the body. GitHub renders it as invisible text; it does not appear in the rendered issue.
+
+```html
+<!-- gitissues-meta
+agent: claude-opus-4-6
+session: abc123
+pid: 84921
+trigger: cli-create
+fingerprint: sha256:3f2a1b...
+created_at: 2026-02-19T15:30:00.000Z
+created_via: ghissue-cli/0.3.0
+-->
+```
+
+The block is used by ghissue to:
+
+- Power content fingerprint dedup (prevents re-creating identical issues)
+- Track which agent created which issue
+- Enable idempotency for agent workflows
+
+You can pass additional fields via `--agent`, `--session`, and the programmatic API.
+
+---
+
+## State Database
+
+ghissue stores local state in a SQLite database at:
+
+```
+.gitissues/data/gitissues.db
+```
+
+**No separate SQLite install.** The CLI uses [better-sqlite3](https://github.com/WiseLibs/better-sqlite3), which compiles SQLite into the Node addon at `npm install` time. Users do not need to install SQLite on their system. SQLite is a common choice for CLI tool state when you need queryable, structured data (rate limits, dedup history, circuit breaker); simpler config lives in JSON (e.g. `conf` store).
+
+**What it stores:**
+
+- `fingerprints` — SHA-256 hashes of previously created issues (for dedup layer 2)
+- `rate_events` — timestamped creation events (for rate limiting)
+- `circuit_breaker` — circuit state per repo+agent (status, failure count, cooldown)
+- `idempotency_keys` — deterministic keys for agent-driven idempotency
+
+The database file can be committed to share dedup history across a team, or added to `.gitignore` to keep it local. It is created automatically on first use.
+
+---
+
+## License
+
+MIT

package/bin/gitissues.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { program } from '../src/cli.js'
+
+try {
+  await program.parseAsync()
+} catch (err) {
+  if (err.name === 'ExitPromptError') {
+    process.exit(0)
+  }
+  throw err
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "tissues",
+  "version": "0.3.0",
+  "description": "AI-enhanced GitHub issue creation with built-in safety guardrails. Wraps gh CLI with circuit breakers, rate limiting, dedup, and templates.",
+  "type": "module",
+  "bin": {
+    "tissues": "./bin/gitissues.js"
+  },
+  "scripts": {
+    "dev": "node bin/gitissues.js",
+    "watch": "node --watch bin/gitissues.js --help",
+    "test": "node --test src/**/*.test.js",
+    "audit": "node scripts/audit.js",
+    "build": "node scripts/build.js",
+    "prepublishOnly": "node scripts/audit.js",
+    "dev:install": "node scripts/dev-install.js",
+    "dev:uninstall": "node scripts/dev-install.js --uninstall"
+  },
+  "keywords": [
+    "git",
+    "github",
+    "issues",
+    "ai",
+    "cli",
+    "safety",
+    "dedup",
+    "circuit-breaker"
+  ],
+  "author": "Caleb Ogden",
+  "license": "MIT",
+  "homepage": "https://ghissue.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/calebogden/ghissue.git"
+  },
+  "bugs": {
+    "url": "https://github.com/calebogden/ghissue/issues"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "better-sqlite3": "^11.0.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "conf": "^13.0.0",
+    "ora": "^8.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,64 @@
+import { Command } from 'commander'
+import { authCommand } from './commands/auth.js'
+import { openCommand } from './commands/open.js'
+import { createCommand } from './commands/create.js'
+import { listCommand } from './commands/list.js'
+import { statusCommand } from './commands/status.js'
+import { store } from './lib/config.js'
+import { requireGh, getAuthStatus } from './lib/gh.js'
+import chalk from 'chalk'
+
+export const program = new Command()
+
+function authDescription() {
+  const base = 'Authenticate with GitHub (via gh CLI)'
+  try {
+    const status = getAuthStatus()
+    const active = status.accounts?.find(a => a.active)
+    if (!active) return base
+    const check = chalk.green('✔')
+    return `${base} ${check} ${chalk.dim(active.login)}`
+  } catch {
+    return base
+  }
+}
+
+program
+  .name('tissues')
+  .description('AI-enhanced GitHub issue creation from the command line.')
+  .version('0.3.0')
+  .hook('preAction', (_thisCommand, actionCommand) => {
+    const name = actionCommand.name()
+
+    // completion doesn't need gh installed
+    if (name === 'completion') return
+
+    // Ensure gh is installed before any command
+    requireGh()
+
+    // Show active repo context on every command (except auth/open)
+    if (name !== 'auth' && name !== 'open' && name !== 'login' && name !== 'status' && name !== 'switch' && name !== 'logout') {
+      const activeRepo = store.get('activeRepo')
+      if (activeRepo) {
+        console.log(chalk.dim(`Working in: ${activeRepo}\n`))
+      }
+    }
+  })
+
+program.addHelpText(
+  'after',
+  `
+
+Repo: https://github.com/calebogden/ghissue
+`,
+)
+
+program.hook('preAction', () => {
+  // Lazily resolve auth description only when a command actually runs
+  authCommand.description(authDescription())
+})
+program.addCommand(authCommand)
+program.addCommand(openCommand)
+program.addCommand(createCommand)
+program.addCommand(listCommand)
+program.addCommand(statusCommand)

package/src/commands/auth.js

@@ -0,0 +1,62 @@
+import { Command } from 'commander'
+import {
+  requireGh,
+  checkScopes,
+  authLogin,
+  authStatus,
+  authSwitch,
+  authLogout,
+} from '../lib/gh.js'
+import chalk from 'chalk'
+
+export const authCommand = new Command('auth')
+  .description('Authenticate with GitHub (via gh CLI)')
+  .action(function () {
+    this.help()
+  })
+
+// Subcommands
+authCommand.addCommand(
+  new Command('login')
+    .description('Log in to GitHub (opens browser)')
+    .action(() => {
+      requireGh()
+      authLogin()
+    }),
+)
+
+authCommand.addCommand(
+  new Command('status')
+    .description('Show auth status, accounts, and scopes')
+    .action(() => {
+      requireGh()
+      authStatus()
+
+      const { ok, missing } = checkScopes()
+      if (!ok) {
+        console.log()
+        console.log(chalk.yellow('⚠ Missing required scope: ') + chalk.bold(missing.join(', ')))
+        console.log(chalk.dim('  Fix with: ') + chalk.cyan(`gh auth refresh -s ${missing.join(',')}`))
+      } else {
+        console.log(chalk.green('\n✓ Token has required scopes for issue creation'))
+      }
+    }),
+)
+
+authCommand.addCommand(
+  new Command('switch')
+    .description('Switch active GitHub account')
+    .action(() => {
+      requireGh()
+      authSwitch()
+    }),
+)
+
+authCommand.addCommand(
+  new Command('logout')
+    .description('Log out of GitHub')
+    .action(() => {
+      requireGh()
+      authLogout()
+    }),
+)