dev-loops 0.4.0 → 0.6.0

package/scripts/github/fetch-ci-logs.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+
+const DEFAULT_TAIL_LINES = 200;
+
+const USAGE = `Usage: fetch-ci-logs.mjs --repo <owner/name> --pr <number> [--failed-only] [--tail <n>]
+Fetch the GitHub Actions CI run log tail for a PR's current head SHA. Thin wrapper
+over \`gh run list\` + \`gh run view --log\` — use this instead of an agent-level raw
+\`gh run view\` so the loop's internal-tooling record stays clean (#993). Complements
+probe-ci-status.mjs, which reports failed-check NAMES; this returns the LOG tail.
+(Siblings: list-issues.mjs, comment-issue.mjs.)
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --pr <number>                 Pull request number
+Optional:
+  --failed-only                 Only include runs whose conclusion is failure
+                                (default: all Actions runs for the head SHA)
+  --tail <n>                    Lines of log tail to return per run (default 200)
+Output (stdout, JSON):
+  { "ok": true, "repo": "owner/repo", "pr": 17, "headSha": "abc123",
+    "runs": [{ "runId": 42, "name": "ci", "conclusion": "failure", "logTail": "..." }] }
+Notes:
+  Actions-only (gh run is GitHub Actions). CircleCI / external commit-status logs
+  are NOT covered — use the provider's UI for those (probe-ci-status names the check).
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Success
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
+const parseError = buildParseError(USAGE);
+
+export function parseFetchCiLogsCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      "failed-only": { type: "boolean" },
+      tail: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    failedOnly: false,
+    tail: DEFAULT_TAIL_LINES,
+    jq: undefined,
+    silent: false,
+  };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
+      continue;
+    }
+    if (token.name === "failed-only") {
+      options.failedOnly = true;
+      continue;
+    }
+    if (token.name === "tail") {
+      const raw = requireTokenValue(token, parseError);
+      const value = Number(raw);
+      if (!Number.isInteger(value) || value < 1) {
+        throw parseError(`--tail must be a positive integer, got "${raw}"`);
+      }
+      options.tail = value;
+      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) {
+    throw parseError("Fetching CI logs requires both --repo <owner/name> and --pr <number>");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+async function ghJson(run, ghCommand, args, env, label) {
+  const result = await run(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`${label} failed: ${detail}`);
+  }
+  return parseJsonText(result.stdout, { label });
+}
+
+function tailLines(text, n) {
+  const lines = String(text).replace(/\r?\n$/u, "").split(/\r?\n/u);
+  return lines.slice(Math.max(0, lines.length - n)).join("\n");
+}
+
+export async function fetchCiLogs(options, { env = process.env, ghCommand = "gh", run = runChild } = {}) {
+  // 1. Resolve the PR's current head SHA — logs must be scoped to the head being
+  //    evaluated, not a stale push.
+  const pr = await ghJson(
+    run,
+    ghCommand,
+    ["pr", "view", String(options.pr), "--repo", options.repo, "--json", "headRefOid"],
+    env,
+    "gh pr view",
+  );
+  const headSha = typeof pr.headRefOid === "string" ? pr.headRefOid.trim() : "";
+  if (headSha.length === 0) {
+    throw new Error("gh pr view did not return headRefOid");
+  }
+
+  // 2. List Actions runs for that exact commit.
+  const runs = await ghJson(
+    run,
+    ghCommand,
+    ["run", "list", "--repo", options.repo, "--commit", headSha, "--json", "databaseId,name,conclusion,status"],
+    env,
+    "gh run list",
+  );
+  if (!Array.isArray(runs)) {
+    throw new Error("gh run list did not return a JSON array");
+  }
+  const selected = options.failedOnly
+    ? runs.filter((r) => String(r?.conclusion).toLowerCase() === "failure")
+    : runs;
+
+  // 3. Fetch each run's log tail. --log-failed restricts to failed steps when the
+  //    run failed; for non-failed runs it returns nothing, so fall back to --log.
+  const out = [];
+  for (const r of selected) {
+    const runId = Number.isInteger(r?.databaseId) ? r.databaseId : null;
+    if (runId === null) continue;
+    const conclusion = typeof r?.conclusion === "string" ? r.conclusion.toLowerCase() : null;
+    const logFlag = conclusion === "failure" ? "--log-failed" : "--log";
+    const logResult = await run(
+      ghCommand,
+      ["run", "view", String(runId), "--repo", options.repo, logFlag],
+      env,
+    );
+    // A log fetch failure for one run shouldn't abort the others (logs expire);
+    // record an empty tail with a note rather than throwing.
+    const logTail =
+      logResult.code === 0
+        ? tailLines(logResult.stdout, options.tail)
+        : `<log unavailable: ${logResult.stderr.trim() || `exit ${logResult.code}`}>`;
+    out.push({
+      runId,
+      name: typeof r?.name === "string" ? r.name : null,
+      conclusion,
+      logTail,
+    });
+  }
+  return { ok: true, repo: options.repo, pr: options.pr, headSha, runs: out };
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh", run = runChild } = {},
+) {
+  let options;
+  try {
+    options = parseFetchCiLogsCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await fetchCiLogs(options, { env, ghCommand, run });
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    return 1;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((code) => { process.exitCode = code; });
+}

package/scripts/github/list-issues.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+
+const STATES = new Set(["open", "closed", "all"]);
+
+const USAGE = `Usage: list-issues.mjs --repo <owner/name> [--state <open|closed|all>] [--label <l>] [--limit <n>]
+List/filter repository issues. Thin wrapper over \`gh issue list\` — use this instead
+of an agent-level raw \`gh issue list\` so the loop's internal-tooling record stays
+clean (#993). The queue tool lists the project board, not arbitrary issue queries;
+this fills that gap (siblings: comment-issue.mjs, fetch-ci-logs.mjs).
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+Optional:
+  --state <open|closed|all>     Issue state filter (default open)
+  --label <l>                   Filter by label (repeatable; AND-combined by gh)
+  --limit <n>                   Return at most <n> issues (default 30)
+Output (stdout, JSON):
+  { "ok": true, "issues": [{ "number": 17, "title": "...", "state": "open", "labels": ["bug"] }, ...] }
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Success
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
+const parseError = buildParseError(USAGE);
+
+export function parseListIssuesCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      state: { type: "string" },
+      label: { type: "string", multiple: true },
+      limit: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    state: "open",
+    labels: [],
+    limit: 30,
+    jq: undefined,
+    silent: false,
+  };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "state") {
+      const state = requireTokenValue(token, parseError).trim().toLowerCase();
+      if (!STATES.has(state)) {
+        throw parseError("--state must be one of: open, closed, all");
+      }
+      options.state = state;
+      continue;
+    }
+    if (token.name === "label") {
+      const label = requireTokenValue(token, parseError).trim();
+      if (label.length === 0) {
+        throw parseError("--label must be a non-empty string");
+      }
+      options.labels.push(label);
+      continue;
+    }
+    if (token.name === "limit") {
+      const raw = requireTokenValue(token, parseError);
+      const value = Number(raw);
+      if (!Number.isInteger(value) || value < 1) {
+        throw parseError(`--limit must be a positive integer, got "${raw}"`);
+      }
+      options.limit = value;
+      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) {
+    throw parseError("Listing issues requires --repo <owner/name>");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+// Returns a well-typed issue, or null if the gh entry is missing/invalid in any
+// required field. Callers filter the nulls so the emitted shape stays
+// well-typed (documented output) and --jq filters never hit null number/title/state.
+function normalizeIssue(raw) {
+  if (!Number.isInteger(raw?.number) || typeof raw?.title !== "string" || typeof raw?.state !== "string") {
+    return null;
+  }
+  return {
+    number: raw.number,
+    title: raw.title,
+    // gh reports issue state UPPERCASE (OPEN/CLOSED); normalize to lowercase to
+    // match the --state flag vocabulary.
+    state: raw.state.toLowerCase(),
+    labels: Array.isArray(raw?.labels)
+      ? raw.labels.map((l) => (typeof l?.name === "string" ? l.name : null)).filter((n) => n !== null)
+      : [],
+  };
+}
+
+export async function listIssues(options, { env = process.env, ghCommand = "gh", run = runChild } = {}) {
+  const args = [
+    "issue",
+    "list",
+    "--repo",
+    options.repo,
+    "--state",
+    options.state,
+    "--limit",
+    String(options.limit),
+    "--json",
+    "number,title,state,labels",
+  ];
+  for (const label of options.labels) {
+    args.push("--label", label);
+  }
+  const result = await run(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue list failed: ${detail}`);
+  }
+  const payload = parseJsonText(result.stdout, { label: "gh issue list" });
+  if (!Array.isArray(payload)) {
+    throw new Error("gh issue list did not return a JSON array");
+  }
+  return { ok: true, issues: payload.map(normalizeIssue).filter((issue) => issue !== null) };
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh", run = runChild } = {},
+) {
+  let options;
+  try {
+    options = parseListIssuesCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await listIssues(options, { env, ghCommand, run });
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    return 1;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((code) => { process.exitCode = code; });
+}

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;