dev-loops 0.4.0 → 0.5.0

package/scripts/github/probe-copilot-review.mjs

@@ -3,6 +3,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, parseJsonText, parseReviewThreads } from "../_core-helpers.mjs";
 import { parseArgs } from "node:util";
 import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import {
   DEFAULT_POLL_INTERVAL_MS,
@@ -24,6 +25,10 @@ Required:
 Output (stdout, JSON):
   { "ok": true, "status": "changed"|"timeout"|"idle", "repo": "...", "pr": N, "attempts": N,
     "newComments": [...], "newReviews": [...], "newIssueComments": [...] }
+Concise mode:
+  --concise, --summary      Human-readable summary: status, attempts, new-activity
+                            counts, AND the current round's new Copilot comment bodies.
+${JQ_OUTPUT_USAGE}
 Activity statuses:
   changed    Fresh Copilot review activity found (check newComments/newReviews/newIssueComments)
   timeout    Watch period elapsed with no fresh Copilot activity
@@ -91,7 +96,14 @@ function rejectRemovedFlag(token) {
 export function parseWatchCliArgs(argv) {
   const { tokens } = parseArgs({
     args: [...argv],
-    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, pr: { type: "string" } },
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      concise: { type: "boolean" },
+      summary: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
     allowPositionals: true,
     strict: false,
     tokens: true,
@@ -102,6 +114,9 @@ export function parseWatchCliArgs(argv) {
     pr: undefined,
     pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
     timeoutMs: COPILOT_REVIEW_WAIT_TIMEOUT_MS,
+    concise: false,
+    jq: undefined,
+    silent: false,
   };
   for (const token of tokens) {
     if (token.kind === "positional") {
@@ -125,6 +140,18 @@ export function parseWatchCliArgs(argv) {
       options.pr = parsePositiveInteger(requireTokenValue(token, parseError), "--pr", parseError);
       continue;
     }
+    if (token.name === "concise" || token.name === "summary") {
+      options.concise = true;
+      continue;
+    }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -311,6 +338,37 @@ export function buildPollDelayMs(watchStartedAtMs, timeoutMs, pollIntervalMs, at
   const scheduledAtMs = watchStartedAtMs + Math.min(timeoutMs, attempt * pollIntervalMs);
   return Math.max(0, scheduledAtMs - nowMs);
 }
+// Human-readable concise summary of a probe result, including the current
+// round's new Copilot comment bodies (the field `loop info --pr` omits).
+export function formatProbeConcise(result) {
+  const newComments = result.newComments ?? [];
+  const newReviews = result.newReviews ?? [];
+  const newIssueComments = result.newIssueComments ?? [];
+  const lines = [
+    `Copilot probe: PR #${result.pr} (${result.repo})`,
+    `  status:        ${result.status}`,
+    `  attempts:      ${result.attempts}`,
+    `  new threadComments: ${newComments.length}`,
+    `  new reviews:        ${newReviews.length}`,
+    `  new issueComments:  ${newIssueComments.length}`,
+  ];
+  const bodies = [
+    ...newReviews.map((r) => ({ kind: "review", body: r.body })),
+    ...newComments.map((c) => ({ kind: "threadComment", body: c.body })),
+    ...newIssueComments.map((c) => ({ kind: "issueComment", body: c.body })),
+  ].filter((entry) => typeof entry.body === "string" && entry.body.trim().length > 0);
+  if (bodies.length > 0) {
+    lines.push("  new Copilot comment bodies this round:");
+    for (const entry of bodies) {
+      const indented = entry.body.trim().split("\n").map((l) => `      ${l}`).join("\n");
+      lines.push(`    [${entry.kind}]`);
+      lines.push(indented);
+    }
+  } else {
+    lines.push("  new Copilot comment bodies this round: (none)");
+  }
+  return lines.join("\n");
+}
 export async function runCli(
   argv = process.argv.slice(2),
   {
@@ -325,10 +383,18 @@ export async function runCli(
     return;
   }
   const result = await watchCopilotReview(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  if (options.concise && options.jq === undefined && !options.silent) {
+    stdout.write(`${formatProbeConcise(result)}\n`);
+    return result.ok === false ? 1 : 0;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout });
 }
 if (isDirectCliRun(import.meta.url)) {
-  runCli().catch((error) => {
+  runCli().then((code) => {
+    if (typeof code === "number") {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
     process.stderr.write(`${formatCliError(error)}\n`);
     process.exitCode = 1;
   });

package/scripts/github/upsert-checkpoint-verdict.mjs

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { loadDevLoopConfig, resolveGateConfig, resolveRefinementConfig } from "@dev-loops/core/config";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { truncateText } from "@dev-loops/core/bash-exit-one";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
@@ -105,9 +106,11 @@ exists on a different head SHA (the old comment is stale for the current head).
 Error output (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }
   { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error, gh failure, or contradictory gate evidence`.trim();
+  1  Argument error, gh failure, or contradictory gate evidence
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 function rejectRemovedFlag(token) {
   throw parseError(
@@ -258,6 +261,7 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       "findings-severity-counts": { type: "string" },
       "execution-mode": { type: "string" },
       "inline-reason": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -277,6 +281,8 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
     findingsSeverityCounts: undefined,
     executionMode: undefined,
     inlineReason: undefined,
+    jq: undefined,
+    silent: false,
   };
   for (const token of tokens) {
     if (token.kind === "positional") {
@@ -385,6 +391,14 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       options.inlineReason = smartTruncate(reason, MAX_GATE_COMMENT_EXCERPT_LENGTH);
       continue;
     }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   // Default execution mode to inline_single_agent when omitted. inlineReason is
@@ -1286,10 +1300,11 @@ async function main() {
     const result = await upsertCheckpointVerdict(options);
     // Emit the inline-execution warning only on success so the JSON error
     // envelope on stderr stays clean and machine-parseable on failures.
-    if (inlineWarning) {
+    // Suppress it under --silent, which contracts to zero output (exit code only).
+    if (inlineWarning && !options.silent) {
       process.stderr.write(`${inlineWarning}\n`);
     }
-    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     process.stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
     process.exitCode = 1;

package/scripts/lib/jq-output.mjs

@@ -0,0 +1,297 @@
+// Shared --jq / --silent output helper for the JSON-emitting dev-loops scripts
+// (issue #981, subsumes #963). One helper applied uniformly so the loop never
+// falls back to `gh api | python3` or inline `node -e` to read tool JSON.
+//
+// Convention (also documented in skills/dev-loop/SKILL.md):
+//   prefer the dev-loops subcommand
+//     -> `--silent`/`-s` for a yes/no status check (zero output, exit code only)
+//     -> `--jq <filter>` to extract a field from the result
+//     -> `gh --jq` on a raw gh call
+//     -> NEVER `| python3` or `node -e`.
+//
+// jq subset (NOT full jq — fails closed clearly on anything outside this):
+//   .                identity
+//   .field           field access (also .a.b.c chains)
+//   .field[]         iterate an array field
+//   .[]              iterate an array / object values
+//   .[N] / .field[N] index access
+//   a | b            pipe
+//   select(<pred>)   filter the current value(s) by a predicate
+//   length           count of array/string/object
+//   keys             sorted object keys (or array indices)
+//   predicates inside select: .x == <lit>, !=, <, <=, >, >=, and a bare path
+//                  (truthy test). <lit> is a JSON string/number/true/false/null.
+// Anything else -> JqFilterError (fail closed).
+
+export class JqFilterError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "JqFilterError";
+    this.isJqFilterError = true;
+  }
+}
+
+// A jq "stream" is an array of values (jq filters are many-valued). We thread an
+// array through each pipe stage. Identity is [value].
+
+function parseLiteral(token) {
+  const trimmed = token.trim();
+  if (trimmed === "true") return { ok: true, value: true };
+  if (trimmed === "false") return { ok: true, value: false };
+  if (trimmed === "null") return { ok: true, value: null };
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return { ok: true, value: Number(trimmed) };
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length >= 2)
+  ) {
+    return { ok: true, value: trimmed.slice(1, -1) };
+  }
+  return { ok: false };
+}
+
+// Resolve a single-value path expression like `.`, `.a.b`, `.a[0].b`, `.[2]`.
+// Returns undefined for a missing path (jq yields null; we map missing->undefined
+// then callers coerce). Throws JqFilterError on malformed path syntax.
+function resolvePath(value, path) {
+  const trimmed = path.trim();
+  if (trimmed === "") {
+    // An empty path is never valid jq (no empty filter). Fail closed so
+    // malformed predicates like `select()` or `==5` don't pass as identity.
+    throw new JqFilterError("Empty path expression");
+  }
+  if (trimmed === ".") return value;
+  if (!trimmed.startsWith(".")) {
+    throw new JqFilterError(`Unsupported path (must start with '.'): ${path}`);
+  }
+  // Tokenize into .field and [index] steps.
+  const stepRe = /\.([A-Za-z_][A-Za-z0-9_]*)|\[(\d+)\]/g;
+  let cursor = value;
+  // Root index access (`.[N]`) starts with a leading '.' that is not part of any
+  // step token; consume it so the first `[N]` match aligns at the cursor.
+  let lastIndex = trimmed.startsWith(".[") ? 1 : 0;
+  stepRe.lastIndex = lastIndex;
+  let match;
+  let consumedAny = false;
+  while ((match = stepRe.exec(trimmed)) !== null) {
+    if (match.index !== lastIndex) {
+      throw new JqFilterError(`Unsupported path syntax near: ${trimmed.slice(lastIndex)}`);
+    }
+    lastIndex = stepRe.lastIndex;
+    consumedAny = true;
+    if (cursor === undefined || cursor === null) {
+      cursor = undefined;
+      continue;
+    }
+    if (match[1] !== undefined) {
+      cursor = typeof cursor === "object" && !Array.isArray(cursor) ? cursor[match[1]] : undefined;
+    } else {
+      const idx = Number(match[2]);
+      cursor = Array.isArray(cursor) ? cursor[idx] : undefined;
+    }
+  }
+  if (!consumedAny || lastIndex !== trimmed.length) {
+    throw new JqFilterError(`Unsupported path syntax: ${path}`);
+  }
+  return cursor;
+}
+
+function evaluatePredicate(value, predicate) {
+  const cmpRe = /^(.*?)(==|!=|<=|>=|<|>)(.*)$/;
+  const m = predicate.match(cmpRe);
+  if (!m) {
+    // Bare path => truthy test.
+    const resolved = resolvePath(value, predicate);
+    return resolved !== undefined && resolved !== null && resolved !== false;
+  }
+  const [, leftRaw, op, rightRaw] = m;
+  // jq maps a missing path to null; resolvePath yields undefined -> normalize.
+  const resolvedLeft = resolvePath(value, leftRaw);
+  const left = resolvedLeft === undefined ? null : resolvedLeft;
+  const lit = parseLiteral(rightRaw);
+  if (!lit.ok) {
+    throw new JqFilterError(`Unsupported predicate operand: ${rightRaw.trim()}`);
+  }
+  const right = lit.value;
+  switch (op) {
+    case "==":
+      return left === right;
+    case "!=":
+      return left !== right;
+    case "<":
+    case "<=":
+    case ">":
+    case ">=": {
+      // jq never coerces across types (number < string always); JS would. Fail
+      // closed when operand types differ so numeric-string fields don't misfire.
+      if (typeof left !== typeof right) {
+        throw new JqFilterError(`Cannot order-compare ${typeof left} and ${typeof right}`);
+      }
+      if (op === "<") return left < right;
+      if (op === "<=") return left <= right;
+      if (op === ">") return left > right;
+      return left >= right;
+    }
+    default:
+      throw new JqFilterError(`Unsupported operator: ${op}`);
+  }
+}
+
+// Apply one pipe stage to a stream (array of values), returning a new stream.
+function applyStage(stream, rawStage) {
+  const stage = rawStage.trim();
+  if (stage === "") {
+    throw new JqFilterError("Empty filter stage");
+  }
+  if (stage === "length") {
+    return stream.map((v) => {
+      if (Array.isArray(v) || typeof v === "string") return v.length;
+      if (v && typeof v === "object") return Object.keys(v).length;
+      throw new JqFilterError("length: input must be array, string, or object");
+    });
+  }
+  if (stage === "keys") {
+    return stream.map((v) => {
+      if (Array.isArray(v)) return v.map((_, i) => i);
+      if (v && typeof v === "object") return Object.keys(v).sort();
+      throw new JqFilterError("keys: input must be array or object");
+    });
+  }
+  const selectMatch = stage.match(/^select\((.*)\)$/);
+  if (selectMatch) {
+    return stream.filter((v) => evaluatePredicate(v, selectMatch[1]));
+  }
+  // Top-level comparison expression yields a boolean per input (e.g. .x=="y").
+  if (/(==|!=|<=|>=|<|>)/.test(stage)) {
+    return stream.map((v) => evaluatePredicate(v, stage));
+  }
+  // Iteration: a path ending in [] (incl. bare .[]).
+  if (stage === ".[]") {
+    return stream.flatMap((v) => iterate(v));
+  }
+  if (stage.endsWith("[]")) {
+    const base = stage.slice(0, -2);
+    return stream.flatMap((v) => iterate(resolvePath(v, base)));
+  }
+  // Plain path access (single value per input).
+  return stream.map((v) => resolvePath(v, stage));
+}
+
+function iterate(v) {
+  if (Array.isArray(v)) return v;
+  if (v && typeof v === "object") return Object.values(v);
+  throw new JqFilterError("Cannot iterate (.[]) over a non-array/object value");
+}
+
+// Split on top-level pipes, ignoring | inside quotes or parentheses.
+function splitPipes(filter) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let current = "";
+  for (const ch of filter) {
+    if (quote) {
+      current += ch;
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      current += ch;
+      continue;
+    }
+    if (ch === "(") depth += 1;
+    if (ch === ")") depth -= 1;
+    if (ch === "|" && depth === 0) {
+      parts.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  parts.push(current);
+  return parts;
+}
+
+// Evaluate a jq-subset filter against a value. Returns the jq "stream" (array of
+// result values). Throws JqFilterError on unsupported syntax.
+export function evaluateJqFilter(value, filter) {
+  if (typeof filter !== "string" || filter.trim() === "") {
+    throw new JqFilterError("Empty --jq filter");
+  }
+  let stream = [value];
+  for (const stage of splitPipes(filter)) {
+    stream = applyStage(stream, stage);
+  }
+  return stream;
+}
+
+// jq truthiness for --silent: matches `jq -e` exit semantics — the status is
+// based on the LAST output value (empty output is falsy; a value is truthy
+// unless it is null or false).
+function streamIsTruthy(stream) {
+  if (stream.length === 0) return false;
+  const last = stream[stream.length - 1];
+  return last !== null && last !== false && last !== undefined;
+}
+
+function renderJqStream(stream) {
+  // jq prints each value on its own line; single value => just that value.
+  return stream
+    .map((v) => (typeof v === "string" ? v : JSON.stringify(v ?? null)))
+    .join("\n");
+}
+
+// Standard option block to merge into a parseArgs `options` map so every script
+// exposes the same flags.
+export const JQ_OUTPUT_PARSE_OPTIONS = {
+  jq: { type: "string" },
+  silent: { type: "boolean", short: "s" },
+};
+
+// Shared USAGE fragment so every script documents the flags identically.
+export const JQ_OUTPUT_USAGE = `Output filtering:
+  --jq <filter>             Apply a jq-subset filter to the result and print it
+                            (field access, .[]/.[N], pipes, select(...), ==,!=,<,<=,>,>=, length, keys).
+                            Invalid filter fails closed (stderr + exit 2).
+  --silent, -s              Suppress stdout; map result to exit code only
+                            (0 = pass/truthy, 1 = fail/falsy). Composes with --jq as a predicate.`;
+
+// Apply --jq / --silent to a result object and emit. Returns the exit code the
+// CLI should use (0 success / truthy, 1 falsy or non-ok, 2 invalid filter).
+// Without jq/silent the result is printed verbatim as JSON (unchanged shape).
+//
+//   ok: success of the underlying result (defaults to result.ok !== false).
+export function emitResult(
+  result,
+  {
+    jq = undefined,
+    silent = false,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    ok = result?.ok !== false,
+  } = {},
+) {
+  if (jq !== undefined) {
+    let stream;
+    try {
+      stream = evaluateJqFilter(result, jq);
+    } catch (error) {
+      if (error instanceof JqFilterError) {
+        // Fail closed, distinct from a clean "predicate false". Exit 2.
+        stderr.write(`${JSON.stringify({ ok: false, error: `--jq: ${error.message}` })}\n`);
+        return 2;
+      }
+      throw error;
+    }
+    if (silent) {
+      return streamIsTruthy(stream) ? 0 : 1;
+    }
+    stdout.write(`${renderJqStream(stream)}\n`);
+    return ok ? 0 : 1;
+  }
+  if (silent) {
+    return ok ? 0 : 1;
+  }
+  stdout.write(`${JSON.stringify(result)}\n`);
+  return ok ? 0 : 1;
+}