jules-orchestrator-kit 0.3.0 → 0.5.1

package/bin/init.js

@@ -5,6 +5,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import readline from "node:readline/promises";
+import zlib from "node:zlib";
+import crypto from "node:crypto";
 import { resolveProjectCommands } from "../scripts/command-resolver.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -57,10 +59,13 @@ if (isForce) console.log("⚠️ Force mode enabled (existing files will be over
 let answerRepoVal = "";
 let answerBranchVal = "";
 
-// Dual TTY Interactive Wizard
 if (process.stdin.isTTY && (isInteractive || (!fs.existsSync(path.join(targetDir, ".agent/jules.yml")) && !process.env.CI))) {
   try {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.on('SIGINT', () => {
+      console.log("\n🛑 Initialization aborted by user.");
+      process.exit(130);
+    });
     const answerRepo = await rl.question("📦 Enter target GitHub repository (e.g. owner/repo) [optional]: ");
     if (answerRepo.trim()) {
       answerRepoVal = answerRepo.trim();
@@ -73,6 +78,10 @@ if (process.stdin.isTTY && (isInteractive || (!fs.existsSync(path.join(targetDir
     }
     rl.close();
   } catch (err) {
+    if (err.name === 'AbortError') {
+      console.log("\n🛑 Initialization aborted by user.");
+      process.exit(130);
+    }
     console.warn("⚠️ Interactive setup prompt failed:", err.message);
   }
 }
@@ -181,7 +190,7 @@ if (fs.existsSync(auditWfSource)) {
   }
   if (!fs.existsSync(auditWfTarget) || isForce) {
     fs.copyFileSync(auditWfSource, auditWfTarget);
-    console.log("✅ Scaffolded CI Audit Workflow: .github/workflows/jules-audit.yml");
+    console.log("✅ Added GitHub Actions workflow: .github/workflows/jules-audit.yml");
   }
 }
 
@@ -225,6 +234,8 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
     const julesScripts = {
       "jules:dispatch": "node scripts/jules-dispatch.mjs",
       "jules:queue": "node scripts/jules-queue-runner.mjs",
+      "jules:create": "node scripts/jules-create.mjs",
+      "jules:status": "node scripts/jules-status.mjs",
       "jules:audit": "node scripts/jules-self-audit.mjs",
       "jules:swarm": "node scripts/jules-swarm.mjs",
       "jules:nightly": "node scripts/jules-nightly.mjs"
@@ -239,7 +250,7 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
 
     if (updated) {
       fs.writeFileSync(targetPkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
-      console.log("✅ Injected jules:* helper scripts into package.json");
+      console.log("✅ Added Jules commands to package.json");
     }
   } catch (err) {
     console.warn("⚠️ Failed to inject helper scripts into target package.json:", err.message);
@@ -247,7 +258,55 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
 }
 
 console.log("\n🎉 Google Jules Orchestration Kit successfully initialized!");
+
+// 6. Generate Cryptographic Handshake (JULES_WEB_SETUP.md)
+const agentState = {
+  v: 1,
+  schema: "jules.init/v1",
+  generatedAt: new Date().toISOString(),
+  repo: {
+    name: answerRepoVal || process.env.JULES_REPO || "unknown/repo",
+    branch: answerBranchVal || process.env.BASE_BRANCH || "main"
+  },
+  workspace: {
+    testCmd: detected.testCmd || "",
+    buildCmd: detected.buildCmd || "",
+    source: detected.source || "unknown"
+  }
+};
+
+const canonicalJson = JSON.stringify(agentState);
+const hash = crypto.createHash("sha256").update(canonicalJson, "utf8").digest("hex");
+const compressed = zlib.brotliCompressSync(Buffer.from(canonicalJson, "utf8"));
+const payloadToken = `JULES1.${hash}.${compressed.toString("base64url")}`;
+
+const setupMdContent = `# JULES Web Setup
+
+> **Generated**: ${agentState.generatedAt}
+> **Setup Code**: \`${payloadToken}\`
+
+## 🔗 Web Dashboard Setup
+1. Open Jules Web UI (https://app.jules.ai/setup)
+2. Paste your Setup Code:
+\`\`\`
+${payloadToken}
+\`\`\`
+
+## 🔧 Detected Configuration
+* Test Command: \`${agentState.workspace.testCmd}\`
+* Build Command: \`${agentState.workspace.buildCmd}\`
+* Source: \`${agentState.workspace.source}\`
+`;
+
+fs.writeFileSync(path.join(targetDir, ".agent", "JULES_WEB_SETUP.md"), setupMdContent, "utf-8");
+
+console.log("\n🔗 Web Dashboard Setup");
+console.log("  Your local agent configurations are ready.");
+console.log(`  👉 Setup Code: \x1b[36m${payloadToken}\x1b[0m`);
+console.log("\n  (A backup of this setup code was written to .agent/JULES_WEB_SETUP.md)");
 console.log("\nNext Steps:");
-console.log("  1. Set environment variables: JULES_REPO=\"owner/repo\"");
-console.log("  2. Dispatch your first task:  node scripts/jules-dispatch.mjs \"Task Title\" \"Task prompt\"");
-console.log("  3. Run pre-merge PR audit:    node scripts/jules-self-audit.mjs\n");
+console.log("  1. Paste the Setup Code into Jules Web UI.");
+console.log("  2. Set environment variables: JULES_REPO=\"owner/repo\"");
+console.log("  3. Scaffold a new task: npm run jules:create \"My Feature\"");
+console.log("  4. Dispatch the queue:  npm run jules:queue");
+console.log("  5. Run pre-merge audit: npm run jules:audit\n");

package/index.mjs

@@ -0,0 +1,11 @@
+/**
+ * jules-orchestrator-kit Node.js SDK
+ * Primary entrypoint for programmatically orchestrating Google Jules workflows.
+ * Zero external dependencies.
+ */
+
+export { resolveProjectCommands, resolveWorkspaceExecutionBoundary } from "./scripts/command-resolver.mjs";
+export { runSelfAudit, runPreflightSandbox, loadForbiddenPatterns, loadAllowedPatterns, matchGlob } from "./scripts/jules-self-audit.mjs";
+export { scanCodebaseForTodos, runScanner } from "./scripts/jules-scan-todos.mjs";
+export { log, logToHistory, ensureDir, resolveMarkdownConflict } from "./scripts/utils.mjs";
+export { redactSecrets, getDynamicGuardrails } from "./scripts/jules-dispatch.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/FullThrottle83/jules-orchestrator-kit.git"
@@ -14,7 +14,12 @@
     "jules-init": "bin/init.js",
     "jules-orchestrator-kit": "bin/init.js"
   },
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
   "files": [
+    "index.mjs",
     "bin/",
     "scripts/",
     ".agent/jules.yml",
@@ -27,13 +32,16 @@
     "README.md",
     "LICENSE"
   ],
-
   "scripts": {
     "init": "node bin/init.js",
     "test": "node --test test/kit.test.mjs",
     "jules:dispatch": "node scripts/jules-dispatch.mjs",
     "jules:queue": "node scripts/jules-queue-runner.mjs",
+    "jules:create": "node scripts/jules-create.mjs",
+    "jules:status": "node scripts/jules-status.mjs",
     "jules:audit": "node scripts/jules-self-audit.mjs",
+    "jules:cleanup": "node scripts/jules-cleanup.mjs",
+    "jules:scan": "node scripts/jules-scan-todos.mjs",
     "jules:swarm": "node scripts/jules-swarm.mjs",
     "jules:nightly": "node scripts/jules-nightly.mjs"
   },
@@ -48,7 +56,6 @@
     "mcp",
     "automation"
   ],
-  "author": "Jonas (FullThrottle83)",
+  "author": "Google Open Source",
   "license": "MIT"
 }
-

package/scripts/jules-cleanup.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * Jules Session Cleanup & PR Audit Utility
+ * Cross-references active/completed Jules REST API sessions with GitHub PR merge status
+ * to report and safely close merged or stale sessions.
+ * Zero external dependencies.
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { log } from "./utils.mjs";
+
+function loadEnv() {
+  const envPath = path.resolve(process.cwd(), ".env");
+  if (fs.existsSync(envPath)) {
+    const lines = fs.readFileSync(envPath, "utf-8").split("\n");
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eqIdx = trimmed.indexOf("=");
+      if (eqIdx > 0) {
+        const key = trimmed.slice(0, eqIdx).trim().replace(/^export\s+/, "");
+        let val = trimmed.slice(eqIdx + 1).trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          val = val.slice(1, -1);
+        }
+        if (!process.env[key]) {
+          process.env[key] = val;
+        }
+      }
+    }
+  }
+}
+loadEnv();
+
+const args = process.argv.slice(2);
+const isDryRun = args.includes("--dry-run") || process.env.JULES_DRY_RUN === "true" || process.env.JULES_DRY_RUN === "1";
+const isCompact = args.includes("--compact");
+const isMarkdown = args.includes("--markdown");
+const shouldCloseMerged = args.includes("--close-merged");
+
+let staleHours = 24;
+const staleIdx = args.indexOf("--stale-hours");
+if (staleIdx !== -1 && args[staleIdx + 1]) {
+  const parsed = parseFloat(args[staleIdx + 1]);
+  if (!isNaN(parsed) && parsed > 0) staleHours = parsed;
+}
+
+const apiKey = process.env.JULES_API_KEY || process.env.GEMINI_API_KEY || "";
+const apiUrl = process.env.JULES_API_URL || "https://jules.googleapis.com/v1alpha/sessions";
+
+export function checkGitHubPrMerged(prUrl) {
+  if (!prUrl || typeof prUrl !== "string") return false;
+  try {
+    const output = execFileSync("gh", ["pr", "view", prUrl, "--json", "state,mergedAt"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const parsed = JSON.parse(output);
+    return parsed.state === "MERGED" || Boolean(parsed.mergedAt);
+  } catch (_) {
+    return false;
+  }
+}
+
+export function extractPrUrls(outputs = []) {
+  const urls = [];
+  if (!Array.isArray(outputs)) return urls;
+  for (const item of outputs) {
+    const text = typeof item === "string" ? item : JSON.stringify(item);
+    const matches = text.match(/https:\/\/github\.com\/[^\/]+\/[^\/]+\/pull\/\d+/g);
+    if (matches) {
+      for (const m of matches) {
+        if (!urls.includes(m)) urls.push(m);
+      }
+    }
+  }
+  return urls;
+}
+
+export async function fetchJulesSessions(apiKeyOverride = apiKey) {
+  if (!apiKeyOverride) return [];
+  try {
+    const res = await fetch(apiUrl, {
+      method: "GET",
+      headers: {
+        "X-Goog-Api-Key": apiKeyOverride,
+        "Content-Type": "application/json"
+      }
+    });
+    if (!res.ok) return [];
+    const data = await res.json();
+    return data.sessions || data.items || [];
+  } catch (_) {
+    return [];
+  }
+}
+
+export function auditSessions(sessions, options = {}) {
+  const { staleHoursThreshold = 24 } = options;
+  const now = Date.now();
+
+  const merged = [];
+  const active = [];
+  const stale = [];
+
+  for (const session of sessions) {
+    const sId = session.name || session.id || "unknown";
+    const title = session.title || "Untitled Session";
+    const state = session.state || "UNKNOWN";
+    const updatedAt = session.updateTime ? new Date(session.updateTime).getTime() : now;
+    const hoursInactive = (now - updatedAt) / (1000 * 60 * 60);
+
+    const prUrls = extractPrUrls(session.outputs || session.outputUrls || []);
+    let isPrMerged = false;
+    if (prUrls.length > 0) {
+      isPrMerged = prUrls.every((url) => checkGitHubPrMerged(url));
+    }
+
+    const item = { id: sId, title, state, hoursInactive: Math.round(hoursInactive * 10) / 10, prUrls };
+
+    if (isPrMerged) {
+      merged.push(item);
+    } else if (hoursInactive >= staleHoursThreshold && state !== "COMPLETED") {
+      stale.push(item);
+    } else {
+      active.push(item);
+    }
+  }
+
+  return { merged, active, stale };
+}
+
+export async function runCleanup() {
+  if (!apiKey) {
+    log.info("JULES_API_KEY is not set. Skipping Jules REST API cleanup audit.");
+    return;
+  }
+
+  log.header("Jules Session Audit & Cleanup");
+  log.info(`Fetching active sessions from Jules REST API...`);
+
+  const sessions = await fetchJulesSessions(apiKey);
+  if (sessions.length === 0) {
+    log.info("No active or past sessions found on Jules REST API.");
+    return;
+  }
+
+  const { merged, active, stale } = auditSessions(sessions, { staleHoursThreshold: staleHours });
+
+  if (isCompact) {
+    console.log(`Total: ${sessions.length} | Merged Candidates: ${merged.length} | Active: ${active.length} | Stale (> ${staleHours}h): ${stale.length}`);
+    return;
+  }
+
+  if (isMarkdown) {
+    console.log(`\n### Jules Session Audit Summary\n`);
+    console.log(`| Category | Count |`);
+    console.log(`|---|---|`);
+    console.log(`| **Merged Candidates** | ${merged.length} |`);
+    console.log(`| **Active / In-Progress** | ${active.length} |`);
+    console.log(`| **Stale (> ${staleHours}h)** | ${stale.length} |`);
+    if (merged.length > 0) {
+      console.log(`\n#### Merged Sessions Ready for Cleanup\n`);
+      for (const m of merged) {
+        console.log(`- **${m.id}** (${m.title}) — PR: ${m.prUrls.join(", ") || "N/A"}`);
+      }
+    }
+    return;
+  }
+
+  log.info(`Found ${sessions.length} total session(s).`);
+  log.success(`Merged Cleanup Candidates: ${merged.length}`);
+  log.step("ℹ️", `Active Sessions: ${active.length}`);
+  if (stale.length > 0) {
+    log.warn(`Stale Sessions (> ${staleHours}h inactive): ${stale.length}`);
+  }
+
+  if (merged.length > 0) {
+    console.table(merged.map((m) => ({ ID: m.id, Title: m.title, State: m.state, InactiveHours: m.hoursInactive })));
+
+    if (shouldCloseMerged && !isDryRun) {
+      for (const m of merged) {
+        log.step("🧹", `Deleting merged session: ${m.id}...`);
+        try {
+          const deleteUrl = `${apiUrl}/${m.id}`;
+          await fetch(deleteUrl, { method: "DELETE", headers: { "X-Goog-Api-Key": apiKey } });
+          log.success(`Deleted session ${m.id}`);
+        } catch (err) {
+          log.warn(`Failed to delete session ${m.id}: ${err.message}`);
+        }
+      }
+    } else if (isDryRun) {
+      log.dim(`[DRY RUN] Would delete ${merged.length} merged session(s). Use --close-merged to execute deletion.`);
+    } else {
+      log.info(`Run with \`--close-merged\` to delete the ${merged.length} merged session(s).`);
+    }
+  }
+}

package/scripts/jules-create.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Jules Task Scaffolding Utility
+ * Quickly creates a boilerplate markdown task in .agent/jules-queue/
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { log, ensureDir } from "./utils.mjs";
+
+const taskTitle = process.argv[2];
+
+if (!taskTitle) {
+  log.error("Usage: npm run jules:create \"Task Title\"");
+  process.exit(1);
+}
+
+const queueDir = path.resolve(process.cwd(), ".agent/jules-queue");
+ensureDir(queueDir);
+
+const safeTitle = taskTitle.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+const filesInQueue = fs.readdirSync(queueDir).filter(f => f.endsWith(".md") && f !== "README.md");
+const nextId = (filesInQueue.length + 1).toString().padStart(3, "0");
+const filename = `TASK-${nextId}-${safeTitle}.md`;
+const filepath = path.join(queueDir, filename);
+
+const boilerplate = `# ${taskTitle}
+
+## Objective
+[Describe the primary goal of this task in a few sentences]
+
+## Context & Files
+[List the specific files Jules should focus on or any context required]
+- 
+
+## Verification
+[How should Jules verify that this task is completed? e.g., run tests, check UI]
+`;
+
+try {
+  fs.writeFileSync(filepath, boilerplate, "utf-8");
+  log.success(`Scaffolded new task: ${path.relative(process.cwd(), filepath)}`);
+  log.dim("Open this file, fill in the details, and run `npm run jules:queue` when ready!");
+} catch (err) {
+  log.error(`Failed to create task file: ${err.message}`);
+  process.exit(1);
+}