dev-loops 0.5.0 → 0.6.0

package/lib/dev-loops-core.mjs

@@ -9,6 +9,19 @@ const LOCAL_READINESS_IDS = ['subagent-command', 'git-repo'];
 const REMOTE_READINESS_IDS = ['gh-installed', 'gh-auth', 'subagent-command', 'git-repo'];
 const INSPECT_ACTIONS = new Set(['open', 'resume', 'status', 'stop', 'restart']);
 
+// Direct dev-loop entrypoints (#972): thin named wrappers over the public dev-loop contract.
+// Each maps `<verb> <issue|pr>` to the canonical public-intent shorthand the `dev-loop` skill
+// already accepts — no new routing/strategy logic lives here. `start`/`auto` target an issue,
+// `continue` (#988) targets an issue OR a PR (the resolver picks the canonical artifact) and
+// also accepts a bare form (no number) that continues the current in-progress board item;
+// `info` is the read-only state shortcut for an issue or PR.
+const ENTRYPOINT_VERBS = {
+  start: { target: 'issue', phrase: (n) => `start dev loop on issue ${n}` },
+  auto: { target: 'issue', phrase: (n) => `auto dev loop on issue ${n}` },
+  continue: { target: 'either', allowBare: true, phrase: (n) => (n ? `continue dev loop on ${n}` : 'continue the current dev loop') },
+  info: { target: 'either', phrase: (n) => `inspect dev loop state on ${n}` },
+};
+
 const UNICODE_SPACE_RE = /[\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]/g;
 
 function normalizeInput(input) {
@@ -88,6 +101,100 @@ function parseInspectCommand(tokens, { surface }) {
   };
 }
 
+// Normalize a single entrypoint target token to a bare issue/PR number.
+// Accepts `123`, `#123`, or a GitHub issue/PR URL (.../issues/123 or .../pull/123).
+// Returns the numeric string, or null when it is not a recognized target.
+function normalizeTargetNumber(raw) {
+  const token = String(raw).trim();
+  if (/^#?\d+$/.test(token)) {
+    return token.replace(/^#/, '');
+  }
+  const urlMatch = token.match(/^https?:\/\/[^\s]*\/(?:issues|pull)\/(\d+)(?:[/?#].*)?$/);
+  if (urlMatch) {
+    return urlMatch[1];
+  }
+  return null;
+}
+
+// `start-spike` is a SIBLING of the numeric verbs (start/auto/continue/info): it
+// takes FREE TEXT (a question) or `--file <path>`, NOT a numeric target, so it is
+// parsed on its own path to keep the numeric-validation invariant of the other
+// verbs intact (#988 P2). It is a thin wrapper over the shipped `--spike` intake:
+// the inline-question form scaffolds a startable findings artifact, then both
+// forms hand the resolved spike path to `loop startup --spike <path>`. No new
+// spike behavior lives here — see skills/docs/spike-mode-contract.md.
+function parseStartSpikeCommand(rest, tokens) {
+  const positional = rest.filter((t) => t !== undefined);
+  // `--file <path>`: start from a pre-authored spike artifact (no scaffolding).
+  if (positional[0] === '--file') {
+    const file = positional[1];
+    // Reject any leading `-`: the path is forwarded to `resolve-dev-loop-startup
+    // --spike <path>`, so a value like `-x` could be read as an option (option
+    // injection). Fail closed. The free-text question path below is unaffected.
+    if (typeof file !== 'string' || file.length === 0 || file.startsWith('-') || positional.length !== 2) {
+      return invalidCommand('`start-spike --file` requires exactly one `<path>`.', 'start-spike', tokens);
+    }
+    return {
+      kind: 'start_spike',
+      mode: 'file',
+      file,
+      question: null,
+      intent: `start a dev-loop spike from ${file}`,
+      tokens,
+    };
+  }
+  // Inline free-text question. Joined verbatim so multi-word questions survive.
+  const question = positional.join(' ').trim();
+  if (question.length === 0) {
+    return invalidCommand('`start-spike` requires a question (or `--file <path>`).', 'start-spike', tokens);
+  }
+  return {
+    kind: 'start_spike',
+    mode: 'question',
+    file: null,
+    question,
+    intent: `start a dev-loop spike on the question: ${question}`,
+    tokens,
+  };
+}
+
+function parseEntrypointCommand(action, args, tokens) {
+  const spec = ENTRYPOINT_VERBS[action];
+  const positional = args.filter((a) => a !== undefined);
+  const targetHint = spec.target === 'pr' ? '<pr>' : spec.target === 'either' ? '<issue|pr>' : '<issue>';
+  const targetNoun = spec.target === 'pr' ? 'PR' : spec.target === 'either' ? 'issue/PR' : 'issue';
+
+  // Bare form (no target): only verbs that opt in (e.g. `continue` resumes the
+  // current in-progress board item). The command/skill does the board resolve.
+  if (positional.length === 0 && spec.allowBare) {
+    return {
+      kind: 'entrypoint',
+      action,
+      target: spec.target,
+      number: null,
+      intent: spec.phrase(null),
+      tokens,
+    };
+  }
+
+  if (positional.length !== 1) {
+    const arity = spec.allowBare ? `at most one ${targetHint}` : `exactly one ${targetHint}`;
+    return invalidCommand(`\`${action}\` requires ${arity} argument.`, action, tokens);
+  }
+  const number = normalizeTargetNumber(positional[0]);
+  if (number === null) {
+    return invalidCommand(`\`${action}\` expects a numeric ${targetNoun}, got: ${positional[0]}.`, action, tokens);
+  }
+  return {
+    kind: 'entrypoint',
+    action,
+    target: spec.target,
+    number,
+    intent: spec.phrase(number),
+    tokens,
+  };
+}
+
 export function parseDevLoopsCommand(input, { surface = 'extension' } = {}) {
   const tokens = normalizeInput(input);
   const [rawAction, rawScope, ...rest] = tokens;
@@ -98,6 +205,15 @@ export function parseDevLoopsCommand(input, { surface = 'extension' } = {}) {
     return parseInspectCommand(tokens, { surface });
   }
 
+  // `start-spike` is free-text/path, not a numeric verb — parsed on its own path.
+  if (action === 'start-spike') {
+    return parseStartSpikeCommand([rawScope, ...rest], tokens);
+  }
+
+  if (action && Object.prototype.hasOwnProperty.call(ENTRYPOINT_VERBS, action)) {
+    return parseEntrypointCommand(action, [rawScope, ...rest], tokens);
+  }
+
   switch (action) {
     case undefined:
     case '':
@@ -255,6 +371,31 @@ export async function executeDevLoopsCommand({ input, surface = 'extension', run
     }
   }
 
+  if (parsed.kind === 'start_spike') {
+    // Thin wrapper: surface the spike intent so the operator dispatches it through
+    // the dev-loop skill, which scaffolds (inline question) or uses the given file,
+    // then runs `loop startup --spike <path>`. No spike behavior is decided here.
+    return {
+      kind: 'start_spike',
+      mode: parsed.mode,
+      file: parsed.file,
+      question: parsed.question,
+      intent: parsed.intent,
+    };
+  }
+
+  if (parsed.kind === 'entrypoint') {
+    // Thin wrapper: surface the canonical public intent so the user dispatches it through the
+    // `dev-loop` skill (the single public router). No routing/strategy decision is made here.
+    return {
+      kind: 'entrypoint',
+      action: parsed.action,
+      target: parsed.target,
+      number: parsed.number,
+      intent: parsed.intent,
+    };
+  }
+
   if (parsed.kind !== 'action') {
     return parsed;
   }

package/package.json

@@ -31,6 +31,8 @@
     "test:playwright:viewer": "playwright test -c playwright.inspect-run-viewer.config.mjs",
     "test:playwright:deep-dive": "playwright test -c playwright.dev-loops-deep-dive.config.mjs",
     "test:playwright:intro-deck": "playwright test -c playwright.intro-deck.config.mjs",
+    "test:playwright:intro-article": "playwright test -c playwright.intro-article.config.mjs",
+    "test:playwright:deep-dive-article": "playwright test -c playwright.deep-dive-article.config.mjs",
     "smoke:headless": "node scripts/claude/headless-info-smoke.mjs",
     "test:docs": "node scripts/docs/validate-links.mjs && node scripts/docs/validate-no-duplicate-rules.mjs",
     "repo-wiki": "node scripts/repo-wiki.mjs",
@@ -70,7 +72,7 @@
   },
   "dependencies": {
     "mermaid": "11.15.0",
-    "@dev-loops/core": "^0.5.0"
+    "@dev-loops/core": "^0.6.0"
   },
   "repository": {
     "type": "git",
@@ -80,7 +82,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "files": [
     "cli/",
     "lib/",
@@ -91,6 +93,7 @@
     ".claude-plugin/",
     ".claude/.claude-plugin/",
     ".claude/agents/",
+    ".claude/commands/",
     ".claude/skills/",
     ".claude/hooks/",
     "README.md",

package/scripts/claude/generate-claude-assets.mjs

@@ -14,7 +14,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { transformAgent, transformSkill, stripPiOnlyBlocks } from "@dev-loops/core/claude/asset-generation";
+import { transformAgent, transformSkill, transformCommand, stripPiOnlyBlocks } from "@dev-loops/core/claude/asset-generation";
 
 /**
  * Collect the generated assets as { target, content } pairs (target is repo-relative).
@@ -45,6 +45,19 @@ export function collectGeneratedAssets({ repoRoot = process.cwd() } = {}) {
     }
   }
 
+  // Direct slash commands (#972): thin generated wrappers over the public dev-loop contract,
+  // one `.claude/commands/<name>.md` per `commands/<name>.command.md` source. No routing logic.
+  const commandsDir = path.join(repoRoot, "commands");
+  if (fs.existsSync(commandsDir)) {
+    for (const entry of fs.readdirSync(commandsDir).sort()) {
+      if (!entry.endsWith(".command.md")) continue;
+      const source = `commands/${entry}`;
+      const raw = fs.readFileSync(path.join(repoRoot, source), "utf8");
+      const base = entry.slice(0, -".command.md".length);
+      assets.push({ target: `.claude/commands/${base}.md`, content: transformCommand({ source, raw, version }) });
+    }
+  }
+
   const skillsDir = path.join(repoRoot, "skills");
   if (fs.existsSync(skillsDir)) {
     for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
@@ -171,6 +184,7 @@ function listFilesRecursive(repoRoot, rel) {
 function listExistingAssetFiles(repoRoot) {
   const files = [
     ...listFilesRecursive(repoRoot, ".claude/agents"),
+    ...listFilesRecursive(repoRoot, ".claude/commands"),
     ...listFilesRecursive(repoRoot, ".claude/skills"),
   ];
   // `.claude/hooks/` mixes hand-authored scripts (hooks.json, _hook-io.mjs, the three hook

package/scripts/github/comment-issue.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseIssueNumber, 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 USAGE = `Usage: comment-issue.mjs --repo <owner/name> --issue <number> (--body <text> | --body-file <path>)
+Post a comment on a GitHub issue. Thin wrapper over \`gh issue comment\` — use this
+instead of an agent-level raw \`gh issue comment\` so the loop's internal-tooling
+record stays clean (#993; the read-side siblings are list-issues.mjs / fetch-ci-logs.mjs).
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --issue <number>              Issue number to comment on
+  --body <text>                 Comment body as a single argument
+  --body-file <path>            Read the comment body from a file (preserves
+                                newlines; alternative to --body; - reads stdin)
+Output (stdout, JSON):
+  { "ok": true, "repo": "owner/repo", "issue": 17, "commentUrl": "https://github.com/owner/repo/issues/17#issuecomment-123" }
+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 parseCommentIssueCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      issue: { type: "string" },
+      body: { type: "string" },
+      "body-file": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    issue: undefined,
+    body: undefined,
+    bodyFile: undefined,
+    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 === "issue") {
+      options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
+      continue;
+    }
+    if (token.name === "body") {
+      options.body = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "body-file") {
+      const rawPath = requireTokenValue(token, parseError).trim();
+      if (rawPath.length === 0) {
+        throw parseError("--body-file must be a non-empty path");
+      }
+      options.bodyFile = rawPath;
+      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.issue === undefined) {
+    throw parseError("Commenting on an issue requires both --repo <owner/name> and --issue <number>");
+  }
+  if (options.body === undefined && options.bodyFile === undefined) {
+    throw parseError("Commenting on an issue requires --body <text> or --body-file <path>");
+  }
+  if (options.body !== undefined && options.bodyFile !== undefined) {
+    throw parseError("--body and --body-file are mutually exclusive; pass only one");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+async function resolveBody(options) {
+  if (options.bodyFile === undefined) {
+    if (options.body.trim().length === 0) {
+      throw new Error("--body must not be empty");
+    }
+    return options.body;
+  }
+  const source = options.bodyFile === "-" ? 0 : options.bodyFile;
+  const body = await readFile(source, "utf8");
+  if (body.trim().length === 0) {
+    throw new Error(`--body-file ${options.bodyFile} is empty`);
+  }
+  return body;
+}
+
+// Post the comment via `gh issue comment`, then read its URL back from
+// `gh issue comment` output. `gh issue comment` prints the new comment URL on
+// success — capture it so callers don't need a follow-up read.
+export async function commentIssue(options, { env = process.env, ghCommand = "gh", run = runChild } = {}) {
+  const body = await resolveBody(options);
+  const result = await run(
+    ghCommand,
+    ["issue", "comment", String(options.issue), "--repo", options.repo, "--body", body],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue comment failed: ${detail}`);
+  }
+  // `gh issue comment` prints the created comment's URL (the last non-empty line
+  // of stdout). Surface it so the caller has the comment URL without a re-read.
+  const commentUrl = result.stdout
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .pop() ?? null;
+  if (commentUrl === null || !/^https?:\/\//u.test(commentUrl)) {
+    throw new Error(`gh issue comment did not return a comment URL (got: ${result.stdout.trim() || "<empty>"})`);
+  }
+  return { ok: true, repo: options.repo, issue: options.issue, commentUrl };
+}
+
+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 = parseCommentIssueCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await commentIssue(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/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; });
+}