jules-orchestrator-kit 0.3.0 → 0.5.1

package/scripts/jules-swarm.mjs

@@ -2,26 +2,27 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import fs from "node:fs";
 import path from "node:path";
+import { log, sleep } from "./utils.mjs";
 
 const execFileAsync = promisify(execFile);
 
 const tasksFile = process.argv[2];
 
 if (!tasksFile) {
-  console.error("Usage: node scripts/jules-swarm.mjs <path-to-tasks.json>");
-  console.error('Format of tasks.json: [ { "id": "t1", "title": "Task 1", "prompt": "Description 1", "scope": ["src/moduleA/**"] } ]');
+  log.error("Usage: node scripts/jules-swarm.mjs <path-to-tasks.json>");
+  log.error('Format of tasks.json: [ { "id": "t1", "title": "Task 1", "prompt": "Description 1", "scope": ["src/moduleA/**"] } ]');
   process.exit(1);
 }
 
 const resolvedPath = path.resolve(process.cwd(), tasksFile);
 if (!fs.existsSync(resolvedPath)) {
-  console.error(`❌ Tasks file not found: ${resolvedPath}`);
+  log.error(`Tasks file not found: ${resolvedPath}`);
   process.exit(1);
 }
 
 const tasks = JSON.parse(fs.readFileSync(resolvedPath, "utf-8"));
 if (!Array.isArray(tasks)) {
-  console.error("❌ tasks.json must contain a JSON array of task objects.");
+  log.error("tasks.json must contain a JSON array of task objects.");
   process.exit(1);
 }
 
@@ -36,7 +37,7 @@ const USE_WORKTREES = process.env.JULES_USE_WORKTREES === "true";
 // Ensure root project path is preserved for history logs even when running in worktrees
 process.env.JULES_PROJECT_ROOT = process.cwd();
 
-console.log(`🐝 Launching Jules Swarm Orchestrator (${tasks.length} tasks, Concurrency: ${MAX_CONCURRENT}, Worktrees: ${USE_WORKTREES ? "ENABLED" : "DISABLED"})...`);
+log.info(`Launching Jules Swarm Orchestrator (${tasks.length} tasks, Concurrency: ${MAX_CONCURRENT}, Worktrees: ${USE_WORKTREES ? "ENABLED" : "DISABLED"})...`);
 
 const activeWorktrees = new Set();
 
@@ -59,14 +60,35 @@ function cleanupAllWorktreesSync() {
   activeWorktrees.clear();
 }
 
+function reapOrphanedWorktrees() {
+  const worktreesBase = path.resolve(process.cwd(), ".agent/worktrees");
+  if (!fs.existsSync(worktreesBase)) return;
+  try {
+    const entries = fs.readdirSync(worktreesBase);
+    for (const entry of entries) {
+      const wtPath = path.join(worktreesBase, entry);
+      try {
+        execFileSync("git", ["worktree", "remove", "--force", wtPath], { stdio: "ignore" });
+      } catch (_) {
+        try {
+          fs.rmSync(wtPath, { recursive: true, force: true });
+        } catch (_) {}
+      }
+    }
+  } catch (_) {}
+  try {
+    execFileSync("git", ["worktree", "prune"], { stdio: "ignore" });
+  } catch (_) {}
+}
+
 process.on("SIGINT", () => {
-  console.warn("\n⚠️ SIGINT received. Cleaning up active Git worktrees...");
+  log.dim("SIGINT received. Cleaning up active Git worktrees...");
   cleanupAllWorktreesSync();
   process.exit(130);
 });
 
 process.on("SIGTERM", () => {
-  console.warn("\n⚠️ SIGTERM received. Cleaning up active Git worktrees...");
+  log.dim("SIGTERM received. Cleaning up active Git worktrees...");
   cleanupAllWorktreesSync();
   process.exit(143);
 });
@@ -76,19 +98,27 @@ async function createWorktree(taskId) {
   const wtDir = path.resolve(process.cwd(), `.agent/worktrees/${slug}`);
   const branchName = `jules/${slug}`;
   let item = null;
-  try {
-    if (!fs.existsSync(path.dirname(wtDir))) {
-      fs.mkdirSync(path.dirname(wtDir), { recursive: true });
-    }
-    await execFileAsync("git", ["worktree", "add", "-b", branchName, wtDir, "HEAD"]);
-    item = { wtDir, branchName };
-  } catch (err) {
+  await fs.promises.mkdir(path.dirname(wtDir), { recursive: true });
+
+  const maxRetries = 3;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
-      await execFileAsync("git", ["worktree", "add", "--force", wtDir, "HEAD"]);
-      item = { wtDir, branchName: null };
-    } catch (fallbackErr) {
-      console.warn(`⚠️ Failed to create worktree for ${taskId}:`, fallbackErr.message);
-      return null;
+      await execFileAsync("git", ["worktree", "add", "-b", branchName, wtDir, "HEAD"]);
+      item = { wtDir, branchName };
+      break;
+    } catch (err) {
+      if (attempt < maxRetries) {
+        const jitter = Math.floor(Math.random() * 200) + 100 * Math.pow(2, attempt);
+        await sleep(jitter);
+        continue;
+      }
+      try {
+        await execFileAsync("git", ["worktree", "add", "--force", wtDir, "HEAD"]);
+        item = { wtDir, branchName: null };
+      } catch (fallbackErr) {
+        log.error(`Failed to create worktree for ${taskId}: ${fallbackErr.message}`);
+        return null;
+      }
     }
   }
   if (item) activeWorktrees.add(item);
@@ -105,18 +135,21 @@ async function removeWorktree(wtDir, branchName) {
   try {
     await execFileAsync("git", ["worktree", "remove", "--force", wtDir]);
   } catch (err) {
-    console.warn(`⚠️ Failed to remove worktree at ${wtDir}:`, err.message);
+    log.error(`Failed to remove worktree at ${wtDir}: ${err.message}`);
   }
   if (branchName) {
     try {
       await execFileAsync("git", ["branch", "-D", branchName]);
     } catch (err) {
-      console.warn(`⚠️ Failed to delete swarm branch ${branchName}:`, err.message);
+      log.error(`Failed to delete swarm branch ${branchName}: ${err.message}`);
     }
   }
 }
 
 async function runSwarm() {
+  if (USE_WORKTREES) {
+    reapOrphanedWorktrees();
+  }
   const results = [];
   let hasFailure = false;
 
@@ -131,8 +164,7 @@ async function runSwarm() {
           await sleep(STAGGER_MS * bIdx);
         }
 
-        console.log(`\n----------------------------------------`);
-        console.log(`[${taskNum}/${tasks.length}] Dispatching Swarm Task: ${task.title} (${taskId})`);
+        log.step("======", `[${taskNum}/${tasks.length}] Dispatching Swarm Task: ${task.title} (${taskId})`);
 
         let wtInfo = null;
         let execCwd = process.cwd();
@@ -141,7 +173,7 @@ async function runSwarm() {
           wtInfo = await createWorktree(taskId);
           if (wtInfo?.wtDir) {
             execCwd = wtInfo.wtDir;
-            console.log(`🌲 Isolated Task ${taskId} in Git Worktree: ${wtInfo.wtDir}`);
+            log.info(`Isolated Task ${taskId} in Git Worktree: ${wtInfo.wtDir}`);
           }
         }
 
@@ -156,12 +188,17 @@ async function runSwarm() {
           const { stdout } = await execFileAsync("node", [dispatchScript, task.title, effectivePrompt], {
             cwd: execCwd,
             timeout: 15 * 60 * 1000,
-            env: { ...process.env, JULES_PROJECT_ROOT: process.env.JULES_PROJECT_ROOT },
+            env: {
+              ...process.env,
+              JULES_PROJECT_ROOT: process.env.JULES_PROJECT_ROOT,
+              JULES_SLOT_INDEX: String(bIdx + 1),
+              JULES_SLOT_TOTAL: String(batch.length)
+            },
           });
-          if (stdout) console.log(stdout.trim());
+          if (stdout) log.dim(stdout.trim());
           return { taskId, title: task.title, status: "SUCCESS" };
         } catch (error) {
-          console.error(`⚠️ Failed task [${task.title}]:`, error.message);
+          log.error(`Failed task [${task.title}]: ${error.message}`);
           return { taskId, title: task.title, status: "FAILED", error: error.message };
         } finally {
           if (wtInfo?.wtDir) {
@@ -182,15 +219,14 @@ async function runSwarm() {
     }
 
     if (i + MAX_CONCURRENT < tasks.length) {
-      console.log(`\n⏳ Batch finished. Cooling down for 2s before next batch...`);
+      log.info(`Batch finished. Cooling down for 2s before next batch...`);
       await sleep(2000);
     }
   }
 
-  console.log(`\n========================================`);
-  console.log(`🎉 Swarm Dispatch Summary (${results.length} tasks processed):`);
+  log.header(`Swarm Dispatch Summary (${results.length} tasks processed):`);
   results.forEach((res) => {
-    console.log(`  - [${res.status}] ${res.title}`);
+    log.info(`[${res.status}] ${res.title}`);
   });
 
   if (hasFailure) {
@@ -199,6 +235,6 @@ async function runSwarm() {
 }
 
 runSwarm().catch((err) => {
-  console.error("❌ Unhandled swarm rejection:", err);
+  log.error(`Unhandled swarm rejection: ${err.message}`);
   process.exit(1);
 });

package/scripts/lock-manager.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * lock-manager.mjs
+ * 
+ * Manages multi-agent file locks to prevent concurrent modification collisions.
+ * Uses .agent/sync-manifest.json as the lock registry.
+ * 
+ * Usage:
+ *   node scripts/lock-manager.mjs acquire <agent_name> <task_id> <file_path1> <file_path2> [--unattended]
+ *   node scripts/lock-manager.mjs release <task_id>
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const MANIFEST_PATH = path.join(process.cwd(), '.agent', 'sync-manifest.json');
+const TTL_MS = 20 * 60 * 1000; // 20 minutes
+
+async function readManifest() {
+  try {
+    const data = await fs.readFile(MANIFEST_PATH, 'utf-8');
+    return JSON.parse(data);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return {};
+    }
+    throw err;
+  }
+}
+
+async function writeManifest(manifest) {
+  await fs.mkdir(path.dirname(MANIFEST_PATH), { recursive: true });
+  await fs.writeFile(MANIFEST_PATH, JSON.stringify(manifest, null, 2), 'utf-8');
+}
+
+function cleanExpiredLocks(manifest) {
+  const now = Date.now();
+  let changed = false;
+  for (const [file, lock] of Object.entries(manifest)) {
+    if (lock.expiresAt < now) {
+      delete manifest[file];
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+async function acquireLocks(agentName, taskId, files) {
+  const manifest = await readManifest();
+  cleanExpiredLocks(manifest);
+  
+  const now = Date.now();
+  const expiresAt = now + TTL_MS;
+
+  const conflicts = [];
+  for (const file of files) {
+    const normalizedFile = path.normalize(file);
+    if (manifest[normalizedFile] && manifest[normalizedFile].taskId !== taskId) {
+      conflicts.push({
+        file: normalizedFile,
+        lockedBy: manifest[normalizedFile].agentName,
+        task: manifest[normalizedFile].taskId
+      });
+    }
+  }
+
+  if (conflicts.length > 0) {
+    console.error(`ERROR: Cannot acquire locks for task ${taskId}. Conflicts detected:`);
+    for (const conflict of conflicts) {
+      console.error(`  - ${conflict.file} is locked by ${conflict.lockedBy} (Task: ${conflict.task})`);
+    }
+    process.exit(1);
+  }
+
+  for (const file of files) {
+    const normalizedFile = path.normalize(file);
+    manifest[normalizedFile] = {
+      agentName,
+      taskId,
+      acquiredAt: now,
+      expiresAt
+    };
+  }
+
+  await writeManifest(manifest);
+  console.log(`SUCCESS: Acquired locks for task ${taskId} on ${files.length} files.`);
+}
+
+async function releaseLocks(taskId) {
+  const manifest = await readManifest();
+  let releasedCount = 0;
+  
+  for (const [file, lock] of Object.entries(manifest)) {
+    if (lock.taskId === taskId) {
+      delete manifest[file];
+      releasedCount++;
+    }
+  }
+
+  if (releasedCount > 0) {
+    await writeManifest(manifest);
+    console.log(`SUCCESS: Released ${releasedCount} locks for task ${taskId}.`);
+  } else {
+    console.log(`INFO: No locks found for task ${taskId}.`);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (command === 'acquire') {
+    const agentName = args[1];
+    const taskId = args[2];
+    const unattendedIndex = args.indexOf('--unattended');
+    
+    let files = [];
+    if (unattendedIndex !== -1) {
+       files = args.slice(3, unattendedIndex).concat(args.slice(unattendedIndex + 1));
+    } else {
+       files = args.slice(3);
+    }
+    
+    if (!agentName || !taskId || files.length === 0) {
+      console.error('Usage: acquire <agent_name> <task_id> <file_paths...>');
+      process.exit(1);
+    }
+    
+    await acquireLocks(agentName, taskId, files);
+  } else if (command === 'release') {
+    const taskId = args[1];
+    if (!taskId) {
+      console.error('Usage: release <task_id>');
+      process.exit(1);
+    }
+    await releaseLocks(taskId);
+  } else {
+    console.error('Unknown command. Use "acquire" or "release".');
+    process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error('Unhandled error:', err);
+  process.exit(1);
+});

package/scripts/utils.mjs

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+
+// ANSI colors for standardizing CLI DX
+const isCI = !!process.env.CI;
+const noColor = (!process.stdout.isTTY && !isCI) || process.env.NO_COLOR;
+const c = (color, text) => noColor ? text : `\x1b[${color}m${text}\x1b[0m`;
+
+export const log = {
+  info: (msg) => console.log(c(36, `ℹ️  ${msg}`)),
+  success: (msg) => console.log(c(32, `✅ ${msg}`)),
+  warn: (msg) => console.warn(c(33, `⚠️  ${msg}`)),
+  error: (msg) => {
+    if (isCI) console.log(`::error::${msg}`);
+    console.error(c(31, `❌ ${msg}`));
+  },
+  step: (stepStr, msg) => console.log(`${c(90, stepStr)} ${msg}`),
+  dim: (msg) => console.log(c(90, msg)),
+  header: (msg) => {
+    if (isCI) console.log(`::group::${msg}`);
+    console.log(`\n${c("1;35", `=== ${msg} ===`)}\n`);
+  },
+  groupEnd: () => {
+    if (isCI) console.log("::endgroup::");
+  }
+};
+
+export const sleep = promisify(setTimeout);
+
+export function ensureDir(dirPath) {
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+  } catch (error) {
+    log.error(`EACCES: Insufficient permissions or failed to create directory: ${dirPath}`);
+    log.error(error.message);
+    process.exit(1);
+  }
+}
+
+export function logToHistory(filename, content, type = "audit") {
+  const dateStr = new Date().toISOString().split("T")[0];
+  const historyDir = path.resolve(process.env.JULES_PROJECT_ROOT || process.cwd(), ".agent/history");
+  ensureDir(historyDir);
+  const filePath = path.join(historyDir, `${dateStr}-${filename}`);
+  fs.writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
+export function resolveMarkdownConflict(content) {
+  if (!content || typeof content !== "string") return "";
+  if (!content.includes("<<<<<<<")) return content;
+
+  const lines = content.split("\n");
+  const result = [];
+  let inConflict = false;
+  let headBuffer = [];
+  let devBuffer = [];
+  let section = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("<<<<<<<")) {
+      inConflict = true;
+      section = "head";
+      continue;
+    }
+    if (line.startsWith("=======")) {
+      section = "dev";
+      continue;
+    }
+    if (line.startsWith(">>>>>>>")) {
+      result.push(...headBuffer);
+      result.push(...devBuffer);
+      headBuffer = [];
+      devBuffer = [];
+      inConflict = false;
+      section = null;
+      continue;
+    }
+
+    if (inConflict) {
+      if (section === "head") headBuffer.push(line);
+      else if (section === "dev") devBuffer.push(line);
+    } else {
+      result.push(line);
+    }
+  }
+
+  return result.join("\n");
+}