@alien-protocol/cannon 2.2.2 → 2.3.0

package/.env.example

@@ -1,12 +1,4 @@
-# ─────────────────────────────────────────────
-# .env.example  —  copy to .env  (never commit .env!)
-# ─────────────────────────────────────────────
-
-# Your GitHub Personal Access Token
-# Create one at: https://github.com/settings/tokens/new
-# Required scope: repo  (or public_repo for public repos only)
 GITHUB_TOKEN=ghp_your_token_here
 
-# Database connection strings (only needed for DB sources)
 POSTGRES_URL=postgres://user:password@localhost:5432/mydb
 MYSQL_URL=mysql://user:password@localhost:3306/mydb

package/README.md

@@ -1,6 +1,6 @@
 # 🛸 @alien-protocol/cannon
 
-> Bulk-create GitHub issues from **CSV, PDF, DOCX, JSON, or any SQL database** — one config file, safe delays, duplicate detection, and resume support.
+> Bulk-create **and update** GitHub issues from **CSV, PDF, DOCX, JSON, or any SQL database** — one config file, safe delays, duplicate detection, and resume support.
 
 ## Installation
 
@@ -33,10 +33,10 @@ cannon init
 # 2. Login with GitHub (no token needed)
 cannon auth login
 
-# 3. Preview — nothing gets created
+# 3. Preview — nothing gets created or updated
 cannon fire --preview
 
-# 4. Create your issues
+# 4. Fire your issues
 cannon fire
 ```
 
@@ -97,24 +97,24 @@ cannon fire
 
 ### Config Options
 
-| Key                       | Default        | Description                                                       |
-| ------------------------- | -------------- | ----------------------------------------------------------------- |
+| Key                       | Default        | Description                                                        |
+| ------------------------- | -------------- | ------------------------------------------------------------------ |
 | `source.type`             | `csv`          | `csv` · `json` · `pdf` · `docx` · `sqlite` · `postgres` · `mysql` |
-| `source.file`             | `./issues.csv` | Path to your issues file                                          |
-| `source.query`            | —              | SQL query (database sources only)                                 |
-| `source.connectionString` | —              | DB connection URL — use `${ENV_VAR}`, never hardcode              |
-| `mode.safeMode`           | `true`         | Random delays between issues — keeps you off GitHub's radar       |
-| `mode.dryRun`             | `false`        | Preview only, nothing created                                     |
-| `mode.resumable`          | `true`         | Saves progress so you can stop and restart safely                 |
-| `delay.min`               | `4`            | Minimum minutes between issues                                    |
-| `delay.max`               | `8`            | Maximum minutes between issues                                    |
-| `labels.autoCreate`       | `false`        | Auto-create missing labels in GitHub                              |
-| `labels.colors`           | see above      | Label name → hex color for auto-creation                          |
-| `output.logFile`          | —              | Save a JSON results log to this path                              |
-| `output.showTable`        | `true`         | Show a summary table after completion                             |
-| `notify.webhookUrl`       | —              | Slack / Discord / Teams webhook URL                               |
-| `notify.onSuccess`        | `true`         | Notify when batch completes successfully                          |
-| `notify.onFailure`        | `true`         | Notify when any issues fail                                       |
+| `source.file`             | `./issues.csv` | Path to your issues file                                           |
+| `source.query`            | —              | SQL query (database sources only)                                  |
+| `source.connectionString` | —              | DB connection URL — use `${ENV_VAR}`, never hardcode               |
+| `mode.safeMode`           | `true`         | Random delays between issues — keeps you off GitHub's radar        |
+| `mode.dryRun`             | `false`        | Preview only, nothing created or updated                           |
+| `mode.resumable`          | `true`         | Saves progress so you can stop and restart safely                  |
+| `delay.min`               | `4`            | Minimum minutes between issues                                     |
+| `delay.max`               | `8`            | Maximum minutes between issues                                     |
+| `labels.autoCreate`       | `false`        | Auto-create missing labels in GitHub                               |
+| `labels.colors`           | see above      | Label name → hex color for auto-creation                           |
+| `output.logFile`          | —              | Save a JSON results log to this path                               |
+| `output.showTable`        | `true`         | Show a summary table after completion                              |
+| `notify.webhookUrl`       | —              | Slack / Discord / Teams webhook URL                                |
+| `notify.onSuccess`        | `true`         | Notify when batch completes successfully                           |
+| `notify.onFailure`        | `true`         | Notify when any issues fail                                        |
 
 ---
 
@@ -159,11 +159,11 @@ Checks your config is valid JSON · token is present · source file exists · is
 
 ### `cannon fire`
 
-Create your issues.
+Create and/or update your issues.
 
 ```bash
 cannon fire                          # run using cannon.config.json
-cannon fire --preview                # dry run — nothing created, no delays
+cannon fire --preview                # dry run — nothing created or updated, no delays
 cannon fire --unsafe                 # no delays (fast but risky)
 cannon fire --delay 2                # fixed 2-minute delay between issues
 cannon fire --fresh                  # ignore saved progress, start over
@@ -175,15 +175,15 @@ cannon fire -s docx -f ./issues.docx --delay 1
 cannon fire -s pdf  -f ./issues.pdf  --unsafe
 ```
 
-| Flag             | What it does                                            |
-| ---------------- | ------------------------------------------------------- |
-| `--preview`      | Dry run — shows what would be created, skips all delays |
-| `--unsafe`       | No delays at all — fast but GitHub may flag as spam     |
-| `--delay <mins>` | Fixed delay in minutes, e.g. `--delay 2`                |
-| `--fresh`        | Ignore saved progress and start from the beginning      |
-| `-s <type>`      | Source type override                                    |
-| `-f <path>`      | Source file override                                    |
-| `-q <sql>`       | SQL query override (database sources)                   |
+| Flag             | What it does                                                      |
+| ---------------- | ----------------------------------------------------------------- |
+| `--preview`      | Dry run — shows what would be created/updated, skips all delays   |
+| `--unsafe`       | No delays at all — fast but GitHub may flag as spam               |
+| `--delay <mins>` | Fixed delay in minutes, e.g. `--delay 2`                          |
+| `--fresh`        | Ignore saved progress and start from the beginning                |
+| `-s <type>`      | Source type override                                              |
+| `-f <path>`      | Source file override                                              |
+| `-q <sql>`       | SQL query override (database sources)                             |
 
 ---
 
@@ -203,22 +203,36 @@ Safe mode is on by default. For large batches never turn it off.
 
 Every source needs at minimum: `repo` and `title`.
 
-| Field       | Required | Description                               |
-| ----------- | -------- | ----------------------------------------- |
-| `repo`      | ✅       | `owner/repo`                              |
-| `title`     | ✅       | Issue title                               |
-| `body`      | —        | Description                               |
-| `labels`    | —        | Comma-separated: `bug,auth`               |
-| `milestone` | —        | Auto-created if it doesn't exist          |
-| `priority`  | —        | `HIGH` · `MED` · `LOW` (informational)    |
-| `track`     | —        | e.g. `auth`, `ui`, `docs` (informational) |
+| Field       | Required | Description                                                     |
+| ----------- | -------- | --------------------------------------------------------------- |
+| `action`    | —        | `create` (default) or `update` — controls what cannon does      |
+| `repo`      | ✅       | `owner/repo`                                                    |
+| `title`     | ✅       | Issue title — used as the lookup key for `update`               |
+| `body`      | —        | Description                                                     |
+| `labels`    | —        | Comma-separated: `bug,auth`                                     |
+| `milestone` | —        | Auto-created if it doesn't exist                                |
+| `priority`  | —        | `HIGH` · `MED` · `LOW` (informational)                          |
+| `track`     | —        | e.g. `auth`, `ui`, `docs` (informational)                       |
+
+### The `action` column
+
+Add an `action` column to any source file to mix creates and updates in a single run.
+
+| Value          | What cannon does                                                                                           |
+| -------------- | ---------------------------------------------------------------------------------------------------------- |
+| `create`       | Opens a **new** issue. Skipped if an issue with the same title already exists (duplicate guard).           |
+| `update`       | Finds the **existing** issue by exact title match, then patches its body, labels, and milestone.           |
+| *(blank/omit)* | Defaults to `create`.                                                                                      |
+
+> **Note:** For `update`, the title is the stable lookup key — it is not changed by the patch. If no matching issue is found, the row fails with `UPDATE_NOT_FOUND` and is shown in the summary.
 
 ### CSV
 
 ```csv
-repo,title,body,labels,milestone
-owner/repo,Fix login bug,"Steps to reproduce...",bug,v1.0
-owner/repo,Add dark mode,"User request",enhancement,v1.1
+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 repro steps and raised priority",bug high,v1.0
+create,owner/repo,Add dark mode,"User request",enhancement,v1.1
 ```
 
 ```json
@@ -230,11 +244,19 @@ owner/repo,Add dark mode,"User request",enhancement,v1.1
 ```json
 [
   {
+    "action": "create",
     "repo": "owner/repo",
     "title": "Fix login bug",
     "body": "Steps to reproduce...",
     "labels": "bug,auth",
     "milestone": "v1.0"
+  },
+  {
+    "action": "update",
+    "repo": "owner/repo",
+    "title": "Fix login bug",
+    "body": "Updated repro steps.",
+    "labels": "bug,auth,high"
   }
 ]
 ```
@@ -272,9 +294,10 @@ owner/repo | Fix login bug | Steps | bug,auth
 
 A table in your Word file. First row = headers.
 
-| repo       | title         | body     | labels   |
-| ---------- | ------------- | -------- | -------- |
-| owner/repo | Fix login bug | Steps... | bug,auth |
+| action | repo       | title         | body     | labels   |
+| ------ | ---------- | ------------- | -------- | -------- |
+| create | owner/repo | Fix login bug | Steps... | bug,auth |
+| update | owner/repo | Fix login bug | Updated. | bug,high |
 
 ```json
 "source": { "type": "docx", "file": "./issues.docx" }
@@ -291,7 +314,7 @@ POSTGRES_URL=postgres://user:password@localhost:5432/mydb
 "source": {
   "type": "postgres",
   "connectionString": "${POSTGRES_URL}",
-  "query": "SELECT repo, title, body, labels, milestone FROM backlog WHERE exported = false"
+  "query": "SELECT action, repo, title, body, labels, milestone FROM backlog WHERE exported = false"
 }
 ```
 
@@ -301,7 +324,7 @@ POSTGRES_URL=postgres://user:password@localhost:5432/mydb
 "source": {
   "type": "mysql",
   "connectionString": "${MYSQL_URL}",
-  "query": "SELECT repo, title, body, labels FROM issues WHERE status = 'pending'"
+  "query": "SELECT action, repo, title, body, labels FROM issues WHERE status = 'pending'"
 }
 ```
 
@@ -311,7 +334,7 @@ POSTGRES_URL=postgres://user:password@localhost:5432/mydb
 "source": {
   "type": "sqlite",
   "file": "./backlog.db",
-  "query": "SELECT repo, title, body, labels FROM issues"
+  "query": "SELECT action, repo, title, body, labels FROM issues"
 }
 ```
 
@@ -361,12 +384,44 @@ const cannon = new IssueCannon({
   dryRun: false,
 });
 
-const { created, failed } = await cannon.fire({
+const { created, updated, failed } = await cannon.fire({
   source: 'csv',
   file: './issues.csv',
 });
 
-console.log(`Created: ${created.length}  Failed: ${failed.length}`);
+console.log(`Created: ${created.length}  Updated: ${updated.length}  Failed: ${failed.length}`);
+```
+
+---
+
+## Summary Output
+
+After a run with mixed actions, cannon prints three sections:
+
+```
+✔  Created: 4
+
+  ┌───┬──────────────┬──────────────────────────┬────────────────────────────────────┐
+  │ # │ Repo         │ Title                    │ URL                                │
+  ├───┼──────────────┼──────────────────────────┼────────────────────────────────────┤
+  │ 1 │ owner/repo   │ Add dark mode            │ https://github.com/owner/repo/i... │
+  └───┴──────────────┴──────────────────────────┴────────────────────────────────────┘
+
+↑  Updated: 2
+
+  ┌───┬──────────────┬──────────────────────────┬────────────────────────────────────┐
+  │ # │ Repo         │ Title                    │ URL                                │
+  ├───┼──────────────┼──────────────────────────┼────────────────────────────────────┤
+  │ 7 │ owner/repo   │ Fix login bug            │ https://github.com/owner/repo/i... │
+  └───┴──────────────┴──────────────────────────┴────────────────────────────────────┘
+
+✖  Failed / Skipped: 1
+
+  ┌────────┬──────────────┬──────────────────────┬──────────────────────────────┐
+  │ Action │ Repo         │ Title                │ Reason                       │
+  ├────────┼──────────────┼──────────────────────┼──────────────────────────────┤
+  │ update │ owner/repo   │ Nonexistent issue    │ ✕  issue not found for update│
+  └────────┴──────────────┴──────────────────────┴──────────────────────────────┘
 ```
 
 ---
@@ -392,4 +447,4 @@ console.log(`Created: ${created.length}  Failed: ${failed.length}`);
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alien-protocol/cannon",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "publishConfig": {
     "access": "public"
   },

package/src/cannon.js

@@ -2,7 +2,7 @@ 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';
+import { createIssue, updateIssue, verifyToken, ensureLabel } from './github.js';
 
 // ── ANSI colours ──────────────────────────────────────────────────
 const c = {
@@ -63,12 +63,12 @@ export class IssueCannon {
       file: config.source?.file,
       query: config.source?.query,
       connectionString: config.source?.connectionString,
-      ...sourceOpts, // programmatic overrides still win
+      ...sourceOpts,
     };
 
     // ── Mode banner ───────────────────────────────────────────────
     if (config.mode.dryRun) {
-      this._log('warn', `${c.yellow}${c.bold}DRY RUN MODE${c.reset} — no issues will be created`);
+      this._log('warn', `${c.yellow}${c.bold}DRY RUN MODE${c.reset} — no issues will be created or updated`);
     }
     if (!config.mode.safeMode && !config.mode.dryRun) {
       this._log(
@@ -81,9 +81,15 @@ export class IssueCannon {
     this._log('step', '📦 Loading issues…');
     const issues = await loadIssues(effectiveSource);
     if (!issues.length) throw new Error('No issues loaded from source');
+
+    // Split by action for reporting
+    const toCreate = issues.filter((r) => r.action === 'create');
+    const toUpdate = issues.filter((r) => r.action === 'update');
+
     this._log(
       'info',
-      `Loaded ${c.bold}${issues.length}${c.reset} issue(s) from ${c.cyan}${effectiveSource.source}${c.reset}`
+      `Loaded ${c.bold}${issues.length}${c.reset} issue(s) from ${c.cyan}${effectiveSource.source}${c.reset}` +
+      `  ${c.dim}(${c.green}${toCreate.length} create${c.reset}${c.dim}, ${c.yellow}${toUpdate.length} update${c.reset}${c.dim})${c.reset}`
     );
 
     const repoMap = issues.reduce((a, r) => {
@@ -137,7 +143,7 @@ export class IssueCannon {
     // ── 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`);
+    if (done.size) this._log('warn', `Resuming — ${done.size} issue(s) already processed, skipping`);
 
     const pending = issues.filter((r) => !done.has(r.title) && !badRepos.has(r.repo));
 
@@ -147,27 +153,26 @@ export class IssueCannon {
       .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 });
+        results_prefail.push({ action: r.action, repo: r.repo, title: r.title, error: err });
+        state.failed.push({ action: r.action, repo: r.repo, title: r.title, error: err });
       });
 
     if (!pending.length) {
-      this._log('success', 'All issues already created!');
-      return { created: [], failed: results_prefail };
+      this._log('success', 'All issues already processed!');
+      return { created: [], updated: [], failed: results_prefail };
     }
 
     // ── Delay / timing info ───────────────────────────────────────
     const safeMode = config.mode.safeMode;
-    let estLabel, estMin;
+    let estLabel;
 
     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 estMin = Math.ceil(totalMs / 60_000);
       const delayStr =
         config.delay.mode === 'fixed'
           ? `${fmtDelay(config.delay.fixedMs)} fixed`
@@ -175,11 +180,11 @@ export class IssueCannon {
       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');
+    this._log('info', `To process: ${c.bold}${pending.length}${c.reset}  ·  Delay: ${estLabel}\n`);
+    this._log('step', '🚀 Processing issues…\n');
 
     const startTime = Date.now();
-    const results = { created: [], failed: [] };
+    const results = { created: [], updated: [], failed: [] };
 
     // ── Progress bar ──────────────────────────────────────────────
     const W = 36;
@@ -201,44 +206,85 @@ export class IssueCannon {
 
     for (let i = 0; i < pending.length; i++) {
       const issue = pending[i];
+      const actionLabel = issue.action === 'update'
+        ? `${c.yellow}updating…${c.reset}`
+        : `${c.cyan}creating…${c.reset}`;
+
       drawBar(
         i,
         pending.length,
-        `${c.yellow}creating…${c.reset}  ${c.dim}${issue.title.slice(0, 35)}${c.reset}`
+        `${actionLabel}  ${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`
-          );
+        let result;
+
+        if (issue.action === 'update') {
+          // ── UPDATE path ──────────────────────────────────────
+          result = await updateIssue(issue, config.github.token, config.mode.dryRun);
+          results.updated.push({
+            repo: issue.repo,
+            title: issue.title,
+            url: result.html_url,
+            number: result.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.yellow}↑${c.reset}  ${c.dim}#${result.number ?? i + 1}${c.reset}  ` +
+              `${issue.title.slice(0, 48).padEnd(48)}  ${c.dim}${result.html_url}${c.reset}\n`
+            );
+        } else {
+          // ── CREATE path ──────────────────────────────────────
+          result = await createIssue(issue, config.github.token, config.mode.dryRun);
+          results.created.push({
+            repo: issue.repo,
+            title: issue.title,
+            url: result.html_url,
+            number: result.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}#${result.number ?? i + 1}${c.reset}  ` +
+              `${issue.title.slice(0, 48).padEnd(48)}  ${c.dim}${result.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`
+            `${c.dim}${err.message.startsWith('DUPLICATE')
+              ? 'already exists (skipped)'
+              : err.message.startsWith('UPDATE_NOT_FOUND')
+                ? 'issue not found for update'
+                : 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 });
+        results.failed.push({
+          action: issue.action,
+          repo: issue.repo,
+          title: issue.title,
+          error: err.message,
+        });
+        state.failed.push({
+          action: issue.action,
+          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);
@@ -261,6 +307,7 @@ export class IssueCannon {
         dryRun: config.mode.dryRun,
         safeMode: config.mode.safeMode,
         created: results.created,
+        updated: results.updated,
         failed: results.failed,
       };
       fs.writeFileSync(logPath, JSON.stringify(logData, null, 2));
@@ -271,7 +318,7 @@ export class IssueCannon {
     if (!results.failed.length && config.mode.resumable) {
       try {
         fs.unlinkSync(config.stateFile);
-      } catch {}
+      } catch { }
     }
 
     return results;
@@ -289,7 +336,7 @@ export class IssueCannon {
     try {
       if (fs.existsSync(this.config.stateFile))
         return JSON.parse(fs.readFileSync(this.config.stateFile, 'utf-8'));
-    } catch {}
+    } catch { }
     return { completed: [], failed: [] };
   }
 
@@ -348,10 +395,21 @@ export class IssueCannon {
       console.log('');
     }
 
+    if (results.updated.length) {
+      console.log(`${c.yellow}${c.bold}  ↑  Updated: ${results.updated.length}${c.reset}\n`);
+      boxTable(
+        results.updated.map((r, i) => [`#${r.number ?? i + 1}`, r.repo, r.title, r.url || '']),
+        ['#', 'Repo', 'Title', 'URL'],
+        [c.yellow, 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.startsWith('UPDATE_NOT_FOUND:')) return '✕  issue not found for update';
         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';
@@ -362,19 +420,20 @@ export class IssueCannon {
         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]
+        results.failed.map((r) => [r.action ?? 'create', r.repo, r.title, shortReason(r.error)]),
+        ['Action', 'Repo', 'Title', 'Reason'],
+        [c.cyan, c.blue, c.red, c.yellow]
       );
       console.log('');
     }
 
-    const total = results.created.length + results.failed.length;
+    const total = results.created.length + results.updated.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`
+      `Created: ${c.green}${results.created.length}${c.reset}${c.dim}  ·  ` +
+      `Updated: ${c.yellow}${results.updated.length}${c.reset}${c.dim}  ·  ` +
+      `Failed: ${c.red}${results.failed.length}${c.reset}${c.dim}  ·  ` +
+      `Time: ${c.yellow}${elapsed}${c.reset}\n`
     );
   }
 }
@@ -398,4 +457,4 @@ 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/github.js

@@ -37,19 +37,10 @@ export async function getOrCreateMilestone(repo, milestoneName, token) {
 
 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),
   });
@@ -61,7 +52,6 @@ export async function ensureLabel(repo, name, color, token) {
     }
   }
 
-  // Create label
   const createRes = await fetch(`${GITHUB_API}/repos/${repo}/labels`, {
     method: 'POST',
     headers: { ...authHeaders(token), 'Content-Type': 'application/json' },
@@ -71,8 +61,9 @@ export async function ensureLabel(repo, name, color, token) {
 }
 
 const _existingTitles = {};
+const _issueNumberCache = {};
 
-async function fetchExistingTitles(repo, token) {
+async function fetchExistingIssues(repo, token) {
   if (_existingTitles[repo]) return _existingTitles[repo];
   const titles = new Set();
   let page = 1;
@@ -84,7 +75,13 @@ async function fetchExistingTitles(repo, token) {
     if (!res.ok) break;
     const items = await res.json();
     if (!items.length) break;
-    items.forEach((i) => titles.add(i.title.trim().toLowerCase()));
+    items.forEach((i) => {
+      const key = i.title.trim().toLowerCase();
+      titles.add(key);
+      // Cache issue number by title for update lookup
+      if (!_issueNumberCache[repo]) _issueNumberCache[repo] = {};
+      _issueNumberCache[repo][key] = i.number;
+    });
     if (items.length < 100) break;
     page++;
   }
@@ -92,20 +89,27 @@ async function fetchExistingTitles(repo, token) {
   return titles;
 }
 
+/**
+ * Find an existing issue number by title.
+ * Returns null if not found.
+ */
+export async function findIssueByTitle(repo, title, token) {
+  await fetchExistingIssues(repo, token);
+  const key = title.trim().toLowerCase();
+  const number = _issueNumberCache[repo]?.[key];
+  return number ?? null;
+}
+
 /**
  * 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);
+    const existing = await fetchExistingIssues(repo, token);
     if (existing.has(issue.title.trim().toLowerCase())) {
       throw new Error(`DUPLICATE: issue already exists in ${repo}`);
     }
@@ -149,6 +153,64 @@ export async function createIssue(issue, token, dryRun = false) {
   return created;
 }
 
+/**
+ * Update an existing GitHub issue by title match.
+ * Finds the issue number from the repo, then PATCHes it.
+ *
+ * @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 updateIssue(issue, token, dryRun = false) {
+  const repo = issue.repo?.trim();
+  if (!repo) throw new Error(`Issue missing 'repo': "${issue.title}"`);
+
+  if (dryRun) {
+    return {
+      html_url: `https://github.com/${repo}/issues/0`,
+      number: 0,
+      _dryRun: true,
+      _updated: true,
+    };
+  }
+
+  // Find existing issue number by title
+  const issueNumber = await findIssueByTitle(repo, issue.title, token);
+  if (!issueNumber) {
+    throw new Error(`UPDATE_NOT_FOUND: no issue with title "${issue.title}" found 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 } : {}),
+  };
+
+  const res = await fetch(`${GITHUB_API}/repos/${repo}/issues/${issueNumber}`, {
+    method: 'PATCH',
+    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}#${issueNumber}${hint}: ${text}`);
+  }
+
+  const updated = await res.json();
+  return { ...updated, _updated: true };
+}
+
 function authHeaders(token) {
   return {
     Authorization: `Bearer ${token}`,
@@ -164,4 +226,4 @@ function normLabels(raw) {
     .split(',')
     .map((l) => l.trim())
     .filter(Boolean);
-}
+}

package/src/loaders/index.js

@@ -17,6 +17,8 @@ const LOADERS = {
   array: async (opts) => opts.data ?? [],
 };
 
+const VALID_ACTIONS = ['create', 'update'];
+
 /**
  * @param {{ source: string, [key: string]: any }} opts
  * @returns {Promise<object[]>}
@@ -34,11 +36,17 @@ export async function loadIssues(opts = {}) {
 
   const issues = await loader(rest);
 
-  // Normalise: ensure required fields exist
+  // Normalise: ensure required fields exist and preserve action field
   return issues.map((row, i) => {
     if (!row.title) throw new Error(`Issue at index ${i} is missing "title"`);
     if (!row.repo) throw new Error(`Issue "${row.title}" is missing "repo"`);
+
+    // Resolve action — default to 'create' if not specified or blank
+    const rawAction = (row.action ?? '').trim().toLowerCase();
+    const action = VALID_ACTIONS.includes(rawAction) ? rawAction : 'create';
+
     return {
+      action,
       repo: row.repo.trim(),
       title: row.title.trim(),
       body: row.body?.trim() ?? '',
@@ -48,4 +56,4 @@ export async function loadIssues(opts = {}) {
       track: row.track?.trim() ?? '',
     };
   });
-}
+}