jules-orchestrator-kit 0.32.4 → 0.32.6

package/scripts/doc-sync-check.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+
+/**
+ * Documentation / version consistency gate.
+ *
+ * Implements the `doc-sync-sentinel` preset advertised in src/wizard-init.mjs:
+ * asserts that package.json, bin/agentctl.mjs, README.md, ROADMAP_V1.md and
+ * CHANGELOG.md all agree on the current version, and that README's advertised
+ * test counts match what the suite actually reports.
+ *
+ * Runs as a blocking step in scripts/release.mjs. Standalone usage:
+ *   node scripts/doc-sync-check.mjs                 # runs the suite for counts
+ *   node scripts/doc-sync-check.mjs --tests 429 --suites 59
+ *   node scripts/doc-sync-check.mjs --json
+ *
+ * Exit codes: 0 = in sync, 1 = drift detected.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { resolveRoot } from "../src/config.mjs";
+
+/**
+ * Runs the unit suite and extracts the authoritative counts.
+ *
+ * README advertises *passing* tests, so `pass` — not `tests` — is the number
+ * the documentation claim is compared against. The two diverge as soon as the
+ * adversarial suite records a `todo` probe for a known gap.
+ *
+ * @param {string} root
+ * @returns {{ tests: number|null, pass: number|null, suites: number|null, todo: number|null }}
+ */
+export function measureTestCounts(root = process.cwd()) {
+  let out = "";
+  try {
+    out = execSync("npm test", { cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+  } catch (err) {
+    // A failing suite still prints its summary; parse whatever we got.
+    out = `${err.stdout || ""}${err.stderr || ""}`;
+  }
+  return parseTestCounts(out);
+}
+
+/**
+ * Parses node:test summary counters out of an already-captured run.
+ * Accepts both the spec reporter ("ℹ tests 452") and tap ("# tests 452").
+ * @param {string} out
+ * @returns {{ tests: number|null, pass: number|null, suites: number|null, todo: number|null }}
+ */
+export function parseTestCounts(out = "") {
+  const num = (key) => {
+    const m = String(out).match(new RegExp(`^[^\\n]*?(?:ℹ|#)\\s*${key}\\s+(\\d+)\\s*$`, "m"));
+    return m ? Number(m[1]) : null;
+  };
+  return { tests: num("tests"), pass: num("pass"), suites: num("suites"), todo: num("todo") };
+}
+
+function readIfExists(path) {
+  return existsSync(path) ? readFileSync(path, "utf-8") : null;
+}
+
+/**
+ * Verifies documentation is in sync with package.json and the real test counts.
+ * @param {string} [root]
+ * @param {object} [opts]
+ * @param {number} [opts.tests] Actual passing test count (measured if omitted).
+ * @param {number} [opts.suites] Actual suite count (measured if omitted).
+ * @returns {{ ok: boolean, version: string, checks: Array<{name: string, ok: boolean, detail: string}> }}
+ */
+export function checkDocSync(root = process.cwd(), opts = {}) {
+  const checks = [];
+  const add = (name, ok, detail) => checks.push({ name, ok, detail });
+
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+  const version = pkg.version;
+
+  // 1. bin/agentctl.mjs — VERSION const, help banner, `version` command output.
+  const cli = readIfExists(join(root, "bin", "agentctl.mjs"));
+  if (cli === null) {
+    add("agentctl present", false, "bin/agentctl.mjs not found");
+  } else {
+    const constMatch = cli.match(/export const VERSION\s*=\s*"([^"]+)"/);
+    add(
+      "agentctl VERSION const",
+      constMatch?.[1] === version,
+      constMatch ? `found "${constMatch[1]}", expected "${version}"` : "no `export const VERSION` found"
+    );
+
+    const stale = [...cli.matchAll(/agentctl v(\d+\.\d+\.\d+)/g)].map((m) => m[1]).filter((v) => v !== version);
+    add(
+      "agentctl banner/version strings",
+      stale.length === 0,
+      stale.length ? `stale version string(s): ${[...new Set(stale)].join(", ")}` : `all reference v${version}`
+    );
+  }
+
+  // 2. ROADMAP_V1.md — milestone header must name the shipped version, and no
+  //    already-released version may still be labelled "(Unreleased)".
+  const roadmap = readIfExists(join(root, "ROADMAP_V1.md"));
+  if (roadmap === null) {
+    add("ROADMAP present", false, "ROADMAP_V1.md not found");
+  } else {
+    const current = roadmap.match(/v(\d+\.\d+\.\d+)\s*\(Current Stable\)/);
+    add(
+      "ROADMAP Current Stable",
+      current?.[1] === version,
+      current ? `found v${current[1]}, expected v${version}` : "no `(Current Stable)` marker found"
+    );
+
+    const shipped = roadmap.match(/Shipped Milestones\s*\(v[\d.]+\s*[–-]\s*v(\d+\.\d+\.\d+)\)/);
+    add(
+      "ROADMAP Shipped range",
+      shipped?.[1] === version,
+      shipped ? `ends at v${shipped[1]}, expected v${version}` : "no `Shipped Milestones (…)` range found"
+    );
+
+    const unreleased = [...roadmap.matchAll(/v(\d+\.\d+\.\d+)\s*\(Unreleased\)/g)]
+      .map((m) => m[1])
+      .filter((v) => compareSemver(v, version) <= 0);
+    add(
+      "ROADMAP no stale (Unreleased)",
+      unreleased.length === 0,
+      unreleased.length
+        ? `v${unreleased.join(", v")} marked (Unreleased) but <= shipped v${version}`
+        : "no released version left marked (Unreleased)"
+    );
+  }
+
+  // 3. CHANGELOG.md — a released version needs a matching entry (release.mjs
+  //    extracts its notes from here, and silently falls back if it is missing).
+  const changelog = readIfExists(join(root, "CHANGELOG.md"));
+  if (changelog === null) {
+    add("CHANGELOG present", false, "CHANGELOG.md not found");
+  } else {
+    add(
+      "CHANGELOG entry",
+      changelog.includes(`## [${version}]`),
+      changelog.includes(`## [${version}]`) ? `## [${version}] found` : `no "## [${version}]" section`
+    );
+  }
+
+  // 4. README.md — advertised test counts and roadmap-table release labels.
+  const readme = readIfExists(join(root, "README.md"));
+  if (readme === null) {
+    add("README present", false, "README.md not found");
+  } else {
+    const claim = readme.match(/(\d+)\s+unit tests across\s+(\d+)\s+suites/);
+    const claimedTests = claim ? Number(claim[1]) : null;
+    const claimedSuites = claim ? Number(claim[2]) : null;
+
+    let { tests, suites } = opts;
+    if (tests === undefined || suites === undefined) {
+      const measured = measureTestCounts(root);
+      tests = tests ?? measured.pass;
+      suites = suites ?? measured.suites;
+    }
+
+    if (claimedTests === null) {
+      add("README test count", false, "no `N unit tests across M suites` claim found");
+    } else if (tests === null || suites === null) {
+      add("README test count", false, "could not measure actual test counts");
+    } else {
+      add(
+        "README test count",
+        claimedTests === tests && claimedSuites === suites,
+        `README claims ${claimedTests}/${claimedSuites} passing, suite reports ${tests}/${suites}`
+      );
+    }
+
+    const unreleasedRows = (readme.match(/\|\s*\*\*Unreleased\*\*\s*\*\(main\)\*\s*\|/g) || []).length;
+    add(
+      "README roadmap table labels",
+      unreleasedRows === 0,
+      unreleasedRows ? `${unreleasedRows} row(s) still labelled "Unreleased (main)"` : "no stale Unreleased rows"
+    );
+  }
+
+  // 5. Agent rule-file budgets. rules-lint has existed unwired, which is how
+  //    AGENTS.md silently drifted past its 10k character budget — agent rule
+  //    files are truncated by the model host, so an over-budget file loses
+  //    directives from the end without any error surfacing.
+  if (opts.skipRulesLint !== true) {
+    try {
+      execSync("node scripts/rules-lint.mjs", { cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+      add("agent rule budgets", true, "AGENTS.md and .agent/rules/ within char/line budgets");
+    } catch (err) {
+      const detail = `${err.stdout || ""}${err.stderr || ""}`
+        .split("\n")
+        .filter((l) => l.trim().startsWith("-"))
+        .map((l) => l.trim().replace(/^-\s*/, ""))
+        .join("; ");
+      add("agent rule budgets", false, detail || "rules-lint reported violations");
+    }
+  }
+
+  return { ok: checks.every((c) => c.ok), version, checks };
+}
+
+function compareSemver(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  }
+  return 0;
+}
+
+// ---- CLI ----
+const isMain = process.argv[1] && process.argv[1].endsWith("doc-sync-check.mjs");
+if (isMain) {
+  const argv = process.argv.slice(2);
+  const flag = (name) => {
+    const i = argv.indexOf(`--${name}`);
+    return i !== -1 && argv[i + 1] ? Number(argv[i + 1]) : undefined;
+  };
+
+  const root = resolveRoot();
+  const res = checkDocSync(root, { tests: flag("tests"), suites: flag("suites") });
+
+  if (argv.includes("--json")) {
+    console.log(JSON.stringify(res, null, 2));
+  } else {
+    console.log(`\n📐 Documentation Sync Gate (v${res.version})`);
+    console.log("-------------------------------------------------------");
+    for (const c of res.checks) {
+      console.log(`  ${c.ok ? "✅" : "❌"} ${c.name.padEnd(32)} ${c.detail}`);
+    }
+    console.log("-------------------------------------------------------");
+    console.log(res.ok ? "✅ Documentation is in sync.\n" : "❌ DOC SYNC GATE FAIL: documentation has drifted from package.json / test suite.\n");
+  }
+
+  process.exit(res.ok ? 0 : 1);
+}

package/scripts/release.mjs

@@ -26,16 +26,37 @@ const tagName = `v${version}`;
 console.log(`🚀 Automated Release Pipeline for ${pkg.name} (${tagName})`);
 console.log("-------------------------------------------------------");
 
-// 1. Verify test suite
+// 1. Verify test suite. Output is captured (not inherited) so the doc-sync gate
+//    below can reuse the counts instead of running the suite a second time.
 console.log("1. Running unit test verification suite...");
+let testOutput = "";
 try {
-  execSync("npm test", { cwd: root, stdio: "inherit" });
+  testOutput = execSync("npm test", { cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+  const summary = testOutput.match(/^[^\n]*?ℹ\s*(?:tests|suites|pass|fail|todo)\s+\d+\s*$/gm) || [];
+  summary.forEach((l) => console.log(`   ${l.trim()}`));
   console.log("   ✅ Test suite passed cleanly.\n");
 } catch (err) {
+  console.error(`${err.stdout || ""}${err.stderr || ""}`);
   console.error("❌ Release Aborted: Test suite failed.");
   process.exit(1);
 }
 
+// 1b. Documentation / version consistency gate (blocking).
+console.log("1b. Verifying documentation is in sync with package.json & test suite...");
+{
+  const { checkDocSync, parseTestCounts } = await import("./doc-sync-check.mjs");
+  const counts = parseTestCounts(testOutput);
+  const docRes = checkDocSync(root, { tests: counts.pass, suites: counts.suites });
+  for (const c of docRes.checks) {
+    console.log(`   ${c.ok ? "✅" : "❌"} ${c.name.padEnd(32)} ${c.detail}`);
+  }
+  if (!docRes.ok) {
+    console.error("\n❌ Release Aborted: documentation has drifted. Fix the ❌ rows above and re-run.");
+    process.exit(1);
+  }
+  console.log("   ✅ Documentation is in sync.\n");
+}
+
 // 2. Extract release notes from CHANGELOG.md
 console.log(`2. Extracting release notes for ${tagName} from CHANGELOG.md...`);
 let notes = "";

package/src/config.mjs

@@ -68,6 +68,41 @@ export function normalizePath(p) {
   return p.split(sep).join("/").replace(/\\/g, "/");
 }
 
+/**
+ * Reduces a repo-relative path to a canonical form for pattern matching:
+ * separators normalised, duplicate slashes collapsed, `.` segments dropped,
+ * `..` segments resolved, and any leading `./` or trailing `/` removed.
+ *
+ * Purely lexical — it never touches the filesystem, because the paths being
+ * matched may not exist locally (they can come from a diff or a task envelope).
+ * Leading `..` segments that would escape the repo root are preserved so the
+ * caller can still recognise and reject them.
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+export function canonicalizePath(p) {
+  const normalized = normalizePath(p).replace(/\/+/g, "/");
+  if (!normalized) return "";
+
+  const isAbsolutePosix = normalized.startsWith("/");
+  const out = [];
+  for (const segment of normalized.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      if (out.length > 0 && out[out.length - 1] !== "..") {
+        out.pop();
+      } else if (!isAbsolutePosix) {
+        out.push("..");
+      }
+      continue;
+    }
+    out.push(segment);
+  }
+
+  return (isAbsolutePosix ? "/" : "") + out.join("/");
+}
+
 export function resolveRoot(cwd = process.cwd()) {
   try {
     return execSync("git rev-parse --show-toplevel", { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
@@ -214,9 +249,19 @@ export function resolveVerify(root = process.cwd(), userVerify = {}) {
   const s = detectStack(root);
   return {
     setup: userVerify.setup ?? s.setupCmd ?? "",
+    lint: userVerify.lint ?? s.fmtCmd ?? "",
     test: userVerify.test ?? s.testCmd ?? "",
+    unit: userVerify.unit ?? userVerify.test ?? s.testCmd ?? "",
+    fuzz: userVerify.fuzz ?? s.fuzzCmd ?? "",
+    invariant: userVerify.invariant ?? s.invariantCmd ?? "",
+    e2e: userVerify.e2e ?? s.e2eCmd ?? "",
     teardown: userVerify.teardown ?? s.teardownCmd ?? "",
     build: userVerify.build ?? s.buildCmd ?? "",
+    policy: {
+      networkAccess: userVerify.policy?.networkAccess || (s.stack === "foundry" ? "forbidden" : "allow"),
+      offline: userVerify.policy?.offline ?? (s.stack === "foundry"),
+    },
+    stages: Array.isArray(userVerify.stages) ? userVerify.stages : null,
     server: userVerify.server ? {
       command: userVerify.server.command || "",
       url: userVerify.server.url || "http://localhost:3000",
@@ -273,6 +318,10 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
 
   const setupCmd = parsed.setup_cmd || parsed.verify?.setup || "";
   const testCmd = parsed.test_cmd || parsed.verify?.test || "";
+  const lintCmd = parsed.lint_cmd || parsed.verify?.lint || "";
+  const fuzzCmd = parsed.fuzz_cmd || parsed.verify?.fuzz || "";
+  const invariantCmd = parsed.invariant_cmd || parsed.verify?.invariant || "";
+  const e2eCmd = parsed.e2e_cmd || parsed.verify?.e2e || "";
   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;
@@ -303,11 +352,28 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     tier: activeTier,
     verify: {
       setup: setupCmd || autoVerify.setup || "",
+      lint: lintCmd || autoVerify.lint || "",
       test: testCmd || autoVerify.test,
+      unit: parsed.verify?.unit || testCmd || autoVerify.unit || autoVerify.test,
+      fuzz: fuzzCmd || autoVerify.fuzz || "",
+      invariant: invariantCmd || autoVerify.invariant || "",
+      e2e: e2eCmd || autoVerify.e2e || "",
       teardown: teardownCmd || autoVerify.teardown || "",
       build: buildCmd || autoVerify.build,
+      stages: parsed.verify?.stages || autoVerify.stages || null,
+      policy: parsed.verify?.policy || autoVerify.policy,
       timeoutMs: Number.isFinite(Number(verifyTimeoutMs)) ? Number(verifyTimeoutMs) : 60000,
     },
+    evidence: {
+      enabled: parsed.evidence?.enabled ?? true,
+      strictTestLock: parsed.evidence?.strict_test_lock ?? parsed.evidence?.strictTestLock ?? true,
+    },
+    router: {
+      enabled: parsed.router?.enabled ?? false,
+      fast: parsed.router?.fast || "gemini-flash",
+      complex: parsed.router?.complex || "",
+      threshold: Number.isFinite(Number(parsed.router?.threshold)) ? Number(parsed.router.threshold) : 0,
+    },
     scope: normalizeScope(parsed),
     limits: {
       ...DEFAULTS.limits,

package/src/dag-engine.mjs

@@ -406,3 +406,121 @@ export function resolveAffectedTests(modifiedFiles = [], options = {}) {
   return affected.size > 0 ? Array.from(affected) : null;
 }
 
+/**
+ * Loads tasks from the queue directory and executes them via DagExecutor.
+ * Supports task files with metadata (JSON or Markdown envelopes with dependsOn).
+ * @param {string} [root=process.cwd()]
+ * @param {Object} [options]
+ * @param {number} [options.concurrency=1]
+ * @param {boolean} [options.dryRun=false]
+ * @param {Function} [options.dispatchFn]
+ * @param {Object} [options.config]
+ * @returns {Promise<{ processed: number, results: Array<any> }>}
+ */
+export async function executeQueueDag(root = process.cwd(), options = {}) {
+  const { readdirSync, renameSync, mkdirSync } = await import("node:fs");
+  const { join, basename } = await import("node:path");
+
+  const queueDir = join(root, ".agent", "jules-queue");
+  const fallbackQueueDir = join(root, ".agent", "queue");
+  const actualQueueDir = existsSync(queueDir) ? queueDir : (existsSync(fallbackQueueDir) ? fallbackQueueDir : queueDir);
+  const completedDir = join(actualQueueDir, "completed");
+
+  if (!existsSync(actualQueueDir)) {
+    return { processed: 0, results: [] };
+  }
+  if (!existsSync(completedDir)) {
+    try {
+      mkdirSync(completedDir, { recursive: true });
+    } catch (_) {}
+  }
+
+  const files = readdirSync(actualQueueDir).filter((f) => {
+    if (f === "completed" || f.startsWith(".")) return false;
+    return f.endsWith(".md") || f.endsWith(".json") || f.endsWith(".task");
+  });
+
+  if (files.length === 0) {
+    return { processed: 0, results: [] };
+  }
+
+  const executor = new DagExecutor({ concurrency: options.concurrency || 1 });
+  const taskMap = new Map();
+  const results = [];
+
+  for (const file of files) {
+    if (basename(file) !== file) continue;
+    const fullPath = join(actualQueueDir, file);
+    const content = readFileSync(fullPath, "utf-8");
+    let taskId = file.replace(/\.(md|json|task)$/, "");
+    let dependsOn = [];
+    let title = taskId;
+    let prompt = content;
+    let role = undefined;
+    let tier = undefined;
+
+    // Check envelope header
+    const match = content.match(/<!--\s*JULES_TASK_ENVELOPE:\s*({[\s\S]*?})\s*-->/);
+    if (match) {
+      try {
+        const meta = JSON.parse(match[1]);
+        if (meta.id) taskId = meta.id;
+        if (meta.title) title = meta.title;
+        if (meta.role) role = meta.role;
+        if (meta.tier) tier = meta.tier;
+        if (Array.isArray(meta.dependsOn)) dependsOn = meta.dependsOn;
+        else if (typeof meta.dependsOn === "string") dependsOn = meta.dependsOn.split(",").map((s) => s.trim()).filter(Boolean);
+      } catch (_) {}
+    } else if (file.endsWith(".json")) {
+      try {
+        const parsed = JSON.parse(content);
+        if (parsed.id) taskId = parsed.id;
+        if (parsed.title) title = parsed.title;
+        if (parsed.prompt) prompt = parsed.prompt;
+        if (parsed.role) role = parsed.role;
+        if (parsed.tier) tier = parsed.tier;
+        if (Array.isArray(parsed.dependsOn)) dependsOn = parsed.dependsOn;
+        else if (typeof parsed.dependsOn === "string") dependsOn = parsed.dependsOn.split(",").map((s) => s.trim()).filter(Boolean);
+      } catch (_) {}
+    }
+
+    taskMap.set(taskId, { file, fullPath, taskId, title, prompt, role, tier, dependsOn });
+  }
+
+  // Register each task with its dependencies that are part of this queue run
+  for (const [taskId, t] of taskMap.entries()) {
+    const validDeps = t.dependsOn.filter((dep) => taskMap.has(dep));
+    executor.addTask({
+      id: taskId,
+      dependsOn: validDeps,
+      runner: async () => {
+        const srcPath = t.fullPath;
+        const taskObj = { id: t.taskId, title: t.title, prompt: t.prompt, role: t.role, tier: t.tier };
+        let session;
+        if (typeof options.dispatchFn === "function") {
+          session = await options.dispatchFn(taskObj, { root, config: options.config, dryRun: options.dryRun });
+        } else {
+          const { dispatch } = await import("./engine.mjs");
+          session = await dispatch(taskObj, { root, config: options.config, dryRun: options.dryRun });
+        }
+
+        if (session && session.ok === false) {
+          results.push({ file: t.file, taskId: t.taskId, ok: false, status: session.status, error: session.error, session });
+          throw new Error(`DAG Task '${t.taskId}' failed: ${session.error || session.status || "Unknown error"}`);
+        } else {
+          const dstPath = join(completedDir, t.file);
+          if (existsSync(srcPath)) {
+            if (!existsSync(dstPath)) {
+              renameSync(srcPath, dstPath);
+            }
+          }
+          results.push({ file: t.file, taskId: t.taskId, ok: true, session });
+        }
+      },
+    });
+  }
+
+  await executor.execute({ concurrency: options.concurrency || 1, root });
+  return { processed: results.length, results };
+}
+