tangled-sync / USAGE.md

# 🎉 Tangled Sync - Ready to Use!

## Summary of Changes

I've improved your Tangled Sync project to ensure proper AT Proto authentication and repository record creation. Here's what was updated:

### ✅ What's Fixed

1. **Enhanced AT Proto Login**
   - Added better error handling and validation
   - Shows DID and handle on successful login
   - Clearer error messages when authentication fails

2. **Corrected Repository Schema**
   - Fixed record structure to match `sh.tangled.repo` lexicon
   - Required fields (`name`, `knot`, `createdAt`) now ordered correctly
   - Optional fields properly marked as optional
   - Added better error handling for record creation

3. **Improved Logging**
   - More detailed startup information
   - Better progress tracking during sync
   - Shows AT Proto record URIs when created
   - Success/failure messages are clearer

### 📁 New Files Created

1. **`src/.env.example`** - Template for your configuration
2. **`src/test-atproto.ts`** - Test AT Proto connection before syncing
3. **`src/validate-config.ts`** - Validate your environment setup
4. **`SETUP.md`** - Comprehensive setup and troubleshooting guide

### 🚀 How to Use

#### Step 1: Configure Environment
```bash
# Copy the example file
cp src/.env.example src/.env

# Edit with your actual values
nano src/.env
```

You need:
- Your GitHub username
- Your AT Proto DID (from Bluesky settings)
- A Bluesky **app password** (not your main password!)
- Base directory for repos

#### Step 2: Validate Configuration
```bash
npm run validate
```

This checks all your environment variables are set correctly.

#### Step 3: Test AT Proto Connection
```bash
npm run test-atproto
```

This verifies:
- ✅ Your credentials work
- ✅ Your DID is correct
- ✅ You can access the PDS
- ✅ Shows any existing Tangled repo records

#### Step 4: Run the Sync
```bash
npm run sync
```

This will:
1. Login to AT Proto ✅
2. Fetch your GitHub repos
3. Clone them locally (if needed)
4. Add Tangled remotes
5. Push to Tangled
6. Update READMEs
7. Create AT Proto records for each repo ✅

### 🔍 What to Check

After running the sync, verify:

1. **AT Proto Records Created**
   ```bash
   npm run test-atproto
   ```
   Should show your repos listed

2. **Repos on Tangled**
   Visit: `https://tangled.org/YOUR_DID/REPO_NAME`

3. **Local Git Remotes**
   ```bash
   cd YOUR_BASE_DIR/some-repo
   git remote -v
   ```
   Should show both `origin` (GitHub) and `tangled` remotes

### 📊 Record Schema

Each repository creates a record with this structure:

```typescript
{
  $type: "sh.tangled.repo",
  name: "your-repo-name",           // required
  knot: "knot1.tangled.sh",         // required
  createdAt: "2024-01-01T00:00:00Z", // required
  description: "Repo description",   // optional
  source: "https://github.com/...", // optional
  labels: [],                        // optional
}
```

This matches the official `sh.tangled.repo` lexicon schema.

### ⚠️ Important Notes

1. **Use App Password**: Never use your main Bluesky password. Create an app password in Settings → App Passwords.

2. **Check Your DID**: Run `npm run test-atproto` first to ensure your DID in `.env` matches your actual account.

3. **SSH Key Required**: Make sure your SSH key is added to Tangled at https://tangled.org/settings/keys

4. **Rate Limits**: GitHub API has rate limits (60 req/hour unauthenticated). If you have many repos, consider adding GitHub auth.

### 🐛 Troubleshooting

**"Missing Bluesky credentials"**
- Check `src/.env` exists and has `BLUESKY_USERNAME` and `BLUESKY_PASSWORD`

**"Login failed"**
- Verify you're using an app password, not your main password
- Check username includes full handle (e.g., `you.bsky.social`)

**"Could not push to Tangled"**
- Verify SSH key is configured: `ssh [e-mail]`
- Check repo exists on Tangled

**"Failed to create ATProto record"**
- Run `npm run test-atproto` to check connection
- Verify your app password has write permissions

See `SETUP.md` for more detailed troubleshooting.

### 📚 Available Commands

```bash
npm run check         # Comprehensive health check (recommended first step!)
npm run validate      # Check environment configuration only
npm run test-atproto  # Test AT Proto connection only
npm run sync          # Run sync (only new repos without AT Proto records)
npm run sync:force    # Force sync all repos (including existing)
```

#### `npm run check` - Comprehensive Health Check

This is the **most useful command** for troubleshooting! It runs all checks in one go:

- ✅ Configuration validation
- ✅ AT Proto connection test
- ✅ SSH connection to Tangled
- ✅ GitHub API access
- ✅ Dependencies verification

**When to use:**
- Before your first sync
- When troubleshooting issues
- After changing configuration
- To verify everything is working

#### Individual Check Commands

**Normal sync** (recommended): Only processes repos that don't have AT Proto records yet. This is efficient and safe for regular use.

**Force sync**: Processes all repos regardless of whether they already have records. Use this if you need to:
- Re-push repos to Tangled
- Update READMEs for all repos
- Recover from a partial sync

### ✨ Next Steps

1. Copy and configure `src/.env`
2. Run `npm run validate` 
3. Run `npm run test-atproto`
4. Run `npm run sync`

That's it! Your GitHub repos will be synced to Tangled with proper AT Proto records.

---

**Questions?** Check `SETUP.md` for detailed instructions and troubleshooting.

**Happy syncing! 🚀**