feat(import): trello attachment upload + non-interactive import script

packages/import/.env.example

@@ -0,0 +1,12 @@
+# https://trello.com/app-key
+TRELLO_API_KEY=
+TRELLO_API_TOKEN=
+TRELLO_BOARD_ID=1yyR7LdA
+LINEAR_TEAM_ID=FON
+LINEAR_PROJECT_URL=https://linear.app/fontself/project/proj-d1563b5a7fed
+ATTACHMENT_CACHE_DIR=
+TRELLO_JSON_PATH=
+MAP_LISTS_TO_STATUSES=true
+DISCARD_ARCHIVED_CARDS=false
+DISCARD_ARCHIVED_LISTS=false
+LINEAR_API_KEY=lin_api_

packages/import/.gitignore

@@ -0,0 +1,15 @@
+# Runtime import state — do not commit
+.env
+import-progress.json
+.attachment-cache.json
+
+# Debug / scratch scripts
+debug-*.mjs
+test-*.mjs
+test-*.ts
+debug-*.ts
+exampleReplace.js
+
+# Scratch test files in importers
+src/importers/trelloJson/exampleReplace.js
+src/importers/trelloJson/test-trello-api.ts

packages/import/README.md

@@ -103,9 +103,59 @@ The following fields are supported:
 - `Description` - Trello markdown formatted description
 - `URL` - URL of Trello card
 - `Labels` - Added as a label
-- `Attachments` - Added as links in the description
+- `Attachments` - Downloaded from Trello and re-uploaded to Linear; URLs replaced in description
 - (Optional) `Comments` - Added in the description
 
+#### Non-interactive import (recommended)
+
+For large boards, use `run-trello-import.mjs` to bypass all interactive prompts.
+
+**Prerequisites:** build the SDK first:
+
+```bash
+cd packages/sdk && pnpm run build:sdk && cd ../..
+```
+
+**Setup:** create `packages/import/.env`:
+
+```
+LINEAR_API_KEY=lin_api_...
+TRELLO_API_KEY=...
+TRELLO_API_TOKEN=...
+LINEAR_TEAM_ID=FON                    # team key or UUID
+LINEAR_PROJECT_URL=https://linear.app/yourorg/project/project-name-slugid  # optional
+TRELLO_JSON_PATH=/path/to/board-export.json  # used by patch-trello-urls.mjs
+ATTACHMENT_CACHE_DIR=/path/to/attachments-cache  # used by patch-trello-urls.mjs
+MAP_LISTS_TO_STATUSES=true
+DISCARD_ARCHIVED_CARDS=false
+DISCARD_ARCHIVED_LISTS=false
+```
+
+Get Trello credentials at https://trello.com/app-key.
+
+**Run:**
+
+```bash
+cd packages/import
+
+# Preview (no data written)
+pnpm exec tsx run-trello-import.mjs /path/to/board-export.json --dry-run
+
+# Full import
+pnpm exec tsx run-trello-import.mjs /path/to/board-export.json
+```
+
+**Resume after interruption:** the script writes `import-progress.json` after each issue is created. Re-running will skip already-imported issues. Attachment files are cached in `attachments-cache/` next to the JSON export so they are not re-downloaded.
+
+**Patch existing issues:** if issues were created before attachment upload was working, use:
+
+```bash
+pnpm exec tsx patch-trello-urls.mjs --dry-run  # preview
+pnpm exec tsx patch-trello-urls.mjs            # apply
+```
+
+This script scans all issues in the target project for remaining Trello attachment URLs and replaces them with re-uploaded Linear asset URLs.
+
 ### Linear CSV
 
 Linear CSV exports (Settings → Import / Export → Export CSV) can be imported into Linear again. You can use this to import issues from one workspace to another. Archived issues won't be imported.
@@ -141,9 +191,11 @@ The following fields are supported:
 - `Time Estimate` - Issue estimate
 
 <!-- AUTO-GENERATED-CONTENT:START (TEXT_SECTION:id=license&src=../../README.md) -->
+
 ## License
 
 <br/>
 
 Licensed under the [MIT License](./LICENSE).
+
 <!-- AUTO-GENERATED-CONTENT:END -->

packages/import/TRELLO_API_SETUP.md

@@ -0,0 +1,124 @@
+# Trello API Setup & Testing Guide
+
+## 🔑 Step 1: Get Trello API Credentials
+
+### Generate API Key & Token
+
+1. Go to: **https://trello.com/app-key**
+2. Copy your **API Key** (long alphanumeric string)
+3. Scroll down and click **"Token"** link to generate a token
+4. Grant it **read** scope (minimum required)
+5. Copy the **Token** that appears
+
+### Get Board ID
+
+1. Open your Trello board in browser
+2. The URL looks like: `https://trello.com/b/BOARD_ID/board-name`
+3. Copy the `BOARD_ID` part
+
+## 🔧 Step 2: Create Environment File
+
+Create `.env` file in `packages/import/`:
+
+```bash
+cd packages/import/
+cat > .env << EOF
+TRELLO_API_KEY=your_api_key_here
+TRELLO_API_TOKEN=your_token_here
+TRELLO_BOARD_ID=your_board_id_here
+LINEAR_API_KEY=your_linear_key_here
+EOF
+```
+
+**Important:** Never commit `.env` to git (should be in `.gitignore`)
+
+## 🧪 Step 3: Run Dry-Run Test
+
+Test your credentials and preview what will be downloaded:
+
+```bash
+cd packages/import/
+npx ts-node src/importers/trelloJson/test-trello-api.ts
+```
+
+**Expected output:**
+
+```
+🔍 Trello API Test - Attachment Download
+
+Mode: DRY-RUN (no files downloaded)
+
+1️⃣  Testing API access...
+   ✅ Connected to board: "My Trello Board"
+
+2️⃣  Fetching board structure...
+   Found 5 lists (columns)
+   Found 42 total cards, 15 with attachments
+   Total attachments: 23
+
+3️⃣  Processing attachments...
+
+📋 [To Do] "Design homepage"
+  📎 wireframe.png
+     [dry-run] Would download from: https://trello.com/1/cards/...
+     [dry-run] Save to: attachments/To Do/Design homepage/wireframe.png
+...
+```
+
+## 📥 Step 4: Execute Real Download
+
+Once dry-run looks good, actually download files:
+
+```bash
+cd packages/import/
+npx ts-node src/importers/trelloJson/test-trello-api.ts --download
+```
+
+This creates the `attachments/` directory structure:
+
+```
+attachments/
+├── To Do/
+│   ├── Design homepage/
+│   │   ├── wireframe.png
+│   │   └── requirements.pdf
+├── In Progress/
+│   └── Build feature/
+│       └── screenshot.jpg
+```
+
+## 🐛 Troubleshooting
+
+### "401 Unauthorized"
+
+- API Key or Token is incorrect
+- Verify credentials at https://trello.com/app-key
+- Token may have expired (regenerate it)
+
+### "404 Not Found"
+
+- Board ID is incorrect
+- Copy it directly from your board URL
+
+### Network timeouts
+
+- Large file? Check your internet connection
+- Retry the command
+
+### "No attachments found"
+
+- Are there actually attachments on your board?
+- Check if they're in archived cards (won't be fetched by default)
+
+## ✅ Next Steps
+
+After successful dry-run and download:
+
+1. Run the full Trello import with attachment support (when ready)
+2. Check that `attachments/` directory was created correctly
+3. Run `exampleReplace.js` to upload files to Linear
+
+## 📚 References
+
+- **Trello API Guide:** https://developer.trello.com/reference
+- **Card Attachments:** https://developer.trello.com/reference/#card-object