jules-orchestrator-kit 0.52.8 → 0.54.0

package/src/ops/doctor-registry.mjs

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { execFileSync, spawnSync } from "node:child_process";
 import { loadConfig } from "../config.mjs";
+import { probeProvider, detectAvailableProviders, probeProviderLiveness } from "../provider-readiness.mjs";
 import { resolveConcurrency } from "../budget.mjs";
 
 /**
@@ -429,40 +430,82 @@ export async function runDoctorChecks(options = {}) {
     });
   }
 
-  // 7. Jules Provider Key Check
-  const keyVar = process.env.JULES_API_KEY ? "JULES_API_KEY" : process.env.GEMINI_API_KEY ? "GEMINI_API_KEY" : "";
-  if (keyVar) {
+  // 7. Provider readiness — for the provider this repository actually selected.
+  //
+  // This used to ask one question ("is JULES_API_KEY set?") and report it as a
+  // high-severity warning regardless of the configured provider, so a
+  // repository driving the Claude Code or Codex CLI was permanently told it was
+  // misconfigured over a key it neither needs nor should have.
+  let configuredProvider = "jules";
+  try {
+    configuredProvider = loadConfig(root).provider || "jules";
+  } catch (_) {
+    // Fall back to the default; config.present already reports a broken config.
+  }
+  const providerProbe = probeProvider(configuredProvider);
+  // A green row here used to read as "the provider works", when all it ever
+  // checked was a name on PATH or a variable in the environment. An installed
+  // CLI whose account has no entitlement passes both and then fails on the
+  // first dispatch, so the row has to say what it actually verified.
+  const liveness = activeProbe ? probeProviderLiveness(configuredProvider) : null;
+  const scopeNote =
+    providerProbe.kind === "exec"
+      ? "Checked: the binary is on PATH. Not checked: whether the CLI is signed in — only a dispatch can show that."
+      : "Checked: a credential is present in the environment. Not checked: whether the provider accepts it.";
+  const livenessFailed = Boolean(liveness && liveness.attempted && !liveness.ok);
+
+  addResult({
+    id: "provider.key",
+    category: "Provider",
+    title: `Provider Readiness (${providerProbe.name})`,
+    alwaysShowSummary: true,
+    status: providerProbe.ready && !livenessFailed ? "pass" : "warn",
+    severity: providerProbe.ready && !livenessFailed ? "info" : "high",
+    // Naming the variable, not the value: an operator who wonders which key a
+    // dispatch will use should not have to echo a secret to find out.
+    summary: [
+      `${providerProbe.label} — ${providerProbe.reason}`,
+      liveness && liveness.attempted ? liveness.detail : null,
+      providerProbe.ready ? scopeNote : null,
+      !activeProbe && providerProbe.kind === "exec" ? "Run `agentctl doctor --probe` to start the CLI and confirm it answers." : null,
+    ]
+      .filter(Boolean)
+      .join(" "),
+    remediation:
+      providerProbe.ready && !livenessFailed
+        ? []
+        : [
+            {
+              summary: livenessFailed ? `The CLI is installed but did not run cleanly: ${liveness.detail}` : providerProbe.remedy,
+              risk: "low",
+              automatic: false,
+              requiresProbe: !providerProbe.ready ? false : true,
+            },
+          ],
+    evidence: [
+      { label: "provider", value: providerProbe.name, sensitive: false },
+      { label: "providerKind", value: providerProbe.kind, sensitive: false },
+      { label: "ready", value: providerProbe.ready, sensitive: false },
+      { label: "keySource", value: providerProbe.keySource || "", sensitive: false },
+      { label: "binaryFound", value: Boolean(providerProbe.binPath), sensitive: false },
+      { label: "livenessProbed", value: Boolean(liveness && liveness.attempted), sensitive: false },
+      { label: "livenessOk", value: liveness ? liveness.ok : null, sensitive: false },
+    ],
+  });
+
+  // 7a. What else this machine could dispatch to. Purely informational: an
+  // operator blocked on one provider should not have to discover by reading
+  // source that three others are installed and ready.
+  const alternatives = detectAvailableProviders().filter((p) => p.ready && p.name !== providerProbe.name);
+  if (alternatives.length > 0) {
     addResult({
-      id: "provider.key",
-      category: "Jules",
-      title: "Jules Provider API Key",
+      id: "provider.alternatives",
+      category: "Provider",
+      title: "Other Providers Available",
       status: "pass",
       severity: "info",
-      // Naming the variable, not the value: an operator who wonders which key a
-      // dispatch will use should not have to echo a secret to find out.
-      summary: `API key supplied via ${keyVar} (environment only — never written to config or sent anywhere but the provider)`,
-      evidence: [
-        { label: "keyConfigured", value: true, sensitive: false },
-        { label: "keySource", value: keyVar, sensitive: false },
-      ],
-    });
-  } else {
-    addResult({
-      id: "provider.key",
-      category: "Jules",
-      title: "Jules Provider API Key",
-      status: "warn",
-      severity: "high",
-      summary: "Neither JULES_API_KEY nor GEMINI_API_KEY environment variable is set",
-      remediation: [
-        {
-          summary: "Export JULES_API_KEY in your shell profile, or place it in a git-ignored .env",
-          risk: "low",
-          automatic: false,
-          requiresProbe: false,
-        },
-      ],
-      evidence: [{ label: "keyConfigured", value: false, sensitive: false }],
+      summary: `Also ready on this machine: ${alternatives.map((p) => p.name).join(", ")} — switch with provider: in .agent/config.yml`,
+      evidence: alternatives.map((p) => ({ label: p.name, value: p.reason, sensitive: false })),
     });
   }
 
@@ -477,7 +520,7 @@ export async function runDoctorChecks(options = {}) {
 
     addResult({
       id: "provider.key.dotenv",
-      category: "Jules",
+      category: "Provider",
       title: "Local .env secrecy",
       status: tracked ? "fail" : "pass",
       severity: tracked ? "critical" : "info",

package/src/ops/ide-scaffold.mjs

@@ -11,14 +11,32 @@ export class IdeScaffoldError extends Error {
 
 /**
  * Scaffolds IDE integration configuration files for Cursor, VS Code, and Claude Desktop.
+ *
+ * These files land in directories a project may already be using (`.cursor/`,
+ * `.vscode/`), and the merge logic preserves what is there — but `--dry-run`
+ * was accepted by the CLI and never reached here, so the only way to find out
+ * what would be touched was to let it happen.
+ *
  * @param {string} target - 'cursor' | 'vscode' | 'claude' | 'all'
  * @param {object} [options]
+ * @param {string} [options.root]
+ * @param {boolean} [options.dryRun] - report the files without writing them
  * @returns {object} Summary of scaffolded files
  */
 export function scaffoldIdeConfig(target = "all", options = {}) {
   const root = options.root || resolveRoot();
+  const dryRun = Boolean(options.dryRun);
   const validTargets = new Set(["cursor", "vscode", "claude", "all"]);
 
+  /** Write unless this is a rehearsal; the directory is only made when writing. */
+  const writeUnlessRehearsing = (dir, file, contents) => {
+    if (dryRun) return;
+    try {
+      mkdirSync(dir, { recursive: true });
+    } catch (_) {}
+    writeFileSync(file, contents, "utf-8");
+  };
+
   const normTarget = (target || "all").toLowerCase();
   if (!validTargets.has(normTarget)) {
     throw new IdeScaffoldError(`Invalid target '${target}'. Allowed targets: cursor, vscode, claude, all`);
@@ -29,10 +47,6 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
   // Target: Cursor (.cursor/mcp.json)
   if (normTarget === "cursor" || normTarget === "all") {
     const cursorDir = join(root, ".cursor");
-    try {
-      mkdirSync(cursorDir, { recursive: true });
-    } catch (_) {}
-
     const cursorConfigPath = join(cursorDir, "mcp.json");
     let existingConfig = {};
     if (existsSync(cursorConfigPath)) {
@@ -52,17 +66,13 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
       },
     };
 
-    writeFileSync(cursorConfigPath, JSON.stringify(updatedCursorConfig, null, 2), "utf-8");
+    writeUnlessRehearsing(cursorDir, cursorConfigPath, JSON.stringify(updatedCursorConfig, null, 2));
     results.push({ target: "cursor", file: ".cursor/mcp.json", ok: true });
   }
 
   // Target: VS Code (.vscode/tasks.json)
   if (normTarget === "vscode" || normTarget === "all") {
     const vscodeDir = join(root, ".vscode");
-    try {
-      mkdirSync(vscodeDir, { recursive: true });
-    } catch (_) {}
-
     const vscodeTasksPath = join(vscodeDir, "tasks.json");
     let existingConfig = { version: "2.0.0", tasks: [] };
     if (existsSync(vscodeTasksPath)) {
@@ -110,17 +120,13 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
       tasks: updatedTasks,
     };
 
-    writeFileSync(vscodeTasksPath, JSON.stringify(updatedVsCodeConfig, null, 2), "utf-8");
+    writeUnlessRehearsing(vscodeDir, vscodeTasksPath, JSON.stringify(updatedVsCodeConfig, null, 2));
     results.push({ target: "vscode", file: ".vscode/tasks.json", ok: true });
   }
 
   // Target: Claude Desktop (claude_desktop_config.json snippet helper)
   if (normTarget === "claude" || normTarget === "all") {
     const agentDir = join(root, ".agent");
-    try {
-      mkdirSync(agentDir, { recursive: true });
-    } catch (_) {}
-
     const snippetPath = join(agentDir, "claude_desktop_config.snippet.json");
     const claudeSnippet = {
       mcpServers: {
@@ -131,9 +137,9 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
       },
     };
 
-    writeFileSync(snippetPath, JSON.stringify(claudeSnippet, null, 2), "utf-8");
+    writeUnlessRehearsing(agentDir, snippetPath, JSON.stringify(claudeSnippet, null, 2));
     results.push({ target: "claude", file: ".agent/claude_desktop_config.snippet.json", ok: true });
   }
 
-  return { ok: true, target: normTarget, results };
+  return { ok: true, target: normTarget, dryRun, results };
 }

package/src/ops/next-step.mjs

@@ -1,7 +1,32 @@
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { isTaskFile } from "../engine.mjs";
+import { probeProvider } from "../provider-readiness.mjs";
+
+/**
+ * The provider named in `.agent/config.yml`, without paying for a full
+ * `loadConfig()` (which detects the stack and shells out to git).
+ *
+ * A bare `agentctl` invocation has to stay instant, and the only field this
+ * advisor needs is one line of YAML.
+ *
+ * @param {string} root
+ * @returns {string}
+ */
+function readConfiguredProvider(root) {
+  for (const name of ["config.yml", "jules.yml"]) {
+    const file = join(root, ".agent", name);
+    if (!existsSync(file)) continue;
+    try {
+      const match = readFileSync(file, "utf-8").match(/^provider:\s*["']?([\w.-]+)["']?\s*$/m);
+      if (match) return match[1];
+    } catch (_) {
+      // An unreadable config is already reported by the `init` branch above.
+    }
+  }
+  return "jules";
+}
 
 /**
  * Work out the one thing the operator should do next.
@@ -52,13 +77,19 @@ export function resolveNextStep(root, env = process.env) {
     };
   }
 
-  if (!env.JULES_API_KEY && !env.GEMINI_API_KEY) {
+  // Which credential (or binary) is missing depends entirely on the provider
+  // the repository selected. Asking for JULES_API_KEY in a repository driving
+  // `claude-code` told the operator to fix something that was never broken.
+  const providerName = readConfiguredProvider(root);
+  const probe = probeProvider(providerName, { env });
+  if (!probe.ready) {
     return {
-      id: "key",
-      headline: "No provider API key in the environment",
-      detail:
-        "The key is read from the environment only — never written to config and never sent anywhere but the provider. Until it is set you can still run `agentctl gate` and `--dry-run` dispatches locally.",
-      command: "export JULES_API_KEY=...",
+      id: "provider",
+      headline: probe.known
+        ? `Provider '${probe.name}' is not usable yet`
+        : `Provider '${probe.name}' is not a built-in preset`,
+      detail: `${probe.reason} Until it is resolved you can still run \`agentctl gate\` and \`--dry-run\` dispatches locally — every verification gate works with no provider at all.`,
+      command: probe.remedy,
       blocking: false,
     };
   }

package/src/ops/verify-output.mjs

@@ -0,0 +1,38 @@
+/**
+ * Choose what to show the operator from a failed stage's captured streams.
+ *
+ * stderr is where a failing suite says what it expected; stdout is where
+ * several runners (node:test among them) put the whole report — assertion text
+ * and stack included.
+ *
+ * Preferring stderr outright discarded all of that whenever stderr held so much
+ * as the spawn wrapper's own "Command failed: npm test", which it always does.
+ * The operator was shown a line naming the command they had just typed, and
+ * nothing about which test failed or why. A wrapper line is not diagnostic
+ * output: when that is all stderr has, stdout is the report.
+ *
+ * Lives in src/ rather than in the CLI script so it can be imported and tested
+ * without executing the CLI, which runs on import.
+ *
+ * @param {{ stdout?: string, stderr?: string }} failure
+ * @returns {string}
+ */
+export function selectFailureOutput(failure = {}) {
+  const rawStderr = (failure.stderr || "").trim();
+  const rawStdout = (failure.stdout || "").trim();
+  if (!rawStderr) return rawStdout;
+
+  const stderrIsWrapperOnly = rawStderr
+    .split("\n")
+    .every((line) => line.trim() === "" || /^(command failed|error: command failed|npm err!?)/i.test(line.trim()));
+
+  if (stderrIsWrapperOnly && rawStdout) return rawStdout;
+  if (rawStdout && rawStdout !== rawStderr) {
+    // Both carry something real, so show both rather than guessing which runner
+    // this is. stderr goes last on purpose: the caller keeps only the tail, and
+    // when stderr has real content it is nearly always the failure itself —
+    // putting the runner's banner after it would spend the cap on noise.
+    return `${rawStdout}\n${rawStderr}`;
+  }
+  return rawStderr;
+}

package/src/profiles.mjs

@@ -0,0 +1,188 @@
+/**
+ * Verification profiles: one word in `.agent/config.yml` that turns the kit's
+ * verification primitives on as a coherent set.
+ *
+ * The kit ships mutation testing, V8 diff coverage, flakiness probing and
+ * anti-tamper detection, and every one of them was reachable only by knowing
+ * the command exists and typing it by hand. A repository that scaffolded a
+ * default config got exactly one gate — `npm test` — and none of the rest, so
+ * the capability shipped and then sat idle. A profile is the shortest sentence
+ * that says how hard this repository wants its agents verified.
+ *
+ * Profiles are expanded at load time (see `loadConfig`), not frozen into the
+ * scaffolded YAML, so the stage list stays correct when the stack changes and
+ * improves when the kit does.
+ */
+
+/** Ordered weakest to strictest; `standard` is the default for a fresh repo. */
+export const PROFILE_NAMES = ["minimal", "standard", "max"];
+
+export const PROFILE_DESCRIPTIONS = {
+  minimal: "Tests only. For a slow suite, an unfamiliar stack, or a first day with the kit.",
+  standard: "Lint, tests, build, plus anti-tamper on the diff. The everyday gate.",
+  max: "Everything mechanical: adds mutation scoring, diff coverage, and flakiness probing.",
+};
+
+/**
+ * Stacks whose test command runs on Node and therefore honours
+ * `NODE_V8_COVERAGE`, which is how `assert:diff-coverage` collects data.
+ *
+ * Bun and Deno are deliberately absent: they run JavaScript but do not emit V8
+ * coverage into that directory, so the assertion would find no coverage maps
+ * and fail every diff for a reason that has nothing to do with the diff.
+ */
+const V8_COVERAGE_STACKS = new Set(["node", "turbo", "pnpm", "nx", "react-native", "hardhat"]);
+
+/**
+ * Build the full verification pipeline for a profile.
+ *
+ * Returns the *complete* stage list, not an addendum: `gate()` replaces its
+ * built-in pipeline wholesale when `verify.stages` is present, so a profile
+ * that emitted only its extra assertions would silently drop the tests.
+ *
+ * @param {string} profile - one of {@link PROFILE_NAMES}
+ * @param {object} ctx
+ * @param {string} [ctx.stack] - detected stack id (see `detectPolyglotStack`)
+ * @param {{setup?: string, lint?: string, test?: string, unit?: string, e2e?: string, build?: string, policy?: object}} [ctx.verify]
+ * @returns {{ profile: string, stages: object[], skipped: Array<{id: string, reason: string}> }}
+ */
+export function buildProfileStages(profile, ctx = {}) {
+  const name = PROFILE_NAMES.includes(String(profile || "").toLowerCase())
+    ? String(profile).toLowerCase()
+    : "standard";
+  const verify = ctx.verify || {};
+  const stack = ctx.stack || "unknown";
+  const network = verify.policy?.networkAccess || "allow";
+  const testCmd = verify.test || verify.unit || "";
+
+  const stages = [];
+  const skipped = [];
+
+  // Dependency install always runs first when the stack declares one; without
+  // it every later stage fails on a missing toolchain rather than on the code.
+  if (verify.setup) {
+    stages.push({ id: "setup", kind: "setup", cmd: verify.setup, required: true, networkAccess: "allow" });
+  }
+
+  if (name !== "minimal" && verify.lint) {
+    stages.push({ id: "lint", kind: "lint", cmd: verify.lint, required: true, networkAccess: network });
+  }
+
+  if (testCmd) {
+    stages.push({ id: "unit", kind: "test", cmd: testCmd, required: true, networkAccess: network });
+  } else {
+    skipped.push({
+      id: "unit",
+      reason: "No test command is configured or detectable — set verify.test in .agent/config.yml.",
+    });
+  }
+
+  if (name !== "minimal" && verify.e2e) {
+    stages.push({ id: "e2e", kind: "e2e", cmd: verify.e2e, required: true, networkAccess: "allow" });
+  }
+
+  if (name !== "minimal" && verify.build) {
+    stages.push({ id: "build", kind: "build", cmd: verify.build, required: true, networkAccess: network });
+  }
+
+  // Anti-tamper is diff-based and language-agnostic: it costs nothing to run
+  // and it is the one check an agent under pressure to go green will trip.
+  if (name !== "minimal") {
+    stages.push({ id: "anti-tamper", kind: "assert", assert: "test-integrity", required: true });
+  }
+
+  if (name === "max") {
+    // Mutation operators are C-family (`===`, `&&`, `++`, `true`), so the score
+    // is strongest on JS/TS, Go, Rust, Java, C#, PHP, Swift and Dart, and
+    // weaker on Python/Ruby where the keywords differ. It is still safe
+    // everywhere: it only ever mutates lines the diff added, and a diff with no
+    // mutable operators scores 100 and passes.
+    stages.push({
+      id: "mutation",
+      kind: "assert",
+      assert: "mutation",
+      minScore: 60,
+      maxMutants: 20,
+      testCmd,
+      required: true,
+    });
+
+    if (V8_COVERAGE_STACKS.has(stack)) {
+      stages.push({
+        id: "diff-coverage",
+        kind: "assert",
+        assert: "diff-coverage",
+        minCoverage: 80,
+        testCmd,
+        required: true,
+      });
+    } else {
+      skipped.push({
+        id: "diff-coverage",
+        reason: `Diff coverage reads NODE_V8_COVERAGE, which stack '${stack}' does not produce.`,
+      });
+    }
+
+    // Three passes is the cheapest count that can distinguish "passed" from
+    // "passed this time": a single alternation is enough to quarantine.
+    stages.push({
+      id: "stability",
+      kind: "assert",
+      assert: "test-stability",
+      repeat: 3,
+      minPassRate: 1.0,
+      cmd: testCmd,
+      required: true,
+    });
+
+    // `assert:event-loop-lag` is deliberately not here. It measures the
+    // orchestrator's own loop while it blocks on a synchronous child process,
+    // so against a spawned test command it reports the blocking duration rather
+    // than the application's latency. It stays available as an explicit stage
+    // for repositories that know what they are measuring.
+    skipped.push({
+      id: "event-loop-lag",
+      reason: "Opt-in only: meaningful for in-process latency targets, not for a spawned test command.",
+    });
+  }
+
+  return { profile: name, stages, skipped };
+}
+
+/**
+ * The pipeline `gate()` runs when no profile and no explicit stages are set:
+ * every verification command the stack resolved, in dependency order.
+ *
+ * Lives here rather than inline in `gate()` so that `agentctl profile` can show
+ * an operator what will actually run without reimplementing — and drifting
+ * from — the sequence the gate uses.
+ *
+ * @param {{setup?: string, lint?: string, test?: string, unit?: string, fuzz?: string, invariant?: string, e2e?: string, build?: string, policy?: object}} verify
+ * @returns {object[]}
+ */
+export function buildDefaultStages(verify = {}) {
+  const network = verify.policy?.networkAccess || "allow";
+  const stages = [];
+  if (verify.setup) stages.push({ id: "setup", kind: "setup", cmd: verify.setup, required: true, networkAccess: "allow" });
+  if (verify.lint) stages.push({ id: "lint", kind: "lint", cmd: verify.lint, required: true, networkAccess: network });
+  if (verify.test || verify.unit) {
+    stages.push({ id: "unit", kind: "test", cmd: verify.test || verify.unit, required: true, networkAccess: network });
+  }
+  if (verify.fuzz) stages.push({ id: "fuzz", kind: "fuzz", cmd: verify.fuzz, required: true, networkAccess: network });
+  if (verify.invariant) stages.push({ id: "invariant", kind: "invariant", cmd: verify.invariant, required: true, networkAccess: network });
+  if (verify.e2e) stages.push({ id: "e2e", kind: "e2e", cmd: verify.e2e, required: true, networkAccess: "allow" });
+  if (verify.build) stages.push({ id: "build", kind: "build", cmd: verify.build, required: true, networkAccess: network });
+  return stages;
+}
+
+/**
+ * Short human-readable summary of what a profile will run, for `init` output
+ * and `doctor`.
+ *
+ * @param {ReturnType<typeof buildProfileStages>} plan
+ * @returns {string}
+ */
+export function describeProfilePlan(plan) {
+  const ids = plan.stages.map((s) => s.id);
+  return ids.length ? ids.join(" → ") : "(nothing to run)";
+}