claude-gh-ticket-gen 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brett Buskirk
+
+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,406 @@
+# Claude Ticket Generator
+
+AI-powered CLI tool to parse roadmap documents and automatically generate GitHub issues using Claude AI.
+
+## Overview
+
+Claude Ticket Generator is a standalone npm package that uses Claude AI to intelligently parse any planning document, roadmap, or specification and automatically create structured GitHub issues. It understands various document formats and extracts tasks with their priorities, types, labels, and metadata.
+
+## Features
+
+- **AI-Powered Parsing**: Uses Claude AI to understand document structure and extract tasks
+- **Flexible Format Support**: Works with markdown checklists, bullet points, numbered lists, and plain text
+- **Smart Categorization**: Automatically detects priorities, task types, and labels
+- **Duplicate Detection**: Checks for existing issues to prevent duplicates
+- **Dry Run Mode**: Preview issues before creating them
+- **Label Management**: Automatically creates and manages GitHub labels
+- **Filtering**: Filter by phase, priority, and optional items
+- **Interactive Setup**: Easy configuration wizard
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- [GitHub CLI](https://cli.github.com/) installed and authenticated
+- Anthropic API key (get one at [anthropic.com](https://www.anthropic.com))
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g claude-ticket-gen
+```
+
+### Local Installation
+
+```bash
+npm install claude-ticket-gen
+npx claude-ticket-gen --help
+```
+
+### From Source
+
+```bash
+git clone https://github.com/brett-buskirk/claude-ticket-gen.git
+cd claude-ticket-gen
+npm install
+npm run build
+npm link
+```
+
+## Quick Start
+
+1. **Initialize configuration**
+
+```bash
+claude-ticket-gen init
+```
+
+This will guide you through setting up your API key and preferences.
+
+2. **Create a roadmap document**
+
+Create a `ROADMAP.md` file in your project (see [example](examples/ROADMAP.example.md)).
+
+3. **Preview issues (dry run)**
+
+```bash
+claude-ticket-gen generate --dry-run
+```
+
+4. **Generate issues**
+
+```bash
+claude-ticket-gen generate
+```
+
+## Usage
+
+### Commands
+
+#### `generate`
+
+Parse a document and generate GitHub issues.
+
+```bash
+claude-ticket-gen generate [file] [options]
+```
+
+**Arguments:**
+- `file` - Path to roadmap/planning document (default: ROADMAP.md)
+
+**Options:**
+- `--repo <owner/repo>` - Target GitHub repository (default: current repo)
+- `--dry-run` - Preview without creating issues
+- `--filter-phase <name>` - Filter by phase/section
+- `--min-priority <level>` - Minimum priority level (P0-P3)
+- `--include-optional` - Include optional items
+- `--config <path>` - Use specific config file
+
+**Examples:**
+
+```bash
+# Generate from default ROADMAP.md
+claude-ticket-gen generate
+
+# Preview without creating
+claude-ticket-gen generate --dry-run
+
+# Use specific file
+claude-ticket-gen generate docs/PLANNING.md
+
+# Generate for different repo
+claude-ticket-gen generate --repo owner/other-repo
+
+# Filter by priority (P0 and P1 only)
+claude-ticket-gen generate --min-priority P1
+
+# Filter by phase
+claude-ticket-gen generate --filter-phase "Phase 1"
+
+# Include optional tasks
+claude-ticket-gen generate --include-optional
+```
+
+#### `config`
+
+Manage configuration settings.
+
+```bash
+# List all configuration
+claude-ticket-gen config list
+
+# Get specific value
+claude-ticket-gen config get anthropicApiKey
+
+# Set value
+claude-ticket-gen config set anthropicApiKey sk-ant-...
+claude-ticket-gen config set defaultRepo owner/repo
+
+# Reset to defaults
+claude-ticket-gen config reset
+```
+
+#### `init`
+
+Interactive setup wizard.
+
+```bash
+claude-ticket-gen init
+```
+
+## Configuration
+
+Configuration is stored in `~/.config/claude-ticket-gen/config.json`.
+
+### Configuration Options
+
+```json
+{
+  "anthropicApiKey": "sk-ant-...",
+  "defaultRepo": "owner/repo",
+  "defaultDocPath": "ROADMAP.md",
+  "preferences": {
+    "dryRunByDefault": false,
+    "autoCreateLabels": true,
+    "checkDuplicates": true,
+    "duplicateThreshold": 0.8
+  },
+  "labelColors": {
+    "priority-critical": "B60205",
+    "priority-high": "D93F0B",
+    "priority-medium": "FBCA04",
+    "priority-low": "0E8A16",
+    "type-feature": "0075CA",
+    "type-bug": "D73A4A",
+    "type-tech-debt": "F9D0C4",
+    "type-documentation": "0E8A16",
+    "optional": "E4E669"
+  }
+}
+```
+
+## Document Format
+
+The tool is flexible and can parse various formats. Here's what it looks for:
+
+### Task Formats
+
+```markdown
+- [ ] Task title (P1)
+- [x] Completed task
+☐ Checkbox task
+✓ Completed checkbox
+1. Numbered task
+* Bullet point task
+We need to implement feature X (plain text)
+```
+
+### Priority Indicators
+
+```markdown
+- [ ] Critical task (P0)
+- [ ] High priority task (P1)
+- [ ] Medium priority task (P2)
+- [ ] Low priority task (P3)
+- [ ] Urgent: fix this bug (keywords: urgent, critical)
+- [ ] Nice to have feature (keywords: optional, nice-to-have)
+```
+
+### Task Types
+
+The tool automatically detects task types based on context:
+- `feature` - New functionality (default)
+- `bug` - Bug fixes (keywords: bug, fix, issue)
+- `tech-debt` - Technical debt (keywords: refactor, cleanup, tech-debt)
+- `documentation` - Documentation tasks (keywords: docs, documentation)
+
+### Example Document
+
+```markdown
+# Project Roadmap
+
+## Phase 1: Foundation
+
+### Authentication (Critical)
+- [ ] Implement JWT authentication (P0)
+- [ ] Add OAuth2 support (P1)
+- [ ] Create user registration flow (P1)
+
+### Database
+- [ ] Design schema (P0)
+- [ ] Set up migrations (P1)
+
+## Phase 2: Features
+
+### User Dashboard
+- [ ] Create dashboard UI (P1)
+- [ ] Add analytics widgets (P2, optional)
+
+## Bug Fixes
+- [ ] Fix login redirect (P0, bug)
+- [ ] Resolve memory leak (P1, bug)
+```
+
+See [examples/ROADMAP.example.md](examples/ROADMAP.example.md) for a complete example.
+
+## GitHub Labels
+
+The tool automatically creates and applies these labels:
+
+**Priority Labels:**
+- `priority-critical` (P0) - Red
+- `priority-high` (P1) - Orange
+- `priority-medium` (P2) - Yellow
+- `priority-low` (P3) - Green
+
+**Type Labels:**
+- `type-feature` - Blue
+- `type-bug` - Red
+- `type-tech-debt` - Pink
+- `type-documentation` - Green
+
+**Other Labels:**
+- `optional` - Yellow
+
+You can customize label colors in the configuration.
+
+## How It Works
+
+1. **Document Parsing**: Sends your document to Claude AI with instructions to extract structured task data
+2. **Task Extraction**: Claude identifies tasks regardless of format and extracts metadata
+3. **Filtering**: Applies your filter criteria (priority, phase, optional)
+4. **Duplicate Detection**: Searches existing issues to prevent duplicates
+5. **Label Creation**: Ensures required labels exist in the repository
+6. **Issue Creation**: Creates GitHub issues via the `gh` CLI
+
+## Duplicate Detection
+
+The tool uses keyword-based similarity to detect duplicates:
+- Searches existing open issues for similar titles
+- Calculates similarity score (Jaccard similarity)
+- Skips creation if similarity exceeds threshold (default: 80%)
+- Configurable via `preferences.duplicateThreshold`
+
+## Troubleshooting
+
+### API Key Issues
+
+```bash
+# Verify API key is set
+claude-ticket-gen config get anthropicApiKey
+
+# Set or update API key
+claude-ticket-gen config set anthropicApiKey sk-ant-...
+```
+
+### GitHub CLI Issues
+
+```bash
+# Check gh is installed
+gh --version
+
+# Check authentication
+gh auth status
+
+# Re-authenticate if needed
+gh auth login
+```
+
+### Repository Detection
+
+```bash
+# Check current repo
+gh repo view
+
+# Specify repo explicitly
+claude-ticket-gen generate --repo owner/repo
+
+# Set default repo
+claude-ticket-gen config set defaultRepo owner/repo
+```
+
+### No Tasks Found
+
+- Verify your document contains actionable items
+- Check that tasks aren't all marked as completed
+- Try with `--include-optional` if tasks are marked optional
+- Use `--dry-run` to see what would be created
+
+## Examples
+
+### Basic Workflow
+
+```bash
+# 1. Setup
+claude-ticket-gen init
+
+# 2. Create ROADMAP.md with your tasks
+
+# 3. Preview
+claude-ticket-gen generate --dry-run
+
+# 4. Generate issues
+claude-ticket-gen generate
+```
+
+### Advanced Usage
+
+```bash
+# Generate from custom file for specific repo
+claude-ticket-gen generate docs/sprint-plan.md --repo owner/repo
+
+# Only create high-priority issues
+claude-ticket-gen generate --min-priority P1
+
+# Generate for specific phase
+claude-ticket-gen generate --filter-phase "Phase 1: Foundation"
+
+# Preview including optional tasks
+claude-ticket-gen generate --dry-run --include-optional
+```
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/brett-buskirk/claude-ticket-gen.git
+cd claude-ticket-gen
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally
+npm run dev -- generate --dry-run
+
+# Link globally for testing
+npm link
+```
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+MIT
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/brett-buskirk/claude-ticket-gen/issues)
+- Documentation: [README.md](README.md)
+
+## Acknowledgments
+
+- Built with [Claude AI](https://www.anthropic.com/claude)
+- Uses [GitHub CLI](https://cli.github.com/)
+- Powered by [@anthropic-ai/sdk](https://www.npmjs.com/package/@anthropic-ai/sdk)

package/bin/claude-ticket-gen.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import('../dist/cli/index.js').catch((err) => {
+  console.error('Failed to load CLI:', err.message);
+  process.exit(1);
+});

package/dist/cli/commands/config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Config command implementation
+ */
+/**
+ * Config command handler
+ */
+export declare function configCommand(action?: string, key?: string, value?: string): Promise<void>;
+//# sourceMappingURL=config.d.ts.map

package/dist/cli/commands/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH;;GAEG;AACH,wBAAsB,aAAa,CACjC,MAAM,CAAC,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAiFf"}

package/dist/cli/commands/config.js

@@ -0,0 +1,84 @@
+/**
+ * Config command implementation
+ */
+import { getConfigValue, setConfigValue, getAllConfig, resetConfig, getConfigPath, } from '../../core/config-manager.js';
+import { logger } from '../../utils/logger.js';
+import { displayConfig } from '../ui.js';
+/**
+ * Config command handler
+ */
+export async function configCommand(action, key, value) {
+    try {
+        if (!action || action === 'list') {
+            // List all config
+            const config = getAllConfig();
+            console.log();
+            logger.header('Configuration');
+            displayConfig(config);
+            console.log();
+            logger.dim(`Config file: ${getConfigPath()}`);
+            console.log();
+            return;
+        }
+        if (action === 'get') {
+            // Get specific value
+            if (!key) {
+                logger.error('Key is required for get action');
+                console.log('Usage: claude-ticket-gen config get <key>');
+                process.exit(1);
+            }
+            const val = getConfigValue(key);
+            if (val === undefined) {
+                logger.warning(`Key "${key}" not found`);
+                process.exit(1);
+            }
+            // Mask API key
+            if (key.includes('apiKey') && typeof val === 'string') {
+                const masked = val.substring(0, 12) + '...' + val.substring(val.length - 4);
+                console.log(masked);
+            }
+            else {
+                console.log(JSON.stringify(val, null, 2));
+            }
+            return;
+        }
+        if (action === 'set') {
+            // Set value
+            if (!key) {
+                logger.error('Key is required for set action');
+                console.log('Usage: claude-ticket-gen config set <key> <value>');
+                process.exit(1);
+            }
+            if (value === undefined) {
+                logger.error('Value is required for set action');
+                console.log('Usage: claude-ticket-gen config set <key> <value>');
+                process.exit(1);
+            }
+            try {
+                setConfigValue(key, value);
+                logger.success(`Set ${key} = ${key.includes('apiKey') ? '****' : value}`);
+            }
+            catch (error) {
+                logger.error(error.message);
+                process.exit(1);
+            }
+            return;
+        }
+        if (action === 'reset') {
+            // Reset to defaults
+            resetConfig();
+            logger.success('Configuration reset to defaults');
+            logger.warning('You will need to set your API key again');
+            return;
+        }
+        // Unknown action
+        logger.error(`Unknown action: ${action}`);
+        console.log('Available actions: get, set, list, reset');
+        process.exit(1);
+    }
+    catch (error) {
+        logger.error(`Config command failed: ${error.message}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/commands/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/cli/commands/config.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/generate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generate command implementation
+ */
+import { GenerateOptions } from '../../core/types.js';
+/**
+ * Generate command handler
+ */
+export declare function generateCommand(file?: string, options?: GenerateOptions): Promise<void>;
+//# sourceMappingURL=generate.d.ts.map

package/dist/cli/commands/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAc,eAAe,EAA+B,MAAM,qBAAqB,CAAC;AAU/F;;GAEG;AACH,wBAAsB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0IjG"}