jules-orchestrator-kit 0.8.1 → 0.9.3

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/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,
+  };
+}

package/src/rules_budget.mjs

@@ -0,0 +1,77 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const DEFAULT_MAX_CHARS = 10000; // Safe threshold below Antigravity 12k & Claude 25k limits
+const DEFAULT_MAX_LINES = 250;
+
+/**
+ * Audit character and line counts of compiled instruction files to prevent truncation.
+ *
+ * @param {string} root - Project root directory
+ * @param {Object} [opts] - Options (maxChars, maxLines)
+ * @returns {{ ok: boolean, violations: Array<{ path: string, charCount: number, lineCount: number, reason: string }> }}
+ */
+export function checkRulesBudget(root = process.cwd(), opts = {}) {
+  const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
+  const maxLines = opts.maxLines ?? DEFAULT_MAX_LINES;
+  const violations = [];
+
+  const candidateFiles = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    ".cursorrules",
+    "JULES_RULES_TEMPLATE.md",
+  ];
+
+  // Scan .agent/rules/ directory if it exists
+  const rulesDir = join(root, ".agent", "rules");
+  try {
+    const files = readdirSync(rulesDir);
+    for (const f of files) {
+      if (f.endsWith(".md")) {
+        candidateFiles.push(join(".agent", "rules", f));
+      }
+    }
+  } catch (_) {}
+
+  for (const relPath of candidateFiles) {
+    const fullPath = join(root, relPath);
+    if (!existsSync(fullPath)) continue;
+
+    try {
+      const content = readFileSync(fullPath, "utf-8");
+      const charCount = content.length;
+      const lineCount = content.split("\n").length;
+
+      if (charCount > maxChars) {
+        violations.push({
+          path: relPath,
+          charCount,
+          lineCount,
+          reason: `Exceeds max character budget of ${maxChars} chars (${charCount} chars). Antigravity silently truncates rules > 12,000 chars.`,
+        });
+      } else if (lineCount > maxLines) {
+        violations.push({
+          path: relPath,
+          charCount,
+          lineCount,
+          reason: `Exceeds max line budget of ${maxLines} lines (${lineCount} lines). Claude Code auto-memory truncates > 200 lines.`,
+        });
+      }
+    } catch (_) {}
+  }
+
+  return {
+    ok: violations.length === 0,
+    violations,
+  };
+}
+
+function existsSync(p) {
+  try {
+    return statSync(p).isFile();
+  } catch (_) {
+    return false;
+  }
+}