🛸 @alien-protocol/cannon

Stop manually creating GitHub issues. Bulk-create, update, and sync issues from CSV, JSON, PDF, DOCX, or any database — in one command.

---

⚡ Why Cannon?

⏳	Save hours of manual issue creation
🔁	Sync any backlog → GitHub instantly
🛡️	Built-in duplicate detection & safe delays
⚙️	Works with CSV, Excel, databases, Word docs
♻️	Resumable — stop and restart safely

---

🚀 Quick Start

npm install -g @alien-protocol/cannon

cannon init            # 1. create cannon.config.json
cannon auth login      # 2. OAuth login — no token needed
cannon fire --preview  # 3. dry run — nothing created yet
cannon fire            # 4. go live

---

👀 See It In Action

---

🎯 Use Cases

Scenario	How
Import 100+ issues from Excel	Save as CSV → cannon fire -s csv -f ./issues.csv
Migrate backlog between repos	Export issues, update repo column, fire
Auto-create from product docs	Convert Word table to DOCX → point cannon at it
Sync a database → GitHub	Use postgres / mysql / sqlite source
Bulk-update existing issues	Set action column to update

---

📄 Your Data File

All sources use the same columns:

Column	Required	Description	Example
repo	✅	Target repository	owner/repo
title	✅	Issue title — also the lookup key for update	Fix login bug
action	—	create (default) or update	create
body	—	Description — markdown supported	Steps to reproduce…
labels	—	Comma-separated label names	bug,auth
milestone	—	Auto-created if it doesn't exist	v1.0

How action works

Value	What cannon does	If title already exists
create	Opens a new issue	Skipped — duplicate guard
update	Finds issue by title, patches body / labels / milestone	Title is the stable key
(blank)	Same as create	Same as create

CSV example

action	repo	title	body	labels	milestone
create	owner/repo	Fix login bug	Steps to reproduce…	bug	v1.0
update	owner/repo	Fix login bug	Updated steps	bug,high	v1.0
create	owner/repo	Add dark mode	User request	enhancement	v1.1

Supported sources

Format	Config snippet
CSV	"type": "csv", "file": "./issues.csv"
JSON	"type": "json", "file": "./issues.json"
PDF	"type": "pdf", "file": "./issues.pdf"
DOCX / Word	"type": "docx", "file": "./issues.docx"
SQLite	"type": "sqlite", "file": "./backlog.db", "query": "SELECT …"
PostgreSQL	"type": "postgres", "connectionString": "${POSTGRES_URL}", "query": "SELECT …"
MySQL	"type": "mysql", "connectionString": "${MYSQL_URL}", "query": "SELECT …"

---

⚙️ Config File

{
  "source": { "type": "csv", "file": "./issues.csv" },
  "mode":   { "safeMode": true, "dryRun": false, "resumable": true },
  "delay":  { "min": 4, "max": 8 }
}

Key	Default	What it does
source.type	csv	One of: csv json pdf docx sqlite postgres mysql
mode.safeMode	true	Random 4–8 min delays — prevents GitHub spam flags
mode.dryRun	false	Preview only, nothing is created
mode.resumable	true	Saves progress — safe to stop and restart
delay.min / max	4 / 8	Minutes between issues (safeMode only)

---

🖥️ Commands

Auth

Command	What it does
cannon auth login	OAuth login — no token needed
cannon auth status	Show who is logged in
cannon auth logout	Remove saved credentials

Setup

Command	What it does
cannon init	Create cannon.config.json
cannon validate	Check config + source file before firing

Fire

Command	What it does
cannon fire	Run using cannon.config.json
cannon fire --preview	Dry run — nothing created, no delays
cannon fire --unsafe	No delays (fast, risky)
cannon fire --delay 2	Fixed 2-min delay between issues
cannon fire --fresh	Ignore saved progress, start over
cannon fire -s csv -f ./my.csv	Override source without editing config

---

🔌 Programmatic Use

import { IssueCannon } from '@alien-protocol/cannon';

const { created, updated, failed } = await new IssueCannon({ safeMode: true })
  .fire({ source: 'csv', file: './issues.csv' });

console.log(`Created: ${created.length}  Updated: ${updated.length}  Failed: ${failed.length}`);

---

🔐 Token Security

Tokens are never stored in your project. cannon auth login saves to ~/.cannon/credentials.json (chmod 600).

Resolution order

Priority	Source
1	new IssueCannon({ token: '...' }) — programmatic
2	GITHUB_TOKEN env var or .env file
3	cannon auth login → ~/.cannon/credentials.json
4	cannon.config.json github.token — not recommended

.gitignore

.env
.cannon_state.json
cannon-log.json

cannon.config.json is safe to commit — just leave github.token blank.

---

---

🛸 Alien Protocol

• Built by ryzen-xp
• npm
• Report a bug
• MIT License