dev-loops 0.1.0

package/scripts/loop/info.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { requireOptionValue, parsePositiveInteger } from "../_cli-primitives.mjs";
+import { detectRepoSlug, normalizeRepoSlug } from "@dev-loops/core/github/repo-slug";
+
+// REPO_ROOT resolves to the git repo root (scripts/loop/info.mjs → scripts/ → repo/)
+const REPO_ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)), "..");
+
+const USAGE = `Usage:
+  dev-loops loop info --issue <number>
+  dev-loops loop info --pr <number>
+Read-only state inspection for issues and PRs.
+Required (exactly one):
+  --issue <n>    Issue number
+  --pr <n>       PR number
+Optional:
+  --json         Machine-readable JSON output (default: human-readable summary)
+  --repo <slug>  Repository slug (auto-detected from git remote when omitted)
+Exit codes:
+  0  Success
+  1  Argument error or runtime failure`.trim();
+
+const parseError = buildParseError(USAGE);
+
+function parseCliArgs(argv) {
+  const args = [...argv];
+  const opts = { help: false, issue: undefined, pr: undefined, json: false, repo: undefined };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") { opts.help = true; return opts; }
+    if (token === "--json") { opts.json = true; continue; }
+    if (token === "--issue") { opts.issue = parsePositiveInteger(requireOptionValue(args, "--issue", parseError), "--issue", parseError); continue; }
+    if (token === "--pr") { opts.pr = parsePositiveInteger(requireOptionValue(args, "--pr", parseError), "--pr", parseError); continue; }
+    if (token === "--repo") { opts.repo = requireOptionValue(args, "--repo", parseError); continue; }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  const modes = [opts.issue, opts.pr].filter(v => v !== undefined).length;
+  if (modes > 1) throw parseError("--issue and --pr are mutually exclusive");
+  if (modes === 0) throw parseError("--issue <n> or --pr <n> is required");
+  return opts;
+}
+
+function validateRepo(repo) {
+  if (!repo) {
+    throw parseError("Repo auto-detection failed. Set origin remote or use --repo.");
+  }
+  try {
+    // Normalize (trim) the slug and validate structure
+    return normalizeRepoSlug(repo, { errorMessage: "--repo must match <owner/name>" });
+  } catch (err) {
+    throw parseError(`Invalid repo slug: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function ghJson(args, cwd) {
+  try {
+    const stdout = execFileSync("gh", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return JSON.parse(stdout);
+  } catch (err) {
+    throw new Error(`gh command failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function runNode(scriptPath, args, cwd) {
+  const stdout = execFileSync(process.execPath, [scriptPath, ...args], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  return JSON.parse(stdout);
+}
+
+function formatBranchDisplay(headRefName, baseRefName) {
+  return `${headRefName} ← ${baseRefName}`;
+}
+
+function formatCiDisplay(ciStatus, ciConclusion) {
+  if (!ciStatus || ciStatus === "none") return "no CI";
+  if (ciStatus === "pending") return "CI pending";
+  if (ciStatus === "failure") return `CI ❌ (${ciConclusion || "failed"})`;
+  if (ciStatus === "crediblyGreen") return "CI ✅ (local)";
+  return `CI ${ciStatus}`;
+}
+
+function formatPrSummary(prData, handoffResult) {
+  const lines = [];
+  lines.push(`PR #${prData.number}: ${prData.title}`);
+  lines.push(`  Branch: ${formatBranchDisplay(prData.headRefName, prData.baseRefName)}`);
+  lines.push(`  State: ${prData.state}${prData.isDraft ? " (draft)" : ""}`);
+  lines.push(`  Author: ${prData.author?.login || "unknown"}`);
+  
+  if (handoffResult?.snapshot) {
+    const s = handoffResult.snapshot;
+    if (s.ciStatus !== undefined) {
+      lines.push(`  CI: ${formatCiDisplay(s.ciStatus, s.ciConclusion)}`);
+    }
+    if (s.unresolvedThreadCount !== undefined) {
+      lines.push(`  Unresolved threads: ${s.unresolvedThreadCount}`);
+    }
+    if (s.completedCopilotRoundCount !== undefined && s.completedCopilotRoundCount > 0) {
+      lines.push(`  Copilot rounds: ${s.completedCopilotRoundCount}`);
+    }
+    if (s.reviewRoundCount !== undefined && s.reviewRoundCount > 0) {
+      lines.push(`  Review rounds: ${s.reviewRoundCount}`);
+    }
+    if (s.copilotReviewOnCurrentHead) {
+      lines.push(`  Copilot review: requested on current head`);
+    }
+  } else if (handoffResult?.error) {
+    lines.push(`  Handoff: unavailable (${handoffResult.error})`);
+  }
+  
+  if (handoffResult?.action) {
+    lines.push(`  Action: ${handoffResult.action}`);
+  }
+  if (handoffResult?.nextAction) {
+    lines.push(`  Next: ${handoffResult.nextAction}`);
+  }
+  if (handoffResult?.state) {
+    lines.push(`  Loop state: ${handoffResult.state}`);
+  }
+  
+  return lines.join("\n");
+}
+
+function formatIssueSummary(issueData, startupBundle, linkedPrData) {
+  const lines = [];
+  lines.push(`Issue #${issueData.number}: ${issueData.title}`);
+  lines.push(`  State: ${issueData.state}`);
+  
+  if (issueData.assignees?.length > 0) {
+    const names = issueData.assignees.map(a => a.login).join(", ");
+    lines.push(`  Assignees: ${names}`);
+  }
+  
+  const bundle = startupBundle?.bundle || startupBundle;
+  if (bundle) {
+    if (bundle.loopState) lines.push(`  Loop state: ${bundle.loopState}`);
+    if (bundle.selectedStrategy) lines.push(`  Strategy: ${bundle.selectedStrategy}`);
+    if (bundle.routeKind) lines.push(`  Route: ${bundle.routeKind}`);
+    if (bundle.nextAction) lines.push(`  Next: ${bundle.nextAction}`);
+  } else if (startupBundle?.error) {
+    lines.push(`  Startup: unavailable (${startupBundle.error})`);
+  }
+  
+  if (issueData.body) {
+    const hasAc = /##\s*Acceptance Criteria|##\s*AC\b|###\s*Acceptance Criteria|###\s*AC\b/i.test(issueData.body);
+    lines.push(`  Acceptance criteria: ${hasAc ? "present" : "missing"}`);
+  }
+  
+  if (linkedPrData) {
+    lines.push(`  Linked PR: #${linkedPrData.number} (${linkedPrData.state}${linkedPrData.isDraft ? ", draft" : ""})`);
+    if (linkedPrData.headRefName) {
+      lines.push(`    Branch: ${formatBranchDisplay(linkedPrData.headRefName, linkedPrData.baseRefName)}`);
+    }
+    if (linkedPrData.ciStatus !== undefined) {
+      lines.push(`    CI: ${formatCiDisplay(linkedPrData.ciStatus, linkedPrData.ciConclusion)}`);
+    }
+    if (linkedPrData.unresolvedThreadCount !== undefined) {
+      lines.push(`    Unresolved threads: ${linkedPrData.unresolvedThreadCount}`);
+    }
+    if (linkedPrData.loopState) {
+      lines.push(`    Loop state: ${linkedPrData.loopState}`);
+    }
+    if (linkedPrData.action) {
+      lines.push(`    Action: ${linkedPrData.action}`);
+    }
+  }
+  
+  return lines.join("\n");
+}
+
+function buildPrInfo(prNumber, repo, cwd) {
+  const prData = ghJson(["pr", "view", String(prNumber), "--repo", repo, "--json", "number,title,body,state,isDraft,headRefName,baseRefName,author,mergedAt,url,reviewRequests"], cwd);
+  
+  let handoffResult = null;
+  try {
+    const handoffScript = path.join(REPO_ROOT, "scripts/loop/copilot-pr-handoff.mjs");
+    handoffResult = runNode(handoffScript, ["--pr", String(prNumber), "--repo", repo, "--watch-status", "idle"], cwd);
+  } catch (err) {
+    handoffResult = { error: err instanceof Error ? err.message : String(err) };
+  }
+  
+  return { prData, handoffResult };
+}
+
+function buildIssueInfo(issueNumber, repo, cwd) {
+  const issueData = ghJson(["issue", "view", String(issueNumber), "--repo", repo, "--json", "number,title,body,state,labels,assignees,milestone,url"], cwd);
+  
+  // Run startup resolver with synthetic PI_SUBAGENT_RUN_ID to avoid
+  // async-start contract rejection for GitHub-first issue routes.
+  let startupBundle = null;
+  try {
+    const startupScript = path.join(REPO_ROOT, "scripts/loop/resolve-dev-loop-startup.mjs");
+    const env = { ...process.env, PI_SUBAGENT_RUN_ID: "info-readonly-placeholder" };
+    const raw = execFileSync(process.execPath, [startupScript, "--issue", String(issueNumber)], {
+      cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env,
+    });
+    startupBundle = JSON.parse(raw);
+  } catch (err) {
+    startupBundle = { error: err instanceof Error ? err.message : String(err) };
+  }
+  
+  let linkedPrInfo = null;
+  try {
+    const linkageScript = path.join(REPO_ROOT, "scripts/github/detect-linked-issue-pr.mjs");
+    const linkage = runNode(linkageScript, ["--repo", repo, "--issue", String(issueNumber)], cwd);
+    if (linkage.hasOpenLinkedPr && linkage.prNumber) {
+      const prData = ghJson(["pr", "view", String(linkage.prNumber), "--repo", repo, "--json", "number,title,state,isDraft,headRefName,baseRefName,author,url"], cwd);
+      
+      let handoffResult = null;
+      try {
+        const handoffScript = path.join(REPO_ROOT, "scripts/loop/copilot-pr-handoff.mjs");
+        handoffResult = runNode(handoffScript, ["--pr", String(linkage.prNumber), "--repo", repo, "--watch-status", "idle"], cwd);
+      } catch {
+        handoffResult = null;
+      }
+      
+      linkedPrInfo = {
+        ...prData,
+        ciStatus: handoffResult?.snapshot?.ciStatus,
+        ciConclusion: handoffResult?.snapshot?.ciConclusion,
+        unresolvedThreadCount: handoffResult?.snapshot?.unresolvedThreadCount,
+        loopState: handoffResult?.state,
+        action: handoffResult?.action,
+      };
+    }
+  } catch {
+    // Linked PR detection unavailable
+  }
+  
+  return { issueData, startupBundle, linkedPrInfo: linkedPrInfo };
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const opts = parseCliArgs(argv);
+  if (opts.help) { stdout.write(`${USAGE}\n`); return; }
+  
+  const cwd = process.cwd();
+  const rawRepo = opts.repo || detectRepoSlug(cwd);
+  // validateRepo normalizes (trims) the slug
+  const repo = validateRepo(rawRepo);
+  
+  if (opts.issue !== undefined) {
+    const { issueData, startupBundle, linkedPrInfo } = buildIssueInfo(opts.issue, repo, cwd);
+    
+    if (opts.json) {
+      stdout.write(JSON.stringify({ ok: true, kind: "issue", issue: issueData, startup: startupBundle, linkedPr: linkedPrInfo }) + "\n");
+    } else {
+      stdout.write(formatIssueSummary(issueData, startupBundle, linkedPrInfo) + "\n");
+    }
+  } else {
+    const { prData, handoffResult } = buildPrInfo(opts.pr, repo, cwd);
+    
+    if (opts.json) {
+      stdout.write(JSON.stringify({ ok: true, kind: "pr", pr: prData, handoff: handoffResult }) + "\n");
+    } else {
+      stdout.write(formatPrSummary(prData, handoffResult) + "\n");
+    }
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/loop/inspect-run-viewer/cli.mjs

@@ -0,0 +1,117 @@
+import {
+  DEFAULT_HOST,
+  DEFAULT_PORT,
+  USAGE,
+} from "./constants.mjs";
+import { requireOptionValue } from "../../_cli-primitives.mjs";
+import { normalizeInspectionTarget } from "../_inspect-run-viewer-adapter.mjs";
+
+export function parseInspectRunViewerCliError(message) {
+  return Object.assign(new Error(message), { usage: USAGE });
+}
+
+function parsePort(rawPort) {
+  if (!/^\d+$/.test(rawPort)) {
+    throw parseInspectRunViewerCliError("--port must be a positive integer");
+  }
+  const port = Number(rawPort);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw parseInspectRunViewerCliError("--port must be between 1 and 65535");
+  }
+  return port;
+}
+
+function parseHost(rawHost) {
+  const host = rawHost.trim();
+  if (host.length === 0) {
+    throw parseInspectRunViewerCliError("--host must not be empty");
+  }
+  if (/^\[[^\]]+\]$/.test(host)) {
+    return host.slice(1, -1);
+  }
+  return host;
+}
+
+function isLoopbackHost(host) {
+  return host === "localhost"
+    || host === "::1"
+    || /^127(?:\.\d{1,3}){3}$/.test(host);
+}
+
+export function normalizeCliRepoOption(rawRepo) {
+  try {
+    return normalizeInspectionTarget({ repo: rawRepo, pr: 1 }).repo;
+  } catch (error) {
+    throw parseInspectRunViewerCliError(error instanceof Error ? error.message : String(error));
+  }
+}
+
+export function parseInspectRunViewerCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    repo: undefined,
+    host: DEFAULT_HOST,
+    port: DEFAULT_PORT,
+    steeringStateFile: undefined,
+    copilotInputPath: undefined,
+    reviewerInputPath: undefined,
+    allowNonLocalhost: false,
+    restart: false,
+  };
+
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--repo") {
+      options.repo = requireOptionValue(args, "--repo", parseInspectRunViewerCliError);
+      continue;
+    }
+    if (token === "--pr") {
+      throw parseInspectRunViewerCliError("--pr is no longer supported on the CLI; choose a PR with ?pr=<number> in the viewer URL");
+    }
+    if (token === "--host") {
+      options.host = parseHost(requireOptionValue(args, "--host", parseInspectRunViewerCliError));
+      continue;
+    }
+    if (token === "--port") {
+      options.port = parsePort(requireOptionValue(args, "--port", parseInspectRunViewerCliError));
+      continue;
+    }
+    if (token === "--allow-non-localhost") {
+      options.allowNonLocalhost = true;
+      continue;
+    }
+    if (token === "--restart") {
+      options.restart = true;
+      continue;
+    }
+    if (token === "--steering-state-file") {
+      options.steeringStateFile = requireOptionValue(args, "--steering-state-file", parseInspectRunViewerCliError);
+      continue;
+    }
+    if (token === "--copilot-input") {
+      options.copilotInputPath = requireOptionValue(args, "--copilot-input", parseInspectRunViewerCliError);
+      continue;
+    }
+    if (token === "--reviewer-input") {
+      options.reviewerInputPath = requireOptionValue(args, "--reviewer-input", parseInspectRunViewerCliError);
+      continue;
+    }
+    throw parseInspectRunViewerCliError(`Unknown argument: ${token}`);
+  }
+
+  if (!options.help) {
+    options.repo = options.repo === undefined ? undefined : normalizeCliRepoOption(options.repo);
+    if (!options.allowNonLocalhost && !isLoopbackHost(options.host)) {
+      throw parseInspectRunViewerCliError("--host must stay on localhost/loopback unless --allow-non-localhost is set");
+    }
+  }
+
+  return options;
+}
+
+export { USAGE };

package/scripts/loop/inspect-run-viewer/constants.mjs

@@ -0,0 +1,80 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+export const USAGE = `Usage: inspect-run-viewer.mjs [--repo <owner/name>]
+  [--host <host>] [--port <port>] [--allow-non-localhost] [--restart]
+  [--steering-state-file <path>]
+  [--copilot-input <path>] [--reviewer-input <path>]
+
+Owned read-only local/operator inspection dashboard for inspect-run snapshots.
+inspect-run remains authoritative for inspection/status state; this viewer owns local inbox discovery plus read-only presentation/prioritization.
+Inbox-first mode works with no PR selected. Use ?pr=<number> to deep-link a selected PR and optionally ?repo=<owner/name> to scope the inbox.
+
+Optional:
+  --repo <owner/name>                     Restrict the inbox to one repo
+  --host <host>                         Bind host (default: 127.0.0.1)
+  --port <port>                         Bind port (default: 4311)
+  --allow-non-localhost                 Permit non-loopback binds
+                                        (otherwise rejected)
+  --restart                             Stop any existing listener on the
+                                        chosen port before starting
+                                        (requires lsof/POSIX; sends
+                                        SIGTERM to all listeners)
+  --steering-state-file <path>          Pass-through to inspect-run
+
+  --copilot-input <path>                Pass-through to inspect-run
+  --reviewer-input <path>               Pass-through to inspect-run
+                                                                                  (pass-through to inspect-run)
+)`.trim();
+
+export const DEFAULT_HOST = "127.0.0.1";
+export const DEFAULT_PORT = 4311;
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+export const MERMAID_BROWSER_ASSET_ROUTE = "/assets/mermaid.min.js";
+const require = createRequire(import.meta.url);
+const DEFAULT_MERMAID_BROWSER_ASSET_FALLBACK_PATH = path.join(
+  REPO_ROOT,
+  "node_modules",
+  "mermaid",
+  "dist",
+  "mermaid.min.js",
+);
+
+export function resolveMermaidBrowserAssetPath({ resolveImpl = require.resolve.bind(require) } = {}) {
+  try {
+    return resolveImpl("mermaid/dist/mermaid.min.js");
+  } catch {
+    return DEFAULT_MERMAID_BROWSER_ASSET_FALLBACK_PATH;
+  }
+}
+
+export const MERMAID_BROWSER_ASSET_PATH = resolveMermaidBrowserAssetPath();
+export const DEFAULT_INBOX_UPDATED_WITHIN_DAYS = 7;
+export const DEFAULT_INBOX_PAGE_SIZE = 25;
+export const MAX_INBOX_RESULT_LIMIT = 100;
+export const DEFAULT_INBOX_PR_STATE = "open";
+export const DEFAULT_INBOX_MODE = "assignee";
+export const DEFAULT_INBOX_PAGE = 1;
+export const INBOX_UPDATED_FILTER_PRESETS = [
+  { label: "7d", value: 7 },
+  { label: "30d", value: 30 },
+  { label: "90d", value: 90 },
+  { label: "All", value: null },
+];
+export const INBOX_STATE_FILTER_PRESETS = [
+  { label: "Open", value: "open" },
+  { label: "Closed", value: "closed" },
+  { label: "All", value: "all" },
+];
+export const INBOX_STATE_FILTER_VALUES = new Set(
+  INBOX_STATE_FILTER_PRESETS.map((preset) => preset.value),
+);
+export const INBOX_MODE_FILTER_PRESETS = [
+  { label: "Assigned", value: "assignee" },
+  { label: "Reviewer", value: "reviewer" },
+  { label: "Involved", value: "involved" },
+];
+export const INBOX_MODE_FILTER_VALUES = new Set(
+  INBOX_MODE_FILTER_PRESETS.map((preset) => preset.value),
+);