@alien-protocol/cannon 2.2.2

package/src/cannon.js

@@ -0,0 +1,401 @@
+import fs from 'fs';
+import path from 'path';
+import { loadConfig } from './config.js';
+import { loadIssues } from './loaders/index.js';
+import { createIssue, verifyToken, ensureLabel } from './github.js';
+
+// ── ANSI colours ──────────────────────────────────────────────────
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+  blue: '\x1b[34m',
+  white: '\x1b[37m',
+};
+
+const log = {
+  info: (m) => console.log(`${c.cyan}ℹ${c.reset}  ${m}`),
+  success: (m) => console.log(`${c.green}✔${c.reset}  ${m}`),
+  warn: (m) => console.log(`${c.yellow}⚠${c.reset}  ${m}`),
+  error: (m) => console.log(`${c.red}✖${c.reset}  ${m}`),
+  step: (m) => console.log(`\n${c.bold}${c.blue}${m}${c.reset}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
+};
+
+export class IssueCannon {
+  /**
+   * @param {object} options  — programmatic overrides (all optional)
+   * @param {string}  [options.token]
+   * @param {boolean} [options.dryRun]
+   * @param {boolean} [options.safeMode]   — true = random delays (default)
+   * @param {boolean} [options.resumable]
+   * @param {object}  [options.delay]      — { mode, minMs, maxMs, fixedMs }
+   * @param {boolean} [options.silent]     — suppress all console output
+   */
+  constructor(options = {}) {
+    this.config = loadConfig(options);
+    this.silent = options.silent ?? false;
+  }
+
+  async fire(sourceOpts = {}) {
+    const { config } = this;
+
+    // ── Auth check ────────────────────────────────────────────────
+    if (!config.github.token) {
+      log.error('No GitHub token found. To authenticate:\n');
+      log.info(`  ${c.bold}Option A — OAuth login (recommended, no token needed):${c.reset}`);
+      log.info(`    cannon auth login\n`);
+      log.info(`  ${c.bold}Option B — Personal Access Token:${c.reset}`);
+      log.info(`    echo "GITHUB_TOKEN=ghp_xxx" > .env`);
+      log.info(`    Create token: https://github.com/settings/tokens/new`);
+      log.info(`    Required scopes: repo  (or public_repo for public repos only)\n`);
+      throw new Error('Missing GitHub token');
+    }
+
+    // ── Resolve source from config if not passed programmatically ─
+    const effectiveSource = {
+      source: config.source?.type,
+      file: config.source?.file,
+      query: config.source?.query,
+      connectionString: config.source?.connectionString,
+      ...sourceOpts, // programmatic overrides still win
+    };
+
+    // ── Mode banner ───────────────────────────────────────────────
+    if (config.mode.dryRun) {
+      this._log('warn', `${c.yellow}${c.bold}DRY RUN MODE${c.reset} — no issues will be created`);
+    }
+    if (!config.mode.safeMode && !config.mode.dryRun) {
+      this._log(
+        'warn',
+        `${c.red}${c.bold}UNSAFE MODE${c.reset} — issues will fire with NO delays (risk of GitHub spam flag)`
+      );
+    }
+
+    // ── Load issues ───────────────────────────────────────────────
+    this._log('step', '📦 Loading issues…');
+    const issues = await loadIssues(effectiveSource);
+    if (!issues.length) throw new Error('No issues loaded from source');
+    this._log(
+      'info',
+      `Loaded ${c.bold}${issues.length}${c.reset} issue(s) from ${c.cyan}${effectiveSource.source}${c.reset}`
+    );
+
+    const repoMap = issues.reduce((a, r) => {
+      a[r.repo] = (a[r.repo] || 0) + 1;
+      return a;
+    }, {});
+    for (const [repo, n] of Object.entries(repoMap)) {
+      this._log('dim', `${c.blue}${repo}${c.reset}  →  ${n} issue(s)`);
+    }
+
+    // ── Verify token access per repo ──────────────────────────────
+    this._log('step', '🔑 Verifying GitHub access…');
+    const badRepos = new Set();
+    const goodRepos = new Set();
+
+    for (const repo of Object.keys(repoMap)) {
+      const status = await verifyToken(repo, config.github.token);
+      if (status) {
+        const reason =
+          status === 401
+            ? 'token invalid or expired'
+            : status === 403
+              ? 'token lacks required scope (need: repo)'
+              : status === 404
+                ? 'repo not found or no permission'
+                : `HTTP ${status}`;
+        log.warn(`Skipping ${c.blue}${repo}${c.reset}  ${c.dim}(${reason})${c.reset}`);
+        badRepos.add(repo);
+      } else {
+        this._log('success', repo);
+        goodRepos.add(repo);
+      }
+    }
+
+    if (goodRepos.size === 0) {
+      log.error('No accessible repos. Check repo names and token permissions.');
+      log.info(`Run: ${c.bold}cannon auth login${c.reset}  or set GITHUB_TOKEN in .env`);
+      throw new Error('No accessible repos');
+    }
+
+    // ── Auto-create labels if configured ──────────────────────────
+    if (config.labels?.autoCreate && Object.keys(config.labels?.colorMap || {}).length) {
+      this._log('step', '🏷  Auto-creating labels…');
+      for (const repo of goodRepos) {
+        for (const [label, color] of Object.entries(config.labels.colorMap)) {
+          await ensureLabel(repo, label, color, config.github.token);
+        }
+      }
+    }
+
+    // ── Resume state ──────────────────────────────────────────────
+    const state = config.mode.resumable ? this._loadState() : { completed: [], failed: [] };
+    const done = new Set(state.completed);
+    if (done.size) this._log('warn', `Resuming — ${done.size} issue(s) already created, skipping`);
+
+    const pending = issues.filter((r) => !done.has(r.title) && !badRepos.has(r.repo));
+
+    // Pre-fail bad-repo issues
+    const results_prefail = [];
+    issues
+      .filter((r) => badRepos.has(r.repo))
+      .forEach((r) => {
+        const err = 'repo not found or no permission';
+        results_prefail.push({ repo: r.repo, title: r.title, error: err });
+        state.failed.push({ repo: r.repo, title: r.title, error: err });
+      });
+
+    if (!pending.length) {
+      this._log('success', 'All issues already created!');
+      return { created: [], failed: results_prefail };
+    }
+
+    // ── Delay / timing info ───────────────────────────────────────
+    const safeMode = config.mode.safeMode;
+    let estLabel, estMin;
+
+    if (!safeMode) {
+      estLabel = `${c.red}${c.bold}IMMEDIATE${c.reset} (no delays — unsafe mode)`;
+      estMin = 0;
+    } else {
+      const mid = (config.delay.minMs + config.delay.maxMs) / 2;
+      const delayMs = config.delay.mode === 'fixed' ? config.delay.fixedMs : mid;
+      const totalMs = pending.length * delayMs;
+      estMin = Math.ceil(totalMs / 60_000);
+      const delayStr =
+        config.delay.mode === 'fixed'
+          ? `${fmtDelay(config.delay.fixedMs)} fixed`
+          : `${fmtDelay(config.delay.minMs)}–${fmtDelay(config.delay.maxMs)} random`;
+      estLabel = `${c.yellow}${delayStr}${c.reset}  ·  Est. total: ${c.yellow}~${estMin > 0 ? estMin + ' min' : Math.round(totalMs / 1000) + 's'}${c.reset}`;
+    }
+
+    this._log('info', `To create: ${c.bold}${pending.length}${c.reset}  ·  Delay: ${estLabel}\n`);
+    this._log('step', '🚀 Creating issues…\n');
+
+    const startTime = Date.now();
+    const results = { created: [], failed: [] };
+
+    // ── Progress bar ──────────────────────────────────────────────
+    const W = 36;
+
+    const drawBar = (done, total, status = '') => {
+      if (this.silent) return;
+      const f = Math.round((done / total) * W);
+      const bar = `${c.green}${'█'.repeat(f)}${c.dim}${'░'.repeat(W - f)}${c.reset}`;
+      const pct = String(Math.round((done / total) * 100)).padStart(3) + '%';
+      const cnt = `${c.bold}${done}/${total}${c.reset}`;
+      const stat = status ? `  ${status}` : '';
+      const padding = ' '.repeat(
+        Math.max(0, 30 - (status || '').replace(/\x1b\[[\d;]*m/g, '').length)
+      );
+      process.stdout.write(`\x1b[u\x1b[2K  ${bar}  ${pct}  ${cnt}${stat}${padding}\x1b[1B\r`);
+    };
+
+    if (!this.silent) process.stdout.write(`\x1b[s\n`);
+
+    for (let i = 0; i < pending.length; i++) {
+      const issue = pending[i];
+      drawBar(
+        i,
+        pending.length,
+        `${c.yellow}creating…${c.reset}  ${c.dim}${issue.title.slice(0, 35)}${c.reset}`
+      );
+
+      try {
+        const created = await createIssue(issue, config.github.token, config.mode.dryRun);
+        results.created.push({
+          repo: issue.repo,
+          title: issue.title,
+          url: created.html_url,
+          number: created.number,
+        });
+        state.completed.push(issue.title);
+        if (config.mode.resumable) this._saveState(state);
+
+        drawBar(i + 1, pending.length);
+        if (!this.silent)
+          process.stdout.write(
+            `\x1b[2K  ${c.green}✔${c.reset}  ${c.dim}#${created.number ?? i + 1}${c.reset}  ` +
+              `${issue.title.slice(0, 48).padEnd(48)}  ${c.dim}${created.html_url}${c.reset}\n`
+          );
+      } catch (err) {
+        drawBar(i + 1, pending.length, `${c.red}failed${c.reset}`);
+        if (!this.silent)
+          process.stdout.write(
+            `\x1b[2K  ${c.red}✖${c.reset}  ${issue.title.slice(0, 48).padEnd(48)}  ` +
+              `${c.dim}${err.message.startsWith('DUPLICATE') ? 'already exists (skipped)' : err.message.slice(0, 40)}${c.reset}\n`
+          );
+        results.failed.push({ repo: issue.repo, title: issue.title, error: err.message });
+        state.failed.push({ repo: issue.repo, title: issue.title, error: err.message });
+        if (config.mode.resumable) this._saveState(state);
+      }
+
+      // ── Delay between issues ──────────────────────────────────
+      if (i < pending.length - 1) {
+        // Never sleep during a dry run / preview — it's pointless
+        if (safeMode && !config.mode.dryRun) {
+          const delay = this._pickDelay();
+          await liveCountdown(Math.round(delay / 1000), pending.length, i + 1, delay, drawBar);
+        }
+      }
+    }
+
+    // Final bar
+    drawBar(pending.length, pending.length, `${c.green}done${c.reset}`);
+    if (!this.silent) process.stdout.write(`\n`);
+
+    results.failed.push(...results_prefail);
+    this._printSummary(results, startTime);
+
+    // ── Write log file ────────────────────────────────────────────
+    if (config.output?.logFile) {
+      const logPath = path.resolve(config.output.logFile);
+      const logData = {
+        timestamp: new Date().toISOString(),
+        dryRun: config.mode.dryRun,
+        safeMode: config.mode.safeMode,
+        created: results.created,
+        failed: results.failed,
+      };
+      fs.writeFileSync(logPath, JSON.stringify(logData, null, 2));
+      this._log('info', `Log written → ${c.dim}${logPath}${c.reset}`);
+    }
+
+    // Clean up state if everything succeeded
+    if (!results.failed.length && config.mode.resumable) {
+      try {
+        fs.unlinkSync(config.stateFile);
+      } catch {}
+    }
+
+    return results;
+  }
+
+  // ── Private helpers ─────────────────────────────────────────────
+
+  _pickDelay() {
+    const { delay } = this.config;
+    if (delay.mode === 'fixed') return delay.fixedMs;
+    return Math.floor(Math.random() * (delay.maxMs - delay.minMs + 1)) + delay.minMs;
+  }
+
+  _loadState() {
+    try {
+      if (fs.existsSync(this.config.stateFile))
+        return JSON.parse(fs.readFileSync(this.config.stateFile, 'utf-8'));
+    } catch {}
+    return { completed: [], failed: [] };
+  }
+
+  _saveState(state) {
+    fs.writeFileSync(this.config.stateFile, JSON.stringify(state, null, 2));
+  }
+
+  _log(level, msg) {
+    if (this.silent) return;
+    if (log[level]) {
+      log[level](msg);
+    } else {
+      console.log(msg);
+    }
+  }
+
+  _printSummary(results, startTime) {
+    if (!this.config.output?.showTable && !this.silent) return;
+    const elapsed = fmtDelay(Date.now() - (startTime || Date.now()));
+    console.log(`\n${c.bold}${c.blue}📊 Summary${c.reset}\n`);
+
+    const boxTable = (rows, headers, colors) => {
+      const colW = headers.map((h, i) =>
+        Math.min(50, Math.max(h.length, ...rows.map((r) => String(r[i] || '').length)))
+      );
+      const line = (l, m, r) => `  ${l}${colW.map((w) => '─'.repeat(w + 2)).join(m)}${r}`;
+      const fmtRow = (vals, rowColors) =>
+        `  │${vals
+          .map(
+            (v, i) =>
+              ` ${rowColors?.[i] || ''}${String(v || '')
+                .slice(0, colW[i])
+                .padEnd(colW[i])}${c.reset} `
+          )
+          .join('│')}│`;
+
+      console.log(`${c.dim}${line('┌', '┬', '┐')}${c.reset}`);
+      console.log(
+        `${c.dim}${fmtRow(
+          headers,
+          headers.map(() => c.dim + c.bold)
+        )}${c.reset}`
+      );
+      console.log(`${c.dim}${line('├', '┼', '┤')}${c.reset}`);
+      rows.forEach((r) => console.log(`${c.dim}${fmtRow(r, colors)}${c.reset}`));
+      console.log(`${c.dim}${line('└', '┴', '┘')}${c.reset}`);
+    };
+
+    if (results.created.length) {
+      console.log(`${c.green}${c.bold}  ✔  Created: ${results.created.length}${c.reset}\n`);
+      boxTable(
+        results.created.map((r, i) => [`#${r.number ?? i + 1}`, r.repo, r.title, r.url || '']),
+        ['#', 'Repo', 'Title', 'URL'],
+        [c.green, c.blue, c.reset, c.dim]
+      );
+      console.log('');
+    }
+
+    if (results.failed.length) {
+      console.log(`${c.red}${c.bold}  ✖  Failed / Skipped: ${results.failed.length}${c.reset}\n`);
+      const shortReason = (err = '') => {
+        if (err.startsWith('DUPLICATE:')) return '⟳  already exists (skipped)';
+        if (err.includes('not found')) return '✕  repo not found';
+        if (err.includes('no permission')) return '✕  no permission';
+        if (err.includes('required scope')) return '✕  token missing scope';
+        if (err.includes('token invalid')) return '✕  token invalid';
+        if (err.includes('404')) return '✕  not found';
+        if (err.includes('403')) return '✕  forbidden';
+        if (err.includes('401')) return '✕  unauthorized';
+        return err.slice(0, 40);
+      };
+      boxTable(
+        results.failed.map((r) => [r.repo, r.title, shortReason(r.error)]),
+        ['Repo', 'Title', 'Reason'],
+        [c.blue, c.red, c.yellow]
+      );
+      console.log('');
+    }
+
+    const total = results.created.length + results.failed.length;
+    console.log(
+      `  ${c.dim}Total: ${total}  ·  ` +
+        `Created: ${c.green}${results.created.length}${c.reset}${c.dim}  ·  ` +
+        `Failed: ${c.red}${results.failed.length}${c.reset}${c.dim}  ·  ` +
+        `Time: ${c.yellow}${elapsed}${c.reset}\n`
+    );
+  }
+}
+
+// ── Utilities ──────────────────────────────────────────────────────
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function liveCountdown(seconds, total, done, delayMs, drawBar) {
+  for (let s = seconds; s > 0; s--) {
+    const mm = String(Math.floor(s / 60)).padStart(2, '0');
+    const ss = String(s % 60).padStart(2, '0');
+    const est = fmtDelay((total - done) * delayMs + s * 1_000);
+    drawBar(done, total, `\x1b[33mnext in ${mm}:${ss}\x1b[0m  \x1b[2m·  ~${est} left\x1b[0m`);
+    await sleep(1_000);
+  }
+  drawBar(done, total);
+}
+
+function fmtDelay(ms) {
+  const s = Math.round(ms / 1_000);
+  const m = Math.floor(s / 60);
+  return m > 0 ? `${m}m ${s % 60}s` : `${s}s`;
+}

package/src/config.js

@@ -0,0 +1,131 @@
+import fs from 'fs';
+import path from 'path';
+import dotenv from 'dotenv';
+import { getSavedToken } from './auth.js';
+
+const CWD = process.cwd();
+
+// Load .env from project root
+dotenv.config({ path: path.join(CWD, '.env') });
+
+// ── Defaults (mirrors cannon.config.json structure) ──────────────
+const DEFAULTS = {
+  github: {
+    token: '',
+    apiVersion: '2022-11-28',
+  },
+  source: {
+    type: 'csv',
+    file: '',
+    query: '',
+    connectionString: '',
+  },
+  mode: {
+    dryRun: false,
+    safeMode: true,
+    resumable: true,
+  },
+  delay: {
+    mode: 'random',
+    minMs: 240_000, // 4 min
+    maxMs: 480_000, // 8 min
+    fixedMs: 300_000, // 5 min
+  },
+  labels: {
+    autoCreate: false,
+    colorMap: {},
+  },
+  output: {
+    logFile: '',
+    showTable: true,
+  },
+  stateFile: path.join(CWD, '.cannon_state.json'),
+};
+
+/**
+ * Load config from cannon.config.json, merge with defaults,
+ * then apply any programmatic overrides passed in.
+ *
+ * Token resolution order:
+ *   1. overrides.token (programmatic / code)
+ *   2. GITHUB_TOKEN shell env var (or .env file)
+ *   3. ~/.cannon/credentials.json (cannon auth login OAuth)
+ *   4. cannon.config.json github.token (not recommended)
+ */
+export function loadConfig(overrides = {}) {
+  let fileConfig = {};
+  const configPath = path.join(CWD, 'cannon.config.json');
+
+  if (fs.existsSync(configPath)) {
+    try {
+      const raw = fs.readFileSync(configPath, 'utf-8');
+      fileConfig = JSON.parse(raw);
+    } catch (e) {
+      throw new Error(`cannon.config.json has invalid JSON: ${e.message}`);
+    }
+  }
+
+  // Strip comment keys (_xxx) before merging
+  const cleaned = stripComments(fileConfig);
+  const merged = deepMerge(DEFAULTS, cleaned);
+
+  // Support new simple format: delay.min / delay.max in MINUTES
+  // Convert to ms so the rest of the codebase stays unchanged
+  if (cleaned.delay?.min !== undefined && cleaned.delay?.fixedMs === undefined) {
+    merged.delay.minMs = Math.round((cleaned.delay.min ?? 4) * 60_000);
+    merged.delay.maxMs = Math.round((cleaned.delay.max ?? 8) * 60_000);
+    merged.delay.mode = 'random';
+  }
+
+  // Token priority chain
+  const token =
+    overrides.token || process.env.GITHUB_TOKEN || getSavedToken() || merged.github?.token || '';
+
+  // Programmatic overrides win over file config for simple fields
+  const mode = {
+    ...merged.mode,
+    ...(overrides.dryRun !== undefined ? { dryRun: overrides.dryRun } : {}),
+    ...(overrides.safeMode !== undefined ? { safeMode: overrides.safeMode } : {}),
+    ...(overrides.resumable !== undefined ? { resumable: overrides.resumable } : {}),
+  };
+
+  // Allow old-style `delay` override object to still work
+  const delay = overrides.delay ? { ...merged.delay, ...overrides.delay } : merged.delay;
+
+  return {
+    ...merged,
+    github: { ...merged.github, token },
+    mode,
+    delay,
+    stateFile: overrides.stateFile ?? merged.stateFile ?? DEFAULTS.stateFile,
+  };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+/** Remove all keys starting with "_" (comment keys) */
+function stripComments(obj) {
+  if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) return obj;
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.startsWith('_')) continue;
+    out[k] = stripComments(v);
+  }
+  return out;
+}
+
+function deepMerge(base, override) {
+  const result = { ...base };
+  for (const key of Object.keys(override ?? {})) {
+    if (
+      typeof override[key] === 'object' &&
+      override[key] !== null &&
+      !Array.isArray(override[key])
+    ) {
+      result[key] = deepMerge(base[key] ?? {}, override[key]);
+    } else {
+      result[key] = override[key];
+    }
+  }
+  return result;
+}

package/src/github.js

@@ -0,0 +1,167 @@
+const GITHUB_API = 'https://api.github.com';
+
+export async function verifyToken(repo, token) {
+  const res = await fetch(`${GITHUB_API}/repos/${repo}`, {
+    headers: authHeaders(token),
+  });
+  return res.ok ? null : res.status;
+}
+
+const _milestoneCache = {};
+
+export async function getOrCreateMilestone(repo, milestoneName, token) {
+  if (!milestoneName) return null;
+  const key = `${repo}::${milestoneName}`;
+  if (_milestoneCache[key] !== undefined) return _milestoneCache[key];
+
+  const listRes = await fetch(`${GITHUB_API}/repos/${repo}/milestones?state=all&per_page=50`, {
+    headers: authHeaders(token),
+  });
+  if (!listRes.ok) return (_milestoneCache[key] = null);
+
+  const milestones = await listRes.json();
+  const existing = milestones.find((m) => m.title === milestoneName);
+  if (existing) return (_milestoneCache[key] = existing.number);
+
+  const createRes = await fetch(`${GITHUB_API}/repos/${repo}/milestones`, {
+    method: 'POST',
+    headers: { ...authHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ title: milestoneName }),
+  });
+  if (!createRes.ok) return (_milestoneCache[key] = null);
+  const created = await createRes.json();
+  return (_milestoneCache[key] = created.number);
+}
+
+// ── Label auto-creation ───────────────────────────────────────────
+
+const _labelCache = {};
+
+/**
+ * Ensure a label exists in a repo.
+ * Creates it with the given hex color if it doesn't exist.
+ * @param {string} repo    — "owner/repo"
+ * @param {string} name    — label name
+ * @param {string} color   — hex color WITHOUT #, e.g. "ee0701"
+ * @param {string} token   — GitHub PAT
+ */
+export async function ensureLabel(repo, name, color, token) {
+  const key = `${repo}::${name}`;
+  if (_labelCache[key]) return;
+
+  // Check existing labels
+  const listRes = await fetch(`${GITHUB_API}/repos/${repo}/labels?per_page=100`, {
+    headers: authHeaders(token),
+  });
+  if (listRes.ok) {
+    const labels = await listRes.json();
+    if (labels.find((l) => l.name === name)) {
+      _labelCache[key] = true;
+      return;
+    }
+  }
+
+  // Create label
+  const createRes = await fetch(`${GITHUB_API}/repos/${repo}/labels`, {
+    method: 'POST',
+    headers: { ...authHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name, color: color.replace('#', '') }),
+  });
+  _labelCache[key] = createRes.ok;
+}
+
+const _existingTitles = {};
+
+async function fetchExistingTitles(repo, token) {
+  if (_existingTitles[repo]) return _existingTitles[repo];
+  const titles = new Set();
+  let page = 1;
+  while (true) {
+    const res = await fetch(
+      `${GITHUB_API}/repos/${repo}/issues?state=all&per_page=100&page=${page}`,
+      { headers: authHeaders(token) }
+    );
+    if (!res.ok) break;
+    const items = await res.json();
+    if (!items.length) break;
+    items.forEach((i) => titles.add(i.title.trim().toLowerCase()));
+    if (items.length < 100) break;
+    page++;
+  }
+  _existingTitles[repo] = titles;
+  return titles;
+}
+
+/**
+ * Create a single GitHub issue.
+ * Skips duplicates (same title already exists in repo).
+ *
+ * @param {object}  issue   — { repo, title, body, labels, milestone }
+ * @param {string}  token   — GitHub PAT
+ * @param {boolean} dryRun  — if true, returns a fake response without hitting the API
+ */
+export async function createIssue(issue, token, dryRun = false) {
+  const repo = issue.repo?.trim();
+  if (!repo) throw new Error(`Issue missing 'repo': "${issue.title}"`);
+
+  if (!dryRun) {
+    const existing = await fetchExistingTitles(repo, token);
+    if (existing.has(issue.title.trim().toLowerCase())) {
+      throw new Error(`DUPLICATE: issue already exists in ${repo}`);
+    }
+  }
+
+  const labels = normLabels(issue.labels);
+  const milestoneNumber = await getOrCreateMilestone(repo, issue.milestone, token);
+
+  const payload = {
+    title: issue.title?.trim(),
+    body: issue.body?.trim() ?? '',
+    labels,
+    ...(milestoneNumber ? { milestone: milestoneNumber } : {}),
+  };
+
+  if (dryRun) {
+    return { html_url: `https://github.com/${repo}/issues/0`, number: 0, _dryRun: true };
+  }
+
+  const res = await fetch(`${GITHUB_API}/repos/${repo}/issues`, {
+    method: 'POST',
+    headers: { ...authHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    const hint =
+      res.status === 403
+        ? ' — check token has "repo" or "public_repo" scope'
+        : res.status === 401
+          ? ' — token invalid or expired; run: cannon auth login'
+          : '';
+    throw new Error(`GitHub ${res.status} on ${repo}${hint}: ${text}`);
+  }
+
+  const created = await res.json();
+  if (_existingTitles[repo]) {
+    _existingTitles[repo].add(created.title.trim().toLowerCase());
+  }
+  return created;
+}
+
+function authHeaders(token) {
+  return {
+    Authorization: `Bearer ${token}`,
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+}
+
+function normLabels(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw.map((l) => l.trim()).filter(Boolean);
+  return raw
+    .split(',')
+    .map((l) => l.trim())
+    .filter(Boolean);
+}