jules-orchestrator-kit 0.8.5 → 0.9.4

package/src/git.mjs

@@ -0,0 +1,127 @@
+import { execFileSync } from "node:child_process";
+import { sep } from "node:path";
+
+export class GateError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "GateError";
+    this.code = opts.code || 1;
+  }
+}
+
+function normalizePath(p) {
+  if (!p || typeof p !== "string") return "";
+  return p.split(sep).join("/").replace(/\\/g, "/");
+}
+
+export function runCmd(command, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  try {
+    const stdout = execFileSync("sh", ["-c", command], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { status: 0, stdout: stdout.trim(), stderr: "" };
+  } catch (err) {
+    if (opts.ignoreError) {
+      return {
+        status: err.status || 1,
+        stdout: (err.stdout || "").toString().trim(),
+        stderr: (err.stderr || "").toString().trim(),
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Shell-safe git invoker using direct argument arrays (shell: false).
+ */
+export function git(args = [], opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const argArray = Array.isArray(args) ? args : String(args).split(" ").filter(Boolean);
+  try {
+    const stdout = execFileSync("git", argArray, {
+      cwd,
+      encoding: "utf-8",
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return opts.raw ? stdout : stdout.trim();
+  } catch (err) {
+    if (opts.ignoreError) {
+      return "";
+    }
+    const stderr = (err.stderr || err.message || "").toString().trim();
+    throw new GateError(`Git command failed [git ${argArray.join(" ")}]: ${stderr}`);
+  }
+}
+
+export function resolveBase(root = process.cwd(), baseRef = "main") {
+  const candidates = [`origin/${baseRef}`, baseRef, `refs/remotes/origin/${baseRef}`, "HEAD"];
+  for (const ref of candidates) {
+    try {
+      const res = execFileSync("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+        cwd: root,
+        encoding: "utf-8",
+        shell: false,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      if (res && res.trim()) {
+        return ref;
+      }
+    } catch (_) {}
+  }
+  throw new GateError(
+    `Cannot resolve base reference "${baseRef}". Ensure base branch is fetched (e.g., fetch-depth: 0 in CI).`,
+    { code: 1 }
+  );
+}
+
+export function changedFiles(root = process.cwd(), base = "main") {
+  const resolvedRef = resolveBase(root, base);
+  const raw = git(["-c", "core.quotePath=false", "diff", "-z", "--name-only", `${resolvedRef}...HEAD`], {
+    cwd: root,
+    raw: true,
+  });
+  return raw
+    .split("\0")
+    .map(normalizePath)
+    .filter(Boolean);
+}
+
+export function diffBytes(root = process.cwd(), base = "main") {
+  const resolvedRef = resolveBase(root, base);
+  const raw = git(["diff", "--shortstat", `${resolvedRef}...HEAD`], { cwd: root });
+  if (!raw) return 0;
+  const diffStr = git(["diff", `${resolvedRef}...HEAD`], { cwd: root, raw: true });
+  return Buffer.byteLength(diffStr, "utf-8");
+}
+
+export function diffText(root = process.cwd(), base = "main") {
+  const resolvedRef = resolveBase(root, base);
+  return git(["diff", `${resolvedRef}...HEAD`], { cwd: root, raw: true });
+}
+
+export function showFromOrigin(root = process.cwd(), base = "main", filePath = "") {
+  const resolvedRef = resolveBase(root, base);
+  const normPath = normalizePath(filePath);
+  try {
+    return git(["show", `${resolvedRef}:${normPath}`], { cwd: root, raw: true });
+  } catch (_) {
+    return null;
+  }
+}
+
+export function worktreeAdd(root = process.cwd(), branch = "agent/task", targetDir = "") {
+  return git(["worktree", "add", targetDir, "-b", branch], { cwd: root });
+}
+
+export function worktreeRemove(root = process.cwd(), targetDir = "") {
+  return git(["worktree", "remove", targetDir, "--force"], { cwd: root });
+}
+
+export function worktreePrune(root = process.cwd()) {
+  return git(["worktree", "prune"], { cwd: root });
+}

package/src/mcp.mjs

@@ -0,0 +1,211 @@
+import { createInterface } from "node:readline";
+import { loadConfig, resolveRoot, detectStack } from "./config.mjs";
+import { gate, dispatch } from "./engine.mjs";
+import { classifyRiskTier } from "./risk.mjs";
+import { checkDailyBudget, lockStatus } from "./state.mjs";
+
+export const MCP_SERVER_INFO = {
+  name: "jules-orchestrator-kit",
+  version: "0.9.4",
+};
+
+export const MCP_TOOLS = [
+  {
+    name: "dispatch_jules_task",
+    description: "Dispatch an autonomous task to the Jules AI agent provider with security bounds and budget check.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Short descriptive title for the task" },
+        prompt: { type: "string", description: "Detailed task instructions and prompt" },
+      },
+      required: ["prompt"],
+    },
+  },
+  {
+    name: "audit_jules_gate",
+    description: "Run the 4-phase safety gatekeeper (Scope, Payload, Secrets, Verify) against the current workspace branch.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        base: { type: "string", description: "Base branch to diff against (defaults to main)" },
+        fix: { type: "boolean", description: "Attempt OODA auto-repair loop on verification failure" },
+        allowProtected: { type: "boolean", description: "Allow edits to protected files" },
+      },
+    },
+  },
+  {
+    name: "check_risk_tier",
+    description: "Classify changed files into Risk Tiers (R0 Cosmetic, R1 Routine, R2 Consequential, R3 Restricted).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        files: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of file paths changed",
+        },
+        diffLines: { type: "number", description: "Total lines changed in diff" },
+      },
+      required: ["files"],
+    },
+  },
+  {
+    name: "get_jules_status",
+    description: "Retrieve orchestrator status including daily task budget, active locks, and stack diagnostics.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+];
+
+export async function handleMcpRequest(request, opts = {}) {
+  const root = opts.root || resolveRoot();
+  const config = opts.config || loadConfig(root);
+  const { id, method, params } = request;
+
+  if (method === "ping") {
+    return { jsonrpc: "2.0", id, result: {} };
+  }
+
+  if (method === "initialize") {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        protocolVersion: "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: MCP_SERVER_INFO,
+      },
+    };
+  }
+
+  if (method === "notifications/initialized") {
+    return null; // Notifications produce no response
+  }
+
+  if (method === "tools/list") {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: { tools: MCP_TOOLS },
+    };
+  }
+
+  if (method === "tools/call") {
+    const toolName = params?.name;
+    const args = params?.arguments || {};
+
+    try {
+      if (toolName === "dispatch_jules_task") {
+        const session = await dispatch(
+          { title: args.title || "MCP Task Dispatch", prompt: args.prompt },
+          { root, config }
+        );
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, session }, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "audit_jules_gate") {
+        const res = await gate({
+          root,
+          config,
+          base: args.base || config.baseBranch || "main",
+          fix: args.fix || false,
+          allowProtected: args.allowProtected || false,
+        });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "check_risk_tier") {
+        const tierResult = classifyRiskTier(args.files || [], { diffLines: args.diffLines || 0 });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(tierResult, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "get_jules_status") {
+        const stackInfo = detectStack(root);
+        const budget = checkDailyBudget(root, config.limits.dailyTasks);
+        const locks = lockStatus(root);
+        const status = {
+          version: MCP_SERVER_INFO.version,
+          root,
+          stack: stackInfo.stack,
+          budget: { used: budget.used, limit: budget.budget, remaining: budget.budget - budget.used },
+          activeLocksCount: locks.length,
+          locks,
+        };
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(status, null, 2) }],
+          },
+        };
+      }
+
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32601, message: `Unknown tool: ${toolName}` },
+      };
+    } catch (err) {
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [{ type: "text", text: JSON.stringify({ ok: false, error: err.message }, null, 2) }],
+          isError: true,
+        },
+      };
+    }
+  }
+
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: { code: -32601, message: `Method not found: ${method}` },
+  };
+}
+
+export function startMcpServer(input = process.stdin, output = process.stdout, opts = {}) {
+  const rl = createInterface({ input, output: null, terminal: false });
+
+  rl.on("line", async (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    try {
+      const request = JSON.parse(trimmed);
+      const response = await handleMcpRequest(request, opts);
+      if (response !== null) {
+        output.write(JSON.stringify(response) + "\n");
+      }
+    } catch (err) {
+      output.write(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32700, message: `Parse error: ${err.message}` },
+        }) + "\n"
+      );
+    }
+  });
+}

package/src/provider.mjs

@@ -0,0 +1,179 @@
+import { spawnSync } from "node:child_process";
+
+export const JULES_PRESET = {
+  name: "jules",
+  type: "http",
+  url: "https://jules.googleapis.com/v1/projects/{project}/sessions",
+  headers: {
+    "Authorization": "Bearer {token}",
+    "Content-Type": "application/json",
+  },
+  bodyTemplate: {
+    prompt: "{prompt}",
+    title: "{title}",
+    branch: "{branch}",
+  },
+};
+
+export const CLAUDE_PRESET = {
+  name: "claude-code",
+  type: "exec",
+  command: "claude",
+  args: ["--print", "-p", "{prompt}"],
+  promptViaStdin: true,
+};
+
+export const CODEX_PRESET = {
+  name: "codex",
+  type: "exec",
+  command: "codex",
+  args: ["exec", "{prompt}"],
+  promptViaStdin: false,
+};
+
+function interpolateString(template, data) {
+  if (typeof template !== "string") return template;
+  return template.replace(/\{(\w+)\}/g, (_, key) => data[key] ?? "");
+}
+
+function interpolateDeep(node, data) {
+  if (typeof node === "string") return interpolateString(node, data);
+  if (Array.isArray(node)) return node.map((item) => interpolateDeep(item, data));
+  if (node && typeof node === "object") {
+    const res = {};
+    for (const [k, v] of Object.entries(node)) {
+      res[k] = interpolateDeep(v, data);
+    }
+    return res;
+  }
+  return node;
+}
+
+/**
+ * Creates an HTTP or Exec provider adapter based on spec/config.
+ */
+export function createProvider(spec = "jules", config = {}) {
+  const providerSpec = typeof spec === "string"
+    ? (spec === "claude-code" ? CLAUDE_PRESET : spec === "codex" ? CODEX_PRESET : JULES_PRESET)
+    : spec;
+
+  return {
+    name: providerSpec.name || "custom-provider",
+
+    async dispatch(task, ctx = {}) {
+      const rawToken = process.env.JULES_API_KEY || process.env.GEMINI_API_KEY || "";
+      const data = {
+        prompt: task.prompt || "",
+        title: task.title || "Agent Task",
+        branch: task.branch || (config.branchPrefix ? config.branchPrefix + "task" : "agent/task"),
+        project: process.env.JULES_PROJECT_ID || "default",
+        ...ctx,
+      };
+
+      if (ctx.dryRun) {
+        return {
+          id: "dry-run-session-id",
+          status: "pending",
+          title: data.title,
+          provider: providerSpec.name,
+          data: {
+            ...data,
+            token: rawToken ? "[REDACTED]" : undefined,
+          },
+        };
+      }
+
+      if (providerSpec.type === "http") {
+        const urlData = { ...data, token: rawToken };
+        const url = interpolateString(providerSpec.url, urlData);
+        const headers = {};
+        for (const [k, v] of Object.entries(providerSpec.headers || {})) {
+          const val = interpolateString(v, urlData);
+          if (val.includes("\r") || val.includes("\n")) {
+            throw new Error(`CRITICAL: Header injection attempt detected in header "${k}"`);
+          }
+          headers[k] = val;
+        }
+
+        let body;
+        if (typeof providerSpec.bodyTemplate === "string") {
+          try {
+            const parsedObj = JSON.parse(providerSpec.bodyTemplate);
+            const interpolatedObj = interpolateDeep(parsedObj, data);
+            body = JSON.stringify(interpolatedObj);
+          } catch (_) {
+            body = interpolateString(providerSpec.bodyTemplate, data);
+          }
+        } else if (providerSpec.bodyTemplate) {
+          const interpolatedObj = interpolateDeep(providerSpec.bodyTemplate, data);
+          body = JSON.stringify(interpolatedObj);
+        } else {
+          body = JSON.stringify(data);
+        }
+
+        const res = await fetch(url, {
+          method: providerSpec.method || "POST",
+          headers,
+          body,
+        });
+
+        if (!res.ok) {
+          const text = await res.text();
+          const cleanText = text.slice(0, 500);
+          const sanitizedText = rawToken ? cleanText.split(rawToken).join("[REDACTED]") : cleanText;
+          throw new Error(`Provider HTTP Error (${res.status}): ${sanitizedText}`);
+        }
+
+        const json = await res.json();
+        return {
+          id: json.id || json.name || "http-session",
+          status: json.state || "active",
+          raw: json,
+        };
+      }
+
+      if (providerSpec.type === "exec") {
+        const rawArgs = providerSpec.args || (providerSpec.command ? providerSpec.command.split(" ").slice(1) : []);
+        const command = providerSpec.command ? providerSpec.command.split(" ")[0] : "claude";
+
+        // CRITICAL H-a FIX: Filter out '{prompt}' argument if prompt is passed via stdin
+        const filteredArgs = providerSpec.promptViaStdin
+          ? rawArgs.filter((arg) => !arg.includes("{prompt}"))
+          : rawArgs;
+
+        const processedArgs = filteredArgs.map((arg) => interpolateString(arg, data));
+
+        const res = spawnSync(command, processedArgs, {
+          cwd: config._root || process.cwd(),
+          encoding: "utf-8",
+          shell: false, // CRITICAL: Ban shell execution to eliminate CWE-77
+          input: providerSpec.promptViaStdin ? data.prompt : undefined,
+          timeout: providerSpec.timeoutMs || 900000,
+          maxBuffer: 32 * 1024 * 1024,
+        });
+
+        if (res.error) {
+          throw new Error(`Provider Exec Failed: ${res.error.message}`);
+        }
+        if (res.status !== 0) {
+          const stderr = (res.stderr || "").slice(0, 500);
+          throw new Error(`Provider Exec Exit ${res.status}: ${stderr}`);
+        }
+
+        return {
+          id: "exec-session-" + Date.now(),
+          status: "completed",
+          output: res.stdout || "",
+        };
+      }
+
+      throw new Error(`Unsupported provider type: ${providerSpec.type}`);
+    },
+
+    validate() {
+      if (providerSpec.type === "http" && !providerSpec.url) return false;
+      if (providerSpec.type === "exec" && !providerSpec.command) return false;
+      return true;
+    },
+  };
+}

package/src/risk.mjs

@@ -0,0 +1,120 @@
+import { normalizePath } from "./config.mjs";
+
+export const RISK_TIERS = {
+  R0: "R0_COSMETIC",     // Docs, markdown, comments, safe devDep patches
+  R1: "R1_ROUTINE",      // Pure utility logic, unit tests, single package layer
+  R2: "R2_CONSEQUENTIAL",// UI components, DB helpers, diff > 400 lines, bundle size impact
+  R3: "R3_RESTRICTED",   // Migrations, Auth, Pricing/VAT, Protected paths (.github, configs)
+};
+
+const RESTRICTED_PATH_PATTERNS = [
+  "**/drizzle/migrations/**",
+  "**/migrations/**",
+  "**/auth/**",
+  "**/pricing/**",
+  "**/vat/**",
+  "**/contracts/**",
+  "**/ledger/**",
+  ".github/**",
+  ".githooks/**",
+  "wrangler.jsonc",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+];
+
+const CONSEQUENTIAL_PATH_PATTERNS = [
+  "apps/web/src/components/**",
+  "packages/db/**",
+  "src/engine.mjs",
+  "src/security.mjs",
+];
+
+const COSMETIC_EXTENSIONS = new Set([".md", ".txt", ".jsonl", ".svg"]);
+
+/**
+ * Classifies a set of changed files and diff metadata into a Risk Tier (R0, R1, R2, R3).
+ *
+ * @param {string[]} files - Array of changed file paths
+ * @param {Object} [opts] - Options (diffBytes, diffLines, author)
+ * @returns {{ tier: string, reason: string, isAutoMergeAllowed: boolean, requiresHumanReview: boolean }}
+ */
+export function classifyRiskTier(files = [], opts = {}) {
+  const diffLines = opts.diffLines ?? 0;
+
+  if (!files || files.length === 0) {
+    return {
+      tier: RISK_TIERS.R0,
+      reason: "No files changed",
+      isAutoMergeAllowed: true,
+      requiresHumanReview: false,
+    };
+  }
+
+  // 1. Check R3 (Restricted Paths)
+  for (const rawFile of files) {
+    const file = normalizePath(rawFile);
+    for (const pat of RESTRICTED_PATH_PATTERNS) {
+      if (file.includes(pat.replace(/\*/g, "")) || file.endsWith(pat)) {
+        return {
+          tier: RISK_TIERS.R3,
+          reason: `Matches restricted security/financial path pattern '${pat}'`,
+          isAutoMergeAllowed: false,
+          requiresHumanReview: true,
+        };
+      }
+    }
+  }
+
+  // 2. Check R2 (Consequential Paths or Diff Size > 400 lines)
+  if (diffLines >= 400) {
+    return {
+      tier: RISK_TIERS.R2,
+      reason: `Diff size (${diffLines} lines) exceeds R1 limit of 400 lines`,
+      isAutoMergeAllowed: false,
+      requiresHumanReview: true,
+    };
+  }
+
+  for (const rawFile of files) {
+    const file = normalizePath(rawFile);
+    for (const pat of CONSEQUENTIAL_PATH_PATTERNS) {
+      if (file.includes(pat.replace(/\*/g, ""))) {
+        return {
+          tier: RISK_TIERS.R2,
+          reason: `Matches consequential component/DB path pattern '${pat}'`,
+          isAutoMergeAllowed: false,
+          requiresHumanReview: true,
+        };
+      }
+    }
+  }
+
+  // 3. Check R0 (Purely Cosmetic files)
+  const isAllCosmetic = files.every((rawFile) => {
+    const file = normalizePath(rawFile);
+    if (file.startsWith(".agent/history/") || file.startsWith("docs/")) return true;
+    const dotIdx = file.lastIndexOf(".");
+    if (dotIdx !== -1) {
+      const ext = file.slice(dotIdx).toLowerCase();
+      return COSMETIC_EXTENSIONS.has(ext);
+    }
+    return false;
+  });
+
+  if (isAllCosmetic) {
+    return {
+      tier: RISK_TIERS.R0,
+      reason: "All changed files are markdown, documentation, or cosmetic assets",
+      isAutoMergeAllowed: true,
+      requiresHumanReview: false,
+    };
+  }
+
+  // 4. Default R1 (Routine Logic)
+  return {
+    tier: RISK_TIERS.R1,
+    reason: "Routine isolated package logic / unit test update within limits",
+    isAutoMergeAllowed: true,
+    requiresHumanReview: false,
+  };
+}