jules-orchestrator-kit 0.29.0 → 0.31.0

package/bin/agentctl.mjs

@@ -2,7 +2,7 @@
 
 import { parseArgs } from "node:util";
 import { readFileSync, existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { loadConfig, resolveRoot, detectStack, bootstrapZeroTestRepo } from "../src/config.mjs";
 import { gate, dispatch, run, isTaskFile } from "../src/engine.mjs";
 import { acquireLock, releaseLock, lockStatus, checkDailyBudget, getQueueDir } from "../src/state.mjs";
@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.29.0 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.30.0 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -32,6 +32,11 @@ Commands:
   dashboard             Start local HTTP telemetry and audit dashboard
   init                  Scaffold .agent/ config and run onboarding wizard
   task create           Interactively author and scope a Jules task envelope
+  task optimize         Linter & optimizer for Jules task prompts (--fix, --json)
+  test-gen              Scaffold & run automated TDD Red-to-Green test cycle (--run)
+  mcp init              Scaffold IDE integration config (cursor | vscode | claude | all)
+  rollback              Restore git state & working tree to atomic pre-flight checkpoint
+  resume                Resume warm session with human response (--response "<text>")
   status                Display queue and system status summary
   scan                  Scan codebase for TODO/FIXME task candidates
   version               Output agentctl version
@@ -54,7 +59,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.29.0");
+    console.log("agentctl v0.29.1");
     process.exit(0);
   }
 
@@ -265,7 +270,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.29.0)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.29.1)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);
@@ -391,8 +396,66 @@ async function main() {
           console.log(`   Auto-PR  : ${res.plan.flags.autoPr}`);
         }
         process.exit(0);
+      } else if (subCommand === "optimize") {
+        const { values, positionals } = parseArgs({
+          args: args.slice(2),
+          options: {
+            fix: { type: "boolean", short: "f" },
+            file: { type: "string" },
+            dir: { type: "string", short: "d" },
+            json: { type: "boolean", short: "j" },
+            "verify-cmd": { type: "string", short: "v" },
+          },
+          allowPositionals: true,
+        });
+
+        const { scorePromptFalsifiability, optimizeTaskPrompt } = await import("../src/task-optimizer.mjs");
+        const targetDir = values.dir ? resolve(values.dir) : root;
+        let promptText = positionals.join(" ");
+
+        if (values.file) {
+          if (existsSync(values.file)) {
+            promptText = readFileSync(values.file, "utf-8");
+          } else {
+            console.error(`Error: File '${values.file}' does not exist.`);
+            process.exit(1);
+          }
+        }
+
+        if (values.fix) {
+          const opt = optimizeTaskPrompt(promptText, { rootDir: targetDir, verifyCmd: values["verify-cmd"] });
+          if (values.json) {
+            console.log(JSON.stringify(opt, null, 2));
+          } else {
+            console.log(opt.optimizedPrompt);
+          }
+          process.exit(0);
+        }
+
+        const analysis = scorePromptFalsifiability(promptText, { rootDir: targetDir, verifyCmd: values["verify-cmd"] });
+        if (values.json) {
+          console.log(JSON.stringify(analysis, null, 2));
+        } else {
+          console.log(`\n🎯 Task Prompt Falsifiability Analysis`);
+          console.log(`--------------------------------------------------`);
+          console.log(`  Score / Grade    : ${analysis.score} / 100 (${analysis.grade})`);
+          console.log(`  Falsifiable      : ${analysis.isFalsifiable ? "✅ YES" : "❌ NO"}`);
+          if (analysis.oracle.command) {
+            console.log(`  Oracle Command   : "${analysis.oracle.command}" (${analysis.oracle.autoDetected ? "Auto-detected" : "User-supplied"})`);
+          }
+          if (analysis.issues.length > 0) {
+            console.log(`\n  Issues Identified (${analysis.issues.length}):`);
+            analysis.issues.forEach((i) => console.log(`   - [${i.type}] ${i.message} (-${i.penalty} pts)`));
+          }
+          if (analysis.suggestions.length > 0) {
+            console.log(`\n  Suggestions for Improvement:`);
+            analysis.suggestions.forEach((s) => console.log(`   - ${s}`));
+          }
+          console.log(`--------------------------------------------------\n`);
+        }
+        process.exit(analysis.isFalsifiable ? 0 : 1);
       } else {
-        console.error(`Unknown task subcommand '${subCommand}'. Supported: agentctl task create`);
+        console.error(`Unknown task subcommand '${subCommand}'. Supported: agentctl task create, agentctl task optimize`);
         process.exit(1);
       }
       break;
@@ -401,7 +464,7 @@ async function main() {
     case "status": {
       const queueDir = getQueueDir(root);
       const files = existsSync(queueDir) ? readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir)) : [];
-      console.log(`\n📊 agentctl Status Summary (v0.29.0)`);
+      console.log(`\n📊 agentctl Status Summary (v0.29.1)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Pending Tasks    : ${files.length}`);
@@ -427,7 +490,143 @@ async function main() {
       break;
     }
 
+    case "rollback": {
+      const { restoreCheckpoint } = await import("../src/ops/checkpoint.mjs");
+      const targetId = args[1] || "--latest";
+      try {
+        const res = restoreCheckpoint(targetId, { root });
+        console.log(`\n✅ Git Checkpoint Restored Successfully!`);
+        console.log(`   Session ID : ${res.id}`);
+        console.log(`   HEAD SHA   : ${res.headSha || "N/A"}`);
+        console.log(`   RestoredAt : ${res.restoredAt}\n`);
+        process.exit(0);
+      } catch (err) {
+        console.error(`❌ Rollback Failed: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "resume": {
+      const { createProvider } = await import("../src/provider.mjs");
+      const sessionId = args[1];
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          response: { type: "string", short: "r" },
+          "dry-run": { type: "boolean", short: "d" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      if (!sessionId || sessionId.startsWith("-")) {
+        console.error("Error: Session ID is required for agentctl resume <sessionId>.");
+        process.exit(1);
+      }
+
+      const responseText = values.response || args.slice(2).join(" ");
+      if (!responseText) {
+        console.error("Error: --response text is required to resume warm session.");
+        process.exit(1);
+      }
+
+      const provider = createProvider(config.provider || "jules", config);
+      try {
+        const res = await provider.resume(sessionId, responseText, { root, dryRun: values["dry-run"] });
+        if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.log(`\n✅ Warm Session Resumed Successfully!`);
+          console.log(`   Session ID : ${res.id}`);
+          console.log(`   Status     : ${res.status}\n`);
+        }
+        process.exit(0);
+      } catch (err) {
+        console.error(`❌ Resume Failed: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "test-gen": {
+      const { scaffoldTddTest, runTddCycle } = await import("../src/ops/tdd-generator.mjs");
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          title: { type: "string", short: "t" },
+          spec: { type: "string", short: "s" },
+          run: { type: "boolean", short: "r" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      const title = values.title || args[1] || "feature-spec";
+      const specText = values.spec || args.slice(2).join(" ") || "TDD requirement specification.";
+
+      try {
+        if (values.run) {
+          const res = await runTddCycle({ title, spec: specText }, { root });
+          if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(`\n🔴 TDD RED Check Verified!`);
+            console.log(`   Test File   : ${res.testFile}`);
+            console.log(`   Scope Lock  : Locked into scope.deny`);
+            console.log(`   Status      : Ready for green implementation dispatch\n`);
+          }
+        } else {
+          const scaffold = scaffoldTddTest({ title, spec: specText }, { root });
+          if (values.json) {
+            console.log(JSON.stringify(scaffold, null, 2));
+          } else {
+            console.log(`\n🧪 TDD Test Scaffolded Successfully!`);
+            console.log(`   File Path : ${scaffold.relativePath}`);
+            console.log(`   Command   : ${scaffold.testCmd}\n`);
+          }
+        }
+        process.exit(0);
+      } catch (err) {
+        console.error(`❌ TDD Generation Failed: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
     case "mcp": {
+      const subAction = args[1];
+      if (subAction === "init") {
+        const { scaffoldIdeConfig } = await import("../src/ops/ide-scaffold.mjs");
+        const { values } = parseArgs({
+          args: args.slice(2),
+          options: {
+            target: { type: "string", short: "t", default: "all" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+
+        const target = values.target || args[2] || "all";
+        try {
+          const res = scaffoldIdeConfig(target, { root });
+          if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(`\n🔌 IDE MCP Config Scaffolded Successfully!`);
+            console.log(`   Target  : ${res.target}`);
+            for (const item of res.results) {
+              console.log(`   - ${item.target.toUpperCase()} : ${item.file}`);
+            }
+            console.log("");
+          }
+          process.exit(0);
+        } catch (err) {
+          console.error(`❌ IDE MCP Scaffold Failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+
       const { startMcpServer } = await import("../src/mcp.mjs");
       startMcpServer();
       break;

package/index.mjs

@@ -1,5 +1,5 @@
 /**
- * Google Jules Orchestrator Kit - Node.js SDK (v0.29.0)
+ * Google Jules Orchestrator Kit - Node.js SDK (v0.29.1)
  *
  * Exposes core orchestrator functions for programmatically driving agent tasks,
  * security auditing, repo gating, and state operations.
@@ -85,4 +85,24 @@ export { planInit, loadPresets, runInitWizard, TIER_PROFILES, BUILTIN_PRESETS }
 // Guided Task Authoring Subsystem
 export { planTaskCreate, runTaskCreateWizard, GUARDRAIL_FOOTER } from "./src/wizard-task.mjs";
 
+// Prompt Falsifiability & Task Optimizer Engine
+export { scorePromptFalsifiability, optimizeTaskPrompt, levenshteinDistance, extractPathTokens } from "./src/task-optimizer.mjs";
+
+// Atomic Git Checkpoints & Rollback
+export { createCheckpoint, restoreCheckpoint, listCheckpoints, pruneCheckpoints, CheckpointError } from "./src/ops/checkpoint.mjs";
+
+// Webhook & HITL Escalation Bridge
+export { dispatchEscalation, verifySignature, parseWebhookPayload, routeWebhookEvent, createWebhookServer } from "./src/webhook.mjs";
+
+// PR Review Evidence Bundler & Dev Server Probe
+export { synthesizePrDescription, probeDevServer } from "./src/engine.mjs";
+
+// Automated TDD Red-to-Green Harness
+export { scaffoldTddTest, runTddCycle, TddError } from "./src/ops/tdd-generator.mjs";
+
+// IDE Native MCP Scaffolder
+export { scaffoldIdeConfig, IdeScaffoldError } from "./src/ops/ide-scaffold.mjs";
+
+
+
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",

package/src/config.mjs

@@ -196,9 +196,19 @@ export function detectStack(projectRoot = process.cwd()) {
   return detectPolyglotStack(projectRoot);
 }
 
-export function resolveVerify(root = process.cwd()) {
+export function resolveVerify(root = process.cwd(), userVerify = {}) {
   const s = detectStack(root);
-  return { test: s.testCmd || "", build: s.buildCmd || "" };
+  return {
+    setup: userVerify.setup ?? s.setupCmd ?? "",
+    test: userVerify.test ?? s.testCmd ?? "",
+    teardown: userVerify.teardown ?? s.teardownCmd ?? "",
+    build: userVerify.build ?? s.buildCmd ?? "",
+    server: userVerify.server ? {
+      command: userVerify.server.command || "",
+      url: userVerify.server.url || "http://localhost:3000",
+      timeoutMs: Number(userVerify.server.timeoutMs || 15000),
+    } : null,
+  };
 }
 
 export const TIER_PRESETS = {
@@ -247,8 +257,11 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     }
   }
 
+  const setupCmd = parsed.setup_cmd || parsed.verify?.setup || "";
   const testCmd = parsed.test_cmd || parsed.verify?.test || "";
+  const teardownCmd = parsed.teardown_cmd || parsed.verify?.teardown || "";
   const buildCmd = parsed.build_cmd || parsed.verify?.build || "";
+  const verifyTimeoutMs = parsed.verify?.timeoutMs ?? parsed.verify?.timeout_ms ?? 60000;
   const autoVerify = resolveVerify(root);
 
   const activeTier = String(process.env.JULES_TIER || parsed.tier || "ultra").toLowerCase();
@@ -275,8 +288,11 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     provider: parsed.provider || DEFAULTS.provider,
     tier: activeTier,
     verify: {
+      setup: setupCmd || autoVerify.setup || "",
       test: testCmd || autoVerify.test,
+      teardown: teardownCmd || autoVerify.teardown || "",
       build: buildCmd || autoVerify.build,
+      timeoutMs: Number.isFinite(Number(verifyTimeoutMs)) ? Number(verifyTimeoutMs) : 60000,
     },
     scope: normalizeScope(parsed),
     limits: {

package/src/dag-engine.mjs

@@ -330,3 +330,79 @@ export class DagExecutor {
     });
   }
 }
+
+/**
+ * Global Contract Trigger List:
+ * Files matching these patterns are considered global structural contracts.
+ * If ANY modified file matches these patterns, selective test execution MUST yield to full test suite execution (returns null).
+ */
+export const GLOBAL_CONTRACT_PATTERNS = [
+  /^package(-lock)?\.json$/,
+  /^pnpm-lock\.yaml$/,
+  /^yarn\.lock$/,
+  /^tsconfig.*\.json$/,
+  /^schema\./,
+  /\.d\.ts$/,
+  /^\.env/,
+  /^\.agent\//,
+  /^Cargo\.(toml|lock)$/,
+  /^go\.(mod|sum)$/,
+  /^composer\.(json|lock)$/,
+];
+
+/**
+ * Checks if a relative file path matches global contract triggers.
+ */
+export function isGlobalContractFile(filePath = "") {
+  if (typeof filePath !== "string") return false;
+  const normalized = filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+  const baseName = normalized.split("/").pop();
+  return GLOBAL_CONTRACT_PATTERNS.some((pattern) => pattern.test(normalized) || pattern.test(baseName));
+}
+
+/**
+ * Resolves affected test files based on modified files and static import analysis.
+ * Returns null if full test suite should be executed (due to global contract change or unknown dependency),
+ * or an array of affected test file paths.
+ */
+export function resolveAffectedTests(modifiedFiles = [], options = {}) {
+  if (!Array.isArray(modifiedFiles) || modifiedFiles.length === 0) {
+    return [];
+  }
+
+  // 1. Check Global Contract Trigger List
+  for (const file of modifiedFiles) {
+    if (isGlobalContractFile(file)) {
+      return null; // Force full test suite execution
+    }
+  }
+
+  const knownTestFiles = Array.isArray(options.knownTestFiles) ? options.knownTestFiles : [];
+  const testSuffixRegex = options.testSuffixRegex || /\.(test|spec)\.(m?[jt]sx?|py|rs|go)$/i;
+
+  const affected = new Set();
+
+  for (const file of modifiedFiles) {
+    if (typeof file !== "string") continue;
+    const normalized = file.replace(/\\/g, "/").replace(/^\.\//, "");
+
+    // If the modified file itself is a test file, add it directly
+    if (testSuffixRegex.test(normalized)) {
+      affected.add(normalized);
+      continue;
+    }
+
+    // Match known test files that import or reference this file/module
+    const baseNameNoExt = normalized.split("/").pop().replace(/\.[^/.]+$/, "");
+    for (const testFile of knownTestFiles) {
+      if (typeof testFile !== "string") continue;
+      const normTest = testFile.replace(/\\/g, "/").replace(/^\.\//, "");
+      if (normTest.includes(baseNameNoExt)) {
+        affected.add(normTest);
+      }
+    }
+  }
+
+  return affected.size > 0 ? Array.from(affected) : null;
+}
+

package/src/dashboard.mjs

@@ -32,7 +32,7 @@ export function getDashboardHtml(root = process.cwd()) {
   </style>
 </head>
 <body>
-  <h1>🚀 jules-orchestrator-kit Dashboard (v0.29.0)</h1>
+  <h1>🚀 jules-orchestrator-kit Dashboard (v0.29.1)</h1>
   <div class="subtitle">Repository: <code>${root}</code></div>
 
   <div class="grid">
@@ -87,7 +87,7 @@ export function createDashboardServer({ root = process.cwd(), port: _port = 4100
 
     if (url.pathname === "/api/status") {
       res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-      return res.end(JSON.stringify({ ok: true, version: "0.29.0", root, ts: new Date().toISOString() }));
+      return res.end(JSON.stringify({ ok: true, version: "0.29.1", root, ts: new Date().toISOString() }));
     }
 
     if (url.pathname === "/api/telemetry") {