@ewanc26/tangled-sync 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ewan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# Tangled Sync
+
+**Tangled Sync** is a TypeScript project that automates the process of syncing GitHub repositories to Tangled and publishing ATProto records for each repository. It is designed to streamline your workflow if you want your GitHub projects mirrored on Tangled while also maintaining structured metadata in ATProto.
+
+This tool is particularly useful for developers and organisations that want a decentralized or alternative hosting layer for their code repositories while keeping them discoverable via ATProto.
+
+---
+
+## Getting Started
+
+### Configuration
+
+Before running any scripts, you need to configure the project. Create a `src/.env` file based on `src/.env.example`:
+
+```bash
+cp src/.env.example src/.env
+```
+
+Then edit `src/.env` with your actual values:
+
+* `BASE_DIR` – the local directory where GitHub repositories will be cloned.
+* `GITHUB_USER` – your GitHub username or organisation.
+* `ATPROTO_DID` – your ATProto DID (Decentralized Identifier).
+* `BLUESKY_PDS` – the URL of your Bluesky PDS instance.
+* `BLUESKY_USERNAME` – your Bluesky username.
+* `BLUESKY_PASSWORD` – your Bluesky password.
+
+Make sure this file is properly set up before proceeding.
+
+---
+
+### Installation
+
+1. Clone this repository locally.
+2. Navigate to the project directory.
+3. Run:
+
+```bash
+npm install
+```
+
+This will install all dependencies required for syncing GitHub repositories and interacting with ATProto.
+
+---
+
+### Verify SSH Connection to Tangled
+
+* If the Tangled remote does not exist for a repository, the script will attempt to create it on first run. This requires a working SSH key associated with your account.
+
+Without proper SSH authentication, repository creation and pushing will fail.
+
+---
+
+### Testing AT Proto Connection
+
+**Before running the full sync**, test your AT Proto connection:
+
+```bash
+npm run test-atproto
+```
+
+This will:
+- Verify your Bluesky credentials
+- Confirm your DID matches the configuration
+- List any existing `sh.tangled.repo` records
+- Validate the connection to the PDS
+
+### Running the Sync Script
+
+Once configuration, SSH verification, and AT Proto testing are complete, run:
+
+```bash
+npm run sync
+```
+
+What happens during the sync:
+
+1. **Login to Bluesky:** The script authenticates using your credentials to allow publishing ATProto records.
+2. **Clone GitHub Repositories:** All repositories under your configured GitHub user are cloned locally (excluding a repository with the same name as your username to avoid recursion).
+3. **Ensure Tangled Remotes:** For each repository, a `tangled` remote is added if it doesn’t exist.
+4. **Push to Tangled:** The script pushes the `main` branch to Tangled. If your `origin` remote’s push URL points to Tangled, it will reset it back to GitHub.
+5. **Update README:** Each repository’s README is updated to include a link to its Tangled mirror, if it isn’t already present.
+6. **Create ATProto Records:** Each repository gets a structured record published in ATProto under your DID, including metadata like description, creation date, and source URL.
+
+---
+
+### Notes & Best Practices
+
+* **Directory Management:** The script ensures that your `BASE_DIR` exists and creates it if necessary.
+* **Record Uniqueness:** ATProto records use a time-based, sortable ID (TID) to ensure uniqueness. Duplicate IDs are avoided automatically.
+* **Error Handling:** If a repository cannot be pushed to Tangled, the script logs a warning but continues processing the remaining repositories.
+* **Idempotency:** Running the script multiple times is safe; existing remotes and ATProto records are checked before creation to prevent duplicates.
+
+---
+
+### Example Workflow
+
+```bash
+# Run the sync script
+npm run sync
+```
+
+After execution, you’ll see logs detailing which repositories were cloned, which remotes were added, which READMEs were updated, and which ATProto records were created.
+
+This allows you to quickly confirm that all GitHub repositories have been mirrored and documented properly on Tangled.
+
+---
+
+### Contribution & Development
+
+If you plan to contribute:
+
+* Ensure Node.js v18+ and npm v9+ are installed.
+* Test the script in a separate directory to avoid accidentally overwriting your production repositories.
+* Use `console.log` statements to debug or track progress during development.
+* Maintain proper `.env` configuration to avoid leaking credentials.
+
+---
+
+**Tangled Sync** bridges GitHub and Tangled efficiently, providing automatic mirroring, record management, and easy discoverability. Following these steps will ensure a smooth, automated workflow for syncing and publishing your repositories.
+
+## ☕ Support
+
+If you found this useful, consider [buying me a ko-fi](https://ko-fi.com/ewancroft)!

package/USAGE.md

@@ -0,0 +1,197 @@
+# 🎉 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 git@tangled.sh`
+- 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! 🚀**

package/dist/check.js

@@ -0,0 +1,209 @@
+// src/check.ts
+import { AtpAgent } from "@atproto/api";
+import dotenv from "dotenv";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { execSync } from "child_process";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+dotenv.config();
+async function runHealthCheck() {
+  console.log("\u{1F50D} Running Tangled Sync Health Check...\n");
+  const checks = [];
+  let errors = 0;
+  let warnings = 0;
+  console.log("\u{1F4CB} Configuration Checks\n");
+  const envPath = path.join(__dirname, ".env");
+  const envExists = fs.existsSync(envPath);
+  checks.push({
+    category: "config",
+    name: ".env file",
+    status: envExists,
+    message: envExists ? "Found at src/.env" : "Missing! Copy src/.env.example to src/.env"
+  });
+  if (!envExists) errors++;
+  const requiredVars = [
+    { name: "BASE_DIR", description: "Base directory for repos" },
+    { name: "GITHUB_USER", description: "GitHub username" },
+    { name: "ATPROTO_DID", description: "AT Proto DID" },
+    { name: "BLUESKY_PDS", description: "Bluesky PDS URL" },
+    { name: "BLUESKY_USERNAME", description: "Bluesky username" },
+    { name: "BLUESKY_PASSWORD", description: "Bluesky app password" }
+  ];
+  requiredVars.forEach(({ name, description }) => {
+    const value = process.env[name];
+    const exists = !!value && value.trim().length > 0;
+    checks.push({
+      category: "config",
+      name,
+      status: exists,
+      message: exists ? `Set` : `Missing (${description})`
+    });
+    if (!exists) errors++;
+  });
+  const baseDir = process.env.BASE_DIR;
+  if (baseDir) {
+    const baseDirExists = fs.existsSync(baseDir);
+    checks.push({
+      category: "config",
+      name: "BASE_DIR path",
+      status: baseDirExists,
+      message: baseDirExists ? `Exists: ${baseDir}` : `Missing (will be created): ${baseDir}`
+    });
+    if (!baseDirExists) warnings++;
+  }
+  const did = process.env.ATPROTO_DID;
+  if (did) {
+    const validDid = did.startsWith("did:plc:") || did.startsWith("did:web:");
+    checks.push({
+      category: "config",
+      name: "DID format",
+      status: validDid,
+      message: validDid ? "Valid" : "Invalid! Should start with 'did:plc:' or 'did:web:'"
+    });
+    if (!validDid) errors++;
+  }
+  const pds = process.env.BLUESKY_PDS;
+  if (pds) {
+    const validPds = pds.startsWith("http://") || pds.startsWith("https://");
+    checks.push({
+      category: "config",
+      name: "PDS URL",
+      status: validPds,
+      message: validPds ? pds : "Invalid! Should start with 'https://'"
+    });
+    if (!validPds) errors++;
+  }
+  checks.filter((c) => c.category === "config").forEach((check) => {
+    const icon = check.status ? "\u2705" : "\u274C";
+    console.log(`${icon} ${check.name}: ${check.message}`);
+  });
+  console.log("\n\u{1F510} AT Proto Connection Check\n");
+  const canTestConnection = process.env.BLUESKY_USERNAME && process.env.BLUESKY_PASSWORD && process.env.BLUESKY_PDS && process.env.ATPROTO_DID;
+  if (canTestConnection) {
+    try {
+      const agent = new AtpAgent({ service: process.env.BLUESKY_PDS });
+      const loginResponse = await agent.login({
+        identifier: process.env.BLUESKY_USERNAME,
+        password: process.env.BLUESKY_PASSWORD
+      });
+      console.log(`\u2705 Login successful`);
+      console.log(`   DID: ${loginResponse.data.did}`);
+      console.log(`   Handle: ${loginResponse.data.handle}`);
+      if (loginResponse.data.did !== process.env.ATPROTO_DID) {
+        console.log(`\u26A0\uFE0F  DID mismatch!`);
+        console.log(`   Expected: ${process.env.ATPROTO_DID}`);
+        console.log(`   Got: ${loginResponse.data.did}`);
+        warnings++;
+      }
+      const records = await agent.api.com.atproto.repo.listRecords({
+        repo: loginResponse.data.did,
+        collection: "sh.tangled.repo",
+        limit: 5
+      });
+      console.log(`\u2705 Can access AT Proto records`);
+      console.log(`   Found ${records.data.records.length} sample records`);
+    } catch (error) {
+      console.log(`\u274C AT Proto connection failed`);
+      console.log(`   Error: ${error.message}`);
+      errors++;
+    }
+  } else {
+    console.log("\u23ED\uFE0F  Skipped (missing credentials)");
+  }
+  console.log("\n\u{1F511} SSH Connection Check\n");
+  try {
+    const sshTest = execSync("ssh -T git@tangled.sh 2>&1", {
+      encoding: "utf-8",
+      timeout: 5e3
+    });
+    if (sshTest.includes("successfully authenticated") || sshTest.includes("Hi")) {
+      console.log("\u2705 SSH connection to Tangled works");
+      console.log(`   ${sshTest.trim().split("\n")[0]}`);
+    } else {
+      console.log("\u26A0\uFE0F  SSH connection uncertain");
+      console.log(`   Response: ${sshTest.trim()}`);
+      warnings++;
+    }
+  } catch (error) {
+    const output = error.stdout?.toString() || error.message;
+    if (output.includes("successfully authenticated") || output.includes("Hi")) {
+      console.log("\u2705 SSH connection to Tangled works");
+    } else {
+      console.log("\u274C SSH connection to Tangled failed");
+      console.log("   Make sure your SSH key is added at https://tangled.org/settings/keys");
+      errors++;
+    }
+  }
+  console.log("\n\u{1F419} GitHub API Check\n");
+  if (process.env.GITHUB_USER) {
+    try {
+      const response = execSync(`curl -s "https://api.github.com/users/${process.env.GITHUB_USER}"`, {
+        encoding: "utf-8",
+        timeout: 5e3
+      });
+      const data = JSON.parse(response);
+      if (data.login) {
+        console.log(`\u2705 GitHub user found: ${data.login}`);
+        console.log(`   Public repos: ${data.public_repos || 0}`);
+      } else {
+        console.log(`\u274C GitHub user not found: ${process.env.GITHUB_USER}`);
+        errors++;
+      }
+    } catch (error) {
+      console.log(`\u26A0\uFE0F  Could not check GitHub API`);
+      console.log(`   ${error.message}`);
+      warnings++;
+    }
+  } else {
+    console.log("\u23ED\uFE0F  Skipped (no GITHUB_USER set)");
+  }
+  console.log("\n\u{1F4E6} Dependencies Check\n");
+  let hasAtproto = false;
+  let hasDotenv = false;
+  try {
+    await import("@atproto/api");
+    hasAtproto = true;
+    console.log("\u2705 @atproto/api installed");
+  } catch {
+    console.log("\u274C @atproto/api not installed (run: npm install)");
+    errors++;
+  }
+  try {
+    await import("dotenv");
+    hasDotenv = true;
+    console.log("\u2705 dotenv installed");
+  } catch {
+    console.log("\u274C dotenv not installed (run: npm install)");
+    errors++;
+  }
+  console.log("\n" + "=".repeat(50));
+  if (errors === 0 && warnings === 0) {
+    console.log("\u2705 All checks passed! Ready to sync.");
+    console.log("\nNext steps:");
+    console.log("  npm run sync       # Sync new repos only");
+    console.log("  npm run sync:force # Force sync all repos");
+  } else {
+    if (errors > 0) {
+      console.log(`\u274C ${errors} error(s) found - please fix before syncing`);
+    }
+    if (warnings > 0) {
+      console.log(`\u26A0\uFE0F  ${warnings} warning(s) - review before syncing`);
+    }
+    console.log("\nSee SETUP.md for detailed troubleshooting");
+    if (errors > 0) {
+      process.exit(1);
+    }
+  }
+  console.log("=".repeat(50));
+  if (process.env.BLUESKY_PASSWORD && !process.env.BLUESKY_PASSWORD.includes("-")) {
+    console.log("\n\u{1F4A1} Tip: Your password might be a regular password.");
+    console.log("   Consider using an App Password from Bluesky settings for better security.");
+  }
+}
+runHealthCheck().catch((error) => {
+  console.error("\n\u274C Health check failed with error:");
+  console.error(error);
+  process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,247 @@
+// src/index.ts
+import { AtpAgent } from "@atproto/api";
+import dotenv from "dotenv";
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+dotenv.config();
+var FORCE_SYNC = process.argv.includes("--force");
+var BASE_DIR = process.env.BASE_DIR;
+var GITHUB_USER = process.env.GITHUB_USER;
+var ATPROTO_DID = process.env.ATPROTO_DID;
+var BLUESKY_PDS = process.env.BLUESKY_PDS;
+var TANGLED_BASE_URL = `git@tangled.sh:${ATPROTO_DID}`;
+var agent = new AtpAgent({ service: BLUESKY_PDS });
+async function login() {
+  const username = process.env.BLUESKY_USERNAME;
+  const password = process.env.BLUESKY_PASSWORD;
+  if (!username || !password) {
+    throw new Error("Missing Bluesky credentials. Please set BLUESKY_USERNAME and BLUESKY_PASSWORD in src/.env");
+  }
+  try {
+    const response = await agent.login({ identifier: username, password });
+    console.log(`[LOGIN] Successfully logged in to AT Proto as ${response.data.did}`);
+    console.log(`[LOGIN] Session handle: ${response.data.handle}`);
+    return response;
+  } catch (error) {
+    console.error("[ERROR] Failed to login to AT Proto:", error.message);
+    throw error;
+  }
+}
+async function getGitHubRepos() {
+  const curl = `curl -s "https://api.github.com/users/${GITHUB_USER}/repos?per_page=200"`;
+  const output = run(curl);
+  const json = JSON.parse(output);
+  return json.filter((r) => r.name !== GITHUB_USER).map((r) => ({ clone_url: r.clone_url, name: r.name, description: r.description }));
+}
+async function ensureTangledRemoteAndPush(repoDir, repoName, cloneUrl) {
+  const tangledUrl = `${TANGLED_BASE_URL}/${repoName}`;
+  try {
+    const remotes = run("git remote", repoDir).split("\n");
+    if (!remotes.includes("tangled")) {
+      console.log(`[REMOTE] Adding Tangled remote for ${repoName}`);
+      run(`git remote add tangled ${tangledUrl}`, repoDir);
+    }
+    const originPushUrl = run("git remote get-url --push origin", repoDir);
+    if (originPushUrl.includes("tangled.sh")) {
+      run(`git remote set-url --push origin ${cloneUrl}`, repoDir);
+      console.log(`[REMOTE] Reset origin push URL to GitHub`);
+    }
+    run(`git push tangled main`, repoDir);
+    console.log(`[PUSH] Pushed main to Tangled`);
+  } catch (error) {
+    console.warn(`[WARN] Could not push ${repoName} to Tangled. Check SSH or repo existence.`);
+  }
+}
+var BASE32_SORTABLE = "234567abcdefghijklmnopqrstuvwxyz";
+function run(cmd, cwd) {
+  const options = {
+    cwd,
+    stdio: "pipe",
+    shell: process.env.SHELL || "/bin/bash",
+    encoding: "utf-8"
+  };
+  return execSync(cmd, options).toString().trim();
+}
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+function generateClockId() {
+  return Math.floor(Math.random() * 1024);
+}
+function toBase32Sortable(num) {
+  if (num === 0n) return "2222222222222";
+  let result = "";
+  while (num > 0n) {
+    result = BASE32_SORTABLE[Number(num % 32n)] + result;
+    num = num / 32n;
+  }
+  return result.padStart(13, "2");
+}
+function generateTid() {
+  const nowMicroseconds = BigInt(Date.now()) * 1000n;
+  const clockId = generateClockId();
+  const tidBigInt = nowMicroseconds << 10n | BigInt(clockId);
+  return toBase32Sortable(tidBigInt);
+}
+var recordCache = {};
+async function ensureTangledRecord(agent2, atprotoDid, githubUser, repoName, description) {
+  if (recordCache[repoName]) {
+    return { tid: recordCache[repoName], existed: true };
+  }
+  let cursor = void 0;
+  let tid = null;
+  do {
+    const res = await agent2.api.com.atproto.repo.listRecords({
+      repo: atprotoDid,
+      collection: "sh.tangled.repo",
+      limit: 50,
+      cursor
+    });
+    for (const record of res.data.records) {
+      const value = record.value;
+      if (value.name === repoName && record.rkey) {
+        tid = record.rkey;
+        recordCache[repoName] = tid;
+        console.log(`[FOUND] Existing record for ${repoName} (TID: ${tid})`);
+        return { tid, existed: true };
+      }
+    }
+    cursor = res.data.cursor;
+  } while (!tid && cursor);
+  if (!tid) {
+    tid = generateTid();
+    const record = {
+      $type: "sh.tangled.repo",
+      name: repoName,
+      knot: "knot1.tangled.sh",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      description: description ?? repoName,
+      source: `https://github.com/${githubUser}/${repoName}`,
+      labels: []
+    };
+    try {
+      const result = await agent2.api.com.atproto.repo.putRecord({
+        repo: atprotoDid,
+        collection: "sh.tangled.repo",
+        rkey: tid,
+        record
+      });
+      console.log(`[CREATED] ATProto record URI: ${result.data.uri}`);
+    } catch (error) {
+      console.error(`[ERROR] Failed to create ATProto record for ${repoName}:`, error.message);
+      throw error;
+    }
+    recordCache[repoName] = tid;
+    console.log(`[CREATED] Tangled record for ${repoName} (TID: ${tid})`);
+    return { tid, existed: false };
+  }
+  return { tid, existed: false };
+}
+function updateReadme(baseDir, repoName, atprotoDid) {
+  const repoDir = path.join(baseDir, repoName);
+  const readmeFiles = ["README.md", "README.MD", "README.txt", "README"];
+  const readmeFile = readmeFiles.find((f) => fs.existsSync(path.join(repoDir, f)));
+  if (!readmeFile) return;
+  const readmePath = path.join(repoDir, readmeFile);
+  const content = fs.readFileSync(readmePath, "utf-8");
+  if (!/tangled\.org/i.test(content)) {
+    fs.appendFileSync(
+      readmePath,
+      `
+Mirrored on Tangled: https://tangled.org/${atprotoDid}/${repoName}
+`
+    );
+    run(`git add ${readmeFile}`, repoDir);
+    run(`git commit -m "Add Tangled mirror reference to README"`, repoDir);
+    run(`git push origin main`, repoDir);
+    console.log(`[README] Updated for ${repoName}`);
+  }
+}
+async function main() {
+  console.log("[STARTUP] Starting Tangled Sync...");
+  if (FORCE_SYNC) {
+    console.log("[MODE] Force sync enabled - will process all repos");
+  }
+  console.log(`[CONFIG] Base directory: ${BASE_DIR}`);
+  console.log(`[CONFIG] GitHub user: ${GITHUB_USER}`);
+  console.log(`[CONFIG] ATProto DID: ${ATPROTO_DID}`);
+  console.log(`[CONFIG] PDS: ${BLUESKY_PDS}`);
+  await login();
+  ensureDir(BASE_DIR);
+  console.log(`[GITHUB] Fetching repositories for ${GITHUB_USER}...`);
+  const repos = await getGitHubRepos();
+  console.log(`[GITHUB] Found ${repos.length} repositories`);
+  let reposToProcess = repos;
+  let skippedRepos = [];
+  if (!FORCE_SYNC) {
+    console.log(`[ATPROTO] Fetching existing Tangled records...`);
+    let cursor = void 0;
+    const existingRepos = /* @__PURE__ */ new Set();
+    do {
+      const res = await agent.api.com.atproto.repo.listRecords({
+        repo: ATPROTO_DID,
+        collection: "sh.tangled.repo",
+        limit: 100,
+        cursor
+      });
+      for (const record of res.data.records) {
+        const value = record.value;
+        if (value.name) {
+          existingRepos.add(value.name);
+          recordCache[value.name] = record.rkey;
+        }
+      }
+      cursor = res.data.cursor;
+    } while (cursor);
+    console.log(`[ATPROTO] Found ${existingRepos.size} existing Tangled records`);
+    reposToProcess = repos.filter((r) => !existingRepos.has(r.name));
+    skippedRepos = repos.filter((r) => existingRepos.has(r.name));
+    console.log(`[INFO] ${reposToProcess.length} new repos to sync`);
+    console.log(`[INFO] ${skippedRepos.length} repos already synced (skipping)
+`);
+    if (skippedRepos.length > 0) {
+      console.log("[SKIPPED] The following repos already have AT Proto records:");
+      skippedRepos.forEach((r) => console.log(`  - ${r.name}`));
+      console.log("");
+    }
+  } else {
+    console.log("[INFO] Processing all ${repos.length} repos (force sync mode)\n");
+  }
+  let syncedCount = 0;
+  let errorCount = 0;
+  for (const { clone_url, name: repoName, description } of reposToProcess) {
+    console.log(`
+[PROGRESS] Processing ${repoName} (${syncedCount + 1}/${reposToProcess.length})`);
+    const repoDir = path.join(BASE_DIR, repoName);
+    try {
+      if (!fs.existsSync(repoDir)) {
+        run(`git clone ${clone_url} ${repoDir}`);
+        console.log(`[CLONE] ${repoName}`);
+      } else {
+        console.log(`[EXISTS] ${repoName} already cloned`);
+      }
+      await ensureTangledRemoteAndPush(repoDir, repoName, clone_url);
+      updateReadme(BASE_DIR, repoName, ATPROTO_DID);
+      const result = await ensureTangledRecord(agent, ATPROTO_DID, GITHUB_USER, repoName, description);
+      if (!result.existed) {
+        syncedCount++;
+      }
+    } catch (error) {
+      console.error(`[ERROR] Failed to sync ${repoName}: ${error.message}`);
+      errorCount++;
+    }
+  }
+  console.log(`
+${"=".repeat(50)}`);
+  console.log(`[COMPLETE] Sync finished!`);
+  console.log(`  \u2705 New repos synced: ${syncedCount}`);
+  if (!FORCE_SYNC) {
+    console.log(`  \u23ED\uFE0F  Repos skipped: ${skippedRepos.length}`);
+  }
+  if (errorCount > 0) {
+    console.log(`  \u274C Errors: ${errorCount}`);
+  }
+  console.log(`${"=".repeat(50)}`);
+}
+main().catch(console.error);

package/dist/test-atproto.js

@@ -0,0 +1,58 @@
+// src/test-atproto.ts
+import { AtpAgent } from "@atproto/api";
+import dotenv from "dotenv";
+dotenv.config();
+async function testAtProtoConnection() {
+  console.log("Testing AT Proto Connection...\n");
+  const service = process.env.BLUESKY_PDS || "https://bsky.social";
+  const username = process.env.BLUESKY_USERNAME;
+  const password = process.env.BLUESKY_PASSWORD;
+  const atprotoDid = process.env.ATPROTO_DID;
+  console.log(`Service: ${service}`);
+  console.log(`Username: ${username}`);
+  console.log(`Expected DID: ${atprotoDid}
+`);
+  if (!username || !password) {
+    console.error("ERROR: Missing BLUESKY_USERNAME or BLUESKY_PASSWORD");
+    process.exit(1);
+  }
+  const agent = new AtpAgent({ service });
+  try {
+    console.log("Attempting login...");
+    const loginResponse = await agent.login({
+      identifier: username,
+      password
+    });
+    console.log("\u2713 Login successful!");
+    console.log(`  DID: ${loginResponse.data.did}`);
+    console.log(`  Handle: ${loginResponse.data.handle}`);
+    console.log(`  Email: ${loginResponse.data.email || "N/A"}`);
+    if (loginResponse.data.did !== atprotoDid) {
+      console.warn(`
+\u26A0 WARNING: Logged in DID (${loginResponse.data.did}) does not match ATPROTO_DID in .env (${atprotoDid})`);
+      console.warn("  Please update your ATPROTO_DID in src/.env");
+    }
+    console.log("\nFetching existing sh.tangled.repo records...");
+    const records = await agent.api.com.atproto.repo.listRecords({
+      repo: loginResponse.data.did,
+      collection: "sh.tangled.repo",
+      limit: 10
+    });
+    console.log(`\u2713 Found ${records.data.records.length} existing Tangled repo records`);
+    if (records.data.records.length > 0) {
+      console.log("\nSample records:");
+      records.data.records.slice(0, 3).forEach((record) => {
+        console.log(`  - ${record.value.name} (${record.uri})`);
+      });
+    }
+    console.log("\n\u2713 AT Proto connection test completed successfully!");
+  } catch (error) {
+    console.error("\n\u2717 AT Proto connection test failed!");
+    console.error(`Error: ${error.message}`);
+    if (error.status) {
+      console.error(`HTTP Status: ${error.status}`);
+    }
+    process.exit(1);
+  }
+}
+testAtProtoConnection();

package/dist/validate-config.js

@@ -0,0 +1,86 @@
+// src/validate-config.ts
+import dotenv from "dotenv";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+dotenv.config();
+console.log("\u{1F50D} Validating Tangled Sync Configuration...\n");
+var checks = [];
+var envPath = path.join(__dirname, ".env");
+var envExists = fs.existsSync(envPath);
+checks.push({
+  name: ".env file",
+  status: envExists,
+  message: envExists ? "Found at src/.env" : "Missing! Copy src/.env.example to src/.env"
+});
+var requiredVars = [
+  { name: "BASE_DIR", description: "Base directory for repos" },
+  { name: "GITHUB_USER", description: "GitHub username" },
+  { name: "ATPROTO_DID", description: "AT Proto DID" },
+  { name: "BLUESKY_PDS", description: "Bluesky PDS URL" },
+  { name: "BLUESKY_USERNAME", description: "Bluesky username" },
+  { name: "BLUESKY_PASSWORD", description: "Bluesky app password" }
+];
+requiredVars.forEach(({ name, description }) => {
+  const value = process.env[name];
+  const exists = !!value && value.trim().length > 0;
+  checks.push({
+    name: `${name}`,
+    status: exists,
+    message: exists ? `\u2713 Set (${description})` : `\u2717 Missing (${description})`
+  });
+});
+var baseDir = process.env.BASE_DIR;
+if (baseDir) {
+  const baseDirExists = fs.existsSync(baseDir);
+  checks.push({
+    name: "BASE_DIR exists",
+    status: baseDirExists,
+    message: baseDirExists ? `Directory exists: ${baseDir}` : `Directory missing: ${baseDir} (will be created)`
+  });
+}
+var did = process.env.ATPROTO_DID;
+if (did) {
+  const validDid = did.startsWith("did:plc:") || did.startsWith("did:web:");
+  checks.push({
+    name: "DID format",
+    status: validDid,
+    message: validDid ? "Valid DID format" : "Invalid! Should start with 'did:plc:' or 'did:web:'"
+  });
+}
+var pds = process.env.BLUESKY_PDS;
+if (pds) {
+  const validPds = pds.startsWith("http://") || pds.startsWith("https://");
+  checks.push({
+    name: "PDS URL format",
+    status: validPds,
+    message: validPds ? `Valid URL: ${pds}` : "Invalid! Should start with 'https://'"
+  });
+}
+console.log("Configuration Check Results:\n");
+var allPassed = true;
+checks.forEach((check) => {
+  const icon = check.status ? "\u2705" : "\u274C";
+  console.log(`${icon} ${check.name}: ${check.message}`);
+  if (!check.status) allPassed = false;
+});
+console.log("\n" + "=".repeat(50) + "\n");
+if (allPassed) {
+  console.log("\u2705 All checks passed! You're ready to run:");
+  console.log("   npm run test-atproto  # Test AT Proto connection");
+  console.log("   npm run sync          # Run the full sync");
+} else {
+  console.log("\u274C Some checks failed. Please fix the issues above.");
+  console.log("   See SETUP.md for detailed instructions.");
+  process.exit(1);
+}
+console.log("\n\u{1F4A1} Recommendations:");
+if (process.env.BLUESKY_PASSWORD && !process.env.BLUESKY_PASSWORD.includes("-")) {
+  console.log("   \u26A0\uFE0F  Your password looks like it might be a regular password.");
+  console.log("      Consider using an App Password from Bluesky settings.");
+}
+console.log("   \u{1F4DA} Read SETUP.md for detailed setup instructions");
+console.log("   \u{1F510} Never commit your .env file to version control");
+console.log("   \u{1F511} Make sure your SSH key is added to Tangled");

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ewanc26/tangled-sync",
+  "version": "1.0.0",
+  "description": "Sync GitHub repos to Tangled with ATProto records",
+  "type": "module",
+  "bin": {
+    "tangled-sync": "./dist/index.js",
+    "tangled-sync-check": "./dist/check.js",
+    "tangled-sync-validate": "./dist/validate-config.js",
+    "tangled-sync-test-atproto": "./dist/test-atproto.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "USAGE.md"
+  ],
+  "dependencies": {
+    "@atproto/api": "^0.17.2",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  },
+  "author": "Ewan Croft",
+  "license": "AGPL-3.0-only",
+  "scripts": {
+    "build": "tsup src/index.ts src/check.ts src/validate-config.ts src/test-atproto.ts --format esm --outDir dist --no-dts --clean",
+    "dev": "ts-node src/index.ts",
+    "check": "ts-node src/check.ts",
+    "validate": "ts-node src/validate-config.ts",
+    "test-atproto": "ts-node src/test-atproto.ts",
+    "sync": "ts-node src/index.ts",
+    "sync:force": "ts-node src/index.ts --force",
+    "type-check": "tsc --noEmit"
+  }
+}