devin-bugs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hannah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# devin-review-cli
+
+CLI to extract unresolved bugs from [Devin AI](https://devin.ai) code reviews. Pulls flagged bugs from any PR that Devin has reviewed and outputs them in your terminal or as JSON.
+
+```
+$ devin-bugs owner/repo#46
+
+  1 bug in owner/repo#46
+
+  BUG  lib/apply/assist.ts:124-136   WARNING
+  Reverting packet to 'ready' after credits charged creates an unrecoverable retry loop
+  In prepareApplyAssist, when createApplication fails with a non-P2002 error,
+  the packet is reverted to 'ready' but credits have already been charged...
+```
+
+## Install
+
+Requires [Bun](https://bun.sh) (v1.0+).
+
+```bash
+git clone https://github.com/xCatalitY/devin-review-cli.git
+cd devin-review-cli
+bun install
+```
+
+## Usage
+
+```bash
+# GitHub PR URL
+devin-bugs https://github.com/owner/repo/pull/123
+
+# Shorthand
+devin-bugs owner/repo#123
+
+# Devin review URL
+devin-bugs https://app.devin.ai/review/owner/repo/pull/123
+```
+
+### Options
+
+```
+--json          Output as JSON (for piping)
+--all           Include analysis/suggestions, not just bugs
+--raw           Dump raw API response (debug)
+--no-cache      Force re-authentication
+--login         Just authenticate, don't fetch anything
+--logout        Clear stored credentials
+--help, -h      Show help
+```
+
+### Examples
+
+```bash
+# Get bugs as JSON for scripting
+devin-bugs owner/repo#46 --json | jq '.[].title'
+
+# Include all flags (bugs + analysis suggestions)
+devin-bugs owner/repo#46 --all
+
+# Pipe to another tool
+devin-bugs owner/repo#46 --json | jq '.[] | select(.severity == "severe")'
+
+# Skip browser, use token directly
+DEVIN_TOKEN=eyJ... devin-bugs owner/repo#46
+```
+
+## Authentication
+
+On first run, the CLI opens your browser to a local page with instructions:
+
+1. Log in to [app.devin.ai](https://app.devin.ai) with GitHub
+2. Paste a one-liner in the browser console (auto-copied from the instruction page)
+3. The token is sent back to the CLI and cached
+
+Subsequent runs use the cached token automatically. Tokens are stored at `~/.config/devin-bugs/token.json`.
+
+For CI or headless environments, set `DEVIN_TOKEN` as an environment variable.
+
+## How it works
+
+The CLI reverse-engineers Devin's internal PR review API:
+
+1. Authenticates via Devin's Auth0-based auth system
+2. Fetches the review digest from `GET /api/pr-review/digest`
+3. Parses review threads for Devin's "lifeguard" bug flags
+4. Filters to unresolved, non-outdated items
+5. Outputs formatted results
+
+### API endpoints used
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET pr-review/digest?pr_path=...` | Full review data with flags, threads, checks |
+| `GET pr-review/info?pr_path=...` | PR metadata |
+| `GET pr-review/jobs?pr_path=...` | Review job status |
+
+## JSON output schema
+
+```typescript
+interface Bug {
+  filePath: string;       // "lib/apply/assist.ts"
+  startLine: number;      // 124
+  endLine: number;        // 136
+  side: "LEFT" | "RIGHT";
+  title: string;          // Short description
+  description: string;    // Full explanation
+  severity: string;       // "severe" | "warning" | "info"
+  recommendation: string; // Suggested fix
+  type: "lifeguard-bug" | "lifeguard-analysis";
+  isResolved: boolean;
+  isOutdated: boolean;
+  htmlUrl: string | null;  // Link to GitHub comment
+}
+```
+
+## Project structure
+
+```
+src/
+  cli.ts          Entry point, arg parsing, orchestration
+  auth.ts         Browser-based auth + token caching
+  api.ts          Devin API client with retry on 401
+  filter.ts       Bug extraction from digest response
+  format.ts       Terminal (ANSI) and JSON formatters
+  parse-pr.ts     PR URL/shorthand parser
+  types.ts        TypeScript interfaces
+  config.ts       Paths and constants
+```
+
+## Disclaimer
+
+This tool uses Devin's internal API, which is not officially documented or supported. It may break if Devin changes their API. Use at your own risk.
+
+## License
+
+MIT

package/bin/devin-bugs

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli.ts";

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "devin-bugs",
+  "version": "0.1.0",
+  "description": "CLI to extract unresolved bugs from Devin AI code reviews",
+  "type": "module",
+  "bin": {
+    "devin-bugs": "./bin/devin-bugs"
+  },
+  "scripts": {
+    "start": "bun src/cli.ts",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "devin",
+    "code-review",
+    "cli",
+    "bugs",
+    "pr-review",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xCatalitY/devin-review-cli.git"
+  },
+  "homepage": "https://github.com/xCatalitY/devin-review-cli",
+  "bugs": "https://github.com/xCatalitY/devin-review-cli/issues",
+  "license": "MIT",
+  "author": "xCatalitY",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.8.3"
+  }
+}

package/src/api.ts

@@ -0,0 +1,81 @@
+import { DEVIN_API_BASE } from "./config.js";
+import type { DigestResponse } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+
+export class AuthExpiredError extends Error {
+  constructor() {
+    super("Authentication expired. Re-authenticating...");
+    this.name = "AuthExpiredError";
+  }
+}
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: string
+  ) {
+    super(`Devin API error ${status}: ${body}`);
+    this.name = "ApiError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Generic request helper
+// ---------------------------------------------------------------------------
+
+async function apiRequest<T>(path: string, token: string): Promise<T> {
+  const url = `${DEVIN_API_BASE}/${path}`;
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json",
+    },
+  });
+
+  if (!res.ok) {
+    if (res.status === 401 || res.status === 403) {
+      throw new AuthExpiredError();
+    }
+    const body = await res.text().catch(() => "");
+    throw new ApiError(res.status, body);
+  }
+
+  return res.json() as Promise<T>;
+}
+
+// ---------------------------------------------------------------------------
+// Endpoints
+// ---------------------------------------------------------------------------
+
+export async function fetchDigest(
+  prPath: string,
+  token: string
+): Promise<DigestResponse> {
+  return apiRequest<DigestResponse>(
+    `pr-review/digest?pr_path=${encodeURIComponent(prPath)}`,
+    token
+  );
+}
+
+export async function fetchPRInfo(
+  prPath: string,
+  token: string
+): Promise<Record<string, unknown>> {
+  return apiRequest<Record<string, unknown>>(
+    `pr-review/info?pr_path=${encodeURIComponent(prPath)}`,
+    token
+  );
+}
+
+export async function fetchJobs(
+  prPath: string,
+  token: string
+): Promise<{ jobs: unknown[] }> {
+  return apiRequest<{ jobs: unknown[] }>(
+    `pr-review/jobs?pr_path=${encodeURIComponent(prPath)}`,
+    token
+  );
+}

package/src/auth.ts

@@ -0,0 +1,360 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+import { createServer, type Server } from "node:http";
+import { execFile } from "node:child_process";
+import {
+  TOKEN_PATH,
+  DEVIN_APP_URL,
+  TOKEN_REFRESH_MARGIN_SEC,
+} from "./config.js";
+import type { CachedToken } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// JWT helpers (no library — just decode the payload for `exp`)
+// ---------------------------------------------------------------------------
+
+function base64UrlDecode(str: string): string {
+  const padded = str.replace(/-/g, "+").replace(/_/g, "/");
+  return Buffer.from(padded, "base64").toString("utf-8");
+}
+
+function decodeTokenExpiry(jwt: string): number {
+  const parts = jwt.split(".");
+  if (parts.length !== 3) throw new Error("Invalid JWT format");
+  const payload = JSON.parse(base64UrlDecode(parts[1]!));
+  if (typeof payload.exp !== "number") throw new Error("JWT missing exp claim");
+  return payload.exp * 1000; // convert to epoch ms
+}
+
+// ---------------------------------------------------------------------------
+// Token cache (disk)
+// ---------------------------------------------------------------------------
+
+function ensureDir(dirPath: string): void {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function readCachedToken(): CachedToken | null {
+  try {
+    if (!existsSync(TOKEN_PATH)) return null;
+    const raw = readFileSync(TOKEN_PATH, "utf-8");
+    const parsed = JSON.parse(raw) as CachedToken;
+    if (!parsed.accessToken || !parsed.expiresAt) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeCachedToken(accessToken: string): CachedToken {
+  ensureDir(dirname(TOKEN_PATH));
+  const expiresAt = decodeTokenExpiry(accessToken);
+  const cached: CachedToken = {
+    accessToken,
+    obtainedAt: Date.now(),
+    expiresAt,
+  };
+  writeFileSync(TOKEN_PATH, JSON.stringify(cached, null, 2));
+  return cached;
+}
+
+function clearCachedToken(): void {
+  try {
+    if (existsSync(TOKEN_PATH)) unlinkSync(TOKEN_PATH);
+  } catch {
+    // ignore
+  }
+}
+
+function isTokenValid(cached: CachedToken): boolean {
+  return cached.expiresAt - Date.now() > TOKEN_REFRESH_MARGIN_SEC * 1000;
+}
+
+// ---------------------------------------------------------------------------
+// Open URL in system browser (safe — no shell interpolation)
+// ---------------------------------------------------------------------------
+
+function openBrowser(url: string): void {
+  const opener =
+    process.platform === "darwin"
+      ? { cmd: "open", args: [url] }
+      : process.platform === "win32"
+        ? { cmd: "cmd", args: ["/c", "start", "", url] }
+        : { cmd: "xdg-open", args: [url] };
+
+  execFile(opener.cmd, opener.args, (err) => {
+    if (err) {
+      console.error(`\x1b[33m▸ Could not open browser automatically.\x1b[0m`);
+      console.error(`  Open this URL manually: ${url}\n`);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Local callback server
+// ---------------------------------------------------------------------------
+
+/**
+ * The capture page served at localhost. It instructs the user to:
+ * 1. Log in to Devin in a new tab
+ * 2. Paste a one-liner in the browser console that sends the token back
+ *
+ * This is the same pattern as many CLIs that can't do standard OAuth.
+ * The one-liner calls __HACK__getAccessToken() on app.devin.ai and
+ * POSTs the result to our localhost callback.
+ */
+function buildCapturePage(port: number): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>devin-bugs — Login</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #141414; color: #e0e0e0;
+      display: flex; align-items: center; justify-content: center;
+      min-height: 100vh; padding: 2rem;
+    }
+    .card {
+      background: #1e1e1e; border: 1px solid #333; border-radius: 12px;
+      padding: 2.5rem; max-width: 560px; width: 100%;
+    }
+    h1 { font-size: 1.25rem; color: #fff; margin-bottom: 0.5rem; }
+    .subtitle { color: #888; font-size: 0.9rem; margin-bottom: 1.5rem; }
+    .step {
+      display: flex; gap: 0.75rem; margin-bottom: 1.25rem;
+      padding: 0.75rem; border-radius: 8px; background: #252525;
+    }
+    .step-num {
+      flex-shrink: 0; width: 24px; height: 24px; border-radius: 50%;
+      background: #3b82f6; color: #fff; font-size: 0.75rem; font-weight: 700;
+      display: flex; align-items: center; justify-content: center;
+    }
+    .step-text { font-size: 0.9rem; line-height: 1.5; }
+    .step-text a { color: #60a5fa; text-decoration: none; }
+    .step-text a:hover { text-decoration: underline; }
+    code {
+      background: #0d1117; color: #7ee787; padding: 0.5rem 0.75rem;
+      border-radius: 6px; display: block; font-size: 0.8rem;
+      margin-top: 0.5rem; cursor: pointer; border: 1px solid #333;
+      word-break: break-all; position: relative;
+    }
+    code:hover { border-color: #3b82f6; }
+    code::after {
+      content: 'click to copy'; position: absolute; right: 8px; top: 8px;
+      font-size: 0.65rem; color: #888; font-family: sans-serif;
+    }
+    .success {
+      display: none; padding: 1rem; border-radius: 8px;
+      background: #052e16; border: 1px solid #16a34a; text-align: center;
+    }
+    .success h2 { color: #4ade80; font-size: 1rem; }
+    .success p { color: #86efac; font-size: 0.85rem; margin-top: 0.5rem; }
+    .waiting {
+      text-align: center; padding: 1rem; color: #888;
+      font-size: 0.85rem; margin-top: 0.5rem;
+    }
+    .dot { animation: pulse 1.5s infinite; }
+    @keyframes pulse { 0%,100% { opacity: 0.3; } 50% { opacity: 1; } }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>devin-bugs</h1>
+    <p class="subtitle">Authenticate with Devin to extract PR review data</p>
+
+    <div id="steps">
+      <div class="step">
+        <div class="step-num">1</div>
+        <div class="step-text">
+          <a href="${DEVIN_APP_URL}" target="_blank" rel="noopener">
+            Open app.devin.ai</a> and log in with GitHub
+        </div>
+      </div>
+
+      <div class="step">
+        <div class="step-num">2</div>
+        <div class="step-text">
+          Open the browser console (<strong>F12</strong> → Console tab) and paste:
+          <code id="snippet" onclick="copySnippet()">fetch('http://localhost:${port}/callback',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({token:await __HACK__getAccessToken()})}).then(()=>document.title='✓ Token sent!')</code>
+        </div>
+      </div>
+
+      <div class="waiting">
+        Waiting for token<span class="dot">...</span>
+      </div>
+    </div>
+
+    <div class="success" id="success">
+      <h2>✓ Authentication successful!</h2>
+      <p>You can close this tab and return to your terminal.</p>
+    </div>
+  </div>
+
+  <script>
+    function copySnippet() {
+      navigator.clipboard.writeText(document.getElementById('snippet').textContent);
+      const el = document.getElementById('snippet');
+      el.style.borderColor = '#4ade80';
+      setTimeout(() => el.style.borderColor = '#333', 1500);
+    }
+
+    // Poll the local server to check if token was received
+    async function poll() {
+      try {
+        const res = await fetch('/status');
+        const data = await res.json();
+        if (data.received) {
+          document.getElementById('steps').style.display = 'none';
+          document.getElementById('success').style.display = 'block';
+          return;
+        }
+      } catch {}
+      setTimeout(poll, 1500);
+    }
+    poll();
+  </script>
+</body>
+</html>`;
+}
+
+/**
+ * Start a local HTTP server that:
+ * - Serves the capture page at /
+ * - Receives the token at POST /callback (from the console one-liner)
+ * - Reports status at GET /status (for the page to poll)
+ */
+function startCallbackServer(): Promise<{ token: string; server: Server }> {
+  return new Promise((resolve, reject) => {
+    let receivedToken: string | null = null;
+
+    const server = createServer((req, res) => {
+      // CORS headers for cross-origin fetch from app.devin.ai
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "POST, GET, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      if (req.method === "GET" && req.url === "/status") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ received: receivedToken !== null }));
+        return;
+      }
+
+      if (req.method === "POST" && req.url === "/callback") {
+        let body = "";
+        req.on("data", (chunk: Buffer) => (body += chunk.toString()));
+        req.on("end", () => {
+          try {
+            const data = JSON.parse(body) as { token?: string };
+            if (typeof data.token === "string" && data.token.length > 20) {
+              receivedToken = data.token;
+              res.writeHead(200, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ ok: true }));
+              // Resolve after a short delay to let the page poll /status
+              setTimeout(() => {
+                server.close();
+                resolve({ token: receivedToken!, server });
+              }, 500);
+              return;
+            }
+          } catch {}
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Invalid token" }));
+        });
+        return;
+      }
+
+      // Serve the capture page
+      if (req.method === "GET" && (req.url === "/" || req.url === "/login")) {
+        const port = (server.address() as { port: number }).port;
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(buildCapturePage(port));
+        return;
+      }
+
+      res.writeHead(404);
+      res.end("Not found");
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address() as { port: number };
+      const port = addr.port;
+
+      console.error(`\x1b[33m▸ Opening browser for Devin login...\x1b[0m`);
+      console.error(`  Local server: http://localhost:${port}\n`);
+
+      openBrowser(`http://localhost:${port}`);
+
+      // Timeout after 5 minutes
+      setTimeout(() => {
+        if (!receivedToken) {
+          server.close();
+          reject(new Error("Login timed out after 5 minutes."));
+        }
+      }, 5 * 60 * 1000);
+    });
+
+    server.on("error", reject);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface GetTokenOptions {
+  noCache?: boolean;
+}
+
+/**
+ * Get a valid Devin API auth token. Strategy:
+ * 1. DEVIN_TOKEN env var (for CI/scripts)
+ * 2. Cached token from disk (if not expired)
+ * 3. Interactive login via system browser + localhost callback
+ */
+export async function getToken(opts?: GetTokenOptions): Promise<string> {
+  // 1. Environment variable override
+  const envToken = process.env["DEVIN_TOKEN"];
+  if (envToken && envToken.length > 0) {
+    return envToken;
+  }
+
+  // 2. Cached token
+  if (!opts?.noCache) {
+    const cached = readCachedToken();
+    if (cached && isTokenValid(cached)) {
+      return cached.accessToken;
+    }
+  }
+
+  // 3. Interactive login via browser
+  const { token } = await startCallbackServer();
+  console.error("\x1b[32m✓ Authentication successful!\x1b[0m\n");
+  writeCachedToken(token);
+  return token;
+}
+
+/** Force re-authentication by clearing cache and launching browser */
+export async function forceReauth(): Promise<string> {
+  clearCachedToken();
+  const { token } = await startCallbackServer();
+  console.error("\x1b[32m✓ Authentication successful!\x1b[0m\n");
+  writeCachedToken(token);
+  return token;
+}
+
+/** Clear stored credentials */
+export function clearAuth(): void {
+  clearCachedToken();
+  console.error("Cleared cached token.");
+}

package/src/cli.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env bun
+
+import { parseArgs } from "node:util";
+import { parsePR } from "./parse-pr.js";
+import { getToken, forceReauth } from "./auth.js";
+import { fetchDigest, AuthExpiredError, ApiError } from "./api.js";
+import { extractFlags } from "./filter.js";
+import { formatTerminal, formatJSON } from "./format.js";
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+const HELP = `
+  \x1b[1mdevin-bugs\x1b[0m — Extract unresolved bugs from Devin AI code reviews
+
+  \x1b[1mUsage:\x1b[0m
+    devin-bugs <pr> [options]
+
+  \x1b[1mArguments:\x1b[0m
+    pr              GitHub PR URL or shorthand
+                    Examples: owner/repo#123
+                              https://github.com/owner/repo/pull/123
+                              https://app.devin.ai/review/owner/repo/pull/123
+
+  \x1b[1mOptions:\x1b[0m
+    --json          Output as JSON (for piping)
+    --all           Include analysis/suggestions, not just bugs
+    --raw           Dump raw API response (debug)
+    --no-cache      Force re-authentication
+    --login         Just authenticate, don't fetch anything
+    --logout        Clear stored credentials
+    --help, -h      Show this help
+    --version, -v   Show version
+
+  \x1b[1mEnvironment:\x1b[0m
+    DEVIN_TOKEN     Skip browser auth, use this token directly
+
+  \x1b[1mExamples:\x1b[0m
+    devin-bugs owner/repo#46
+    devin-bugs owner/repo#46 --json
+    devin-bugs owner/repo#46 --all --raw
+    DEVIN_TOKEN=xxx devin-bugs owner/repo#46
+`;
+
+function printHelp(): void {
+  console.log(HELP);
+}
+
+function printVersion(): void {
+  console.log("devin-bugs 0.1.0");
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      allowPositionals: true,
+      options: {
+        json: { type: "boolean", default: false },
+        all: { type: "boolean", default: false },
+        raw: { type: "boolean", default: false },
+        "no-cache": { type: "boolean", default: false },
+        login: { type: "boolean", default: false },
+        logout: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+        version: { type: "boolean", short: "v", default: false },
+      },
+    });
+  } catch (err: any) {
+    console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+    process.exit(1);
+  }
+
+  const { values, positionals } = parsed;
+
+  if (values.help) {
+    printHelp();
+    return;
+  }
+  if (values.version) {
+    printVersion();
+    return;
+  }
+
+  // --logout: clear credentials and exit
+  if (values.logout) {
+    const { clearAuth } = await import("./auth.js");
+    clearAuth();
+    return;
+  }
+
+  // --login: just authenticate and exit
+  if (values.login) {
+    const token = await getToken({ noCache: values["no-cache"] });
+    console.error("\x1b[32m✓ Authenticated successfully.\x1b[0m");
+    console.error(`  Token cached for future use.\n`);
+    // Show token expiry
+    try {
+      const payload = JSON.parse(
+        Buffer.from(token.split(".")[1]!, "base64url").toString()
+      );
+      const exp = new Date(payload.exp * 1000);
+      console.error(`  Expires: ${exp.toLocaleString()}`);
+    } catch {
+      // ignore
+    }
+    return;
+  }
+
+  // Require a PR argument
+  if (positionals.length === 0) {
+    console.error("\x1b[31mError:\x1b[0m Missing PR argument.\n");
+    printHelp();
+    process.exit(1);
+  }
+
+  const prInput = positionals[0]!;
+  let pr;
+  try {
+    pr = parsePR(prInput);
+  } catch (err: any) {
+    console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+    process.exit(1);
+  }
+
+  // Get auth token
+  let token: string;
+  try {
+    token = await getToken({ noCache: values["no-cache"] });
+  } catch (err: any) {
+    console.error(`\x1b[31mAuth error:\x1b[0m ${err.message}`);
+    process.exit(1);
+  }
+
+  // Fetch digest (with one retry on auth failure)
+  let digest;
+  try {
+    digest = await fetchDigest(pr.prPath, token);
+  } catch (err) {
+    if (err instanceof AuthExpiredError) {
+      // Re-authenticate and retry
+      console.error("\x1b[33m▸ Token expired, re-authenticating...\x1b[0m");
+      try {
+        token = await forceReauth();
+        digest = await fetchDigest(pr.prPath, token);
+      } catch (retryErr: any) {
+        console.error(`\x1b[31mError:\x1b[0m ${retryErr.message}`);
+        process.exit(1);
+      }
+    } else if (err instanceof ApiError) {
+      if (err.status === 404) {
+        console.error(
+          `\x1b[31mError:\x1b[0m PR not found or no Devin review exists for ${pr.owner}/${pr.repo}#${pr.number}`
+        );
+      } else {
+        console.error(`\x1b[31mAPI error ${err.status}:\x1b[0m ${err.body}`);
+      }
+      process.exit(1);
+    } else {
+      throw err;
+    }
+  }
+
+  // --raw: dump full response
+  if (values.raw) {
+    console.log(JSON.stringify(digest, null, 2));
+    return;
+  }
+
+  // Extract and filter flags
+  const flags = extractFlags(digest!, {
+    includeAnalysis: values.all,
+  });
+
+  // Output
+  if (values.json) {
+    console.log(formatJSON(flags));
+  } else {
+    console.log(formatTerminal(flags, pr));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+main().catch((err) => {
+  console.error(`\x1b[31mFatal error:\x1b[0m ${err.message ?? err}`);
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,14 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEVIN_API_BASE = "https://app.devin.ai/api";
+export const DEVIN_APP_URL = "https://app.devin.ai";
+export const DEVIN_LOGIN_URL = "https://app.devin.ai/auth/login";
+
+export const CONFIG_DIR = join(homedir(), ".config", "devin-bugs");
+export const CACHE_DIR = join(homedir(), ".cache", "devin-bugs");
+export const TOKEN_PATH = join(CONFIG_DIR, "token.json");
+export const BROWSER_DATA_DIR = join(CACHE_DIR, "browser-profile");
+
+/** Refresh token if less than this many seconds until expiry */
+export const TOKEN_REFRESH_MARGIN_SEC = 300;

package/src/filter.ts

@@ -0,0 +1,183 @@
+import type { DigestResponse, ReviewThread, ReviewComment, LifeguardFlag } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Parse hidden_header: <!-- devin-review-comment {JSON} -->
+// ---------------------------------------------------------------------------
+
+interface HiddenHeaderData {
+  id: string;
+  file_path: string;
+  start_line: number;
+  end_line: number;
+  side: "LEFT" | "RIGHT";
+}
+
+function parseHiddenHeader(header: string | null | undefined): HiddenHeaderData | null {
+  if (!header) return null;
+
+  // Format: <!-- devin-review-comment {"id":"...","file_path":"...","start_line":N,...} -->
+  const match = header.match(/<!--\s*devin-review-comment\s*(\{.+\})\s*-->/);
+  if (!match?.[1]) return null;
+
+  try {
+    const data = JSON.parse(match[1]) as Record<string, unknown>;
+    return {
+      id: String(data.id ?? ""),
+      file_path: String(data.file_path ?? ""),
+      start_line: typeof data.start_line === "number" ? data.start_line : 0,
+      end_line: typeof data.end_line === "number" ? data.end_line : 0,
+      side: data.side === "LEFT" ? "LEFT" : "RIGHT",
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Parse bug body: emoji severity + bold title + description
+// ---------------------------------------------------------------------------
+
+function parseSeverity(body: string): string {
+  if (body.startsWith("🔴")) return "severe";
+  if (body.startsWith("🟡")) return "warning";
+  if (body.startsWith("🟢")) return "info";
+  return "info";
+}
+
+function parseTitle(body: string): string {
+  const match = body.match(/\*\*(.+?)\*\*/);
+  return match?.[1]?.trim() ?? body.split("\n")[0]?.slice(0, 120).trim() ?? "";
+}
+
+function parseDescription(body: string): string {
+  // Everything after the first line (title line)
+  const lines = body.split("\n");
+  return lines
+    .slice(1)
+    .join("\n")
+    .trim();
+}
+
+function parseRecommendation(body: string): string {
+  // Look for "Recommendation:" or "Fix:" or "→" sections
+  const match = body.match(/(?:recommendation|suggested fix|fix):\s*(.+?)(?:\n\n|\n#+|\n🔴|\n🟡|$)/is);
+  return match?.[1]?.trim() ?? "";
+}
+
+// ---------------------------------------------------------------------------
+// Determine flag type from the comment body/id
+// ---------------------------------------------------------------------------
+
+function determineType(id: string, body: string): LifeguardFlag["type"] {
+  if (id.startsWith("BUG_")) return "lifeguard-bug";
+  if (id.startsWith("ANALYSIS_") || id.startsWith("INFO_")) return "lifeguard-analysis";
+
+  // Fallback: check body for bug indicators
+  const lower = body.toLowerCase();
+  if (
+    lower.includes("potential bug") ||
+    lower.includes("🔴") ||
+    lower.includes("bug:") ||
+    lower.includes("race condition") ||
+    lower.includes("vulnerability") ||
+    lower.includes("double-charge") ||
+    lower.includes("sql injection")
+  ) {
+    return "lifeguard-bug";
+  }
+  return "lifeguard-analysis";
+}
+
+// ---------------------------------------------------------------------------
+// Extract a LifeguardFlag from a Devin review thread
+// ---------------------------------------------------------------------------
+
+function extractFlag(
+  thread: ReviewThread,
+  comment: ReviewComment
+): LifeguardFlag | null {
+  const header = parseHiddenHeader(comment.hidden_header);
+  const body = comment.body ?? "";
+  if (!body && !header) return null;
+
+  const id = header?.id ?? String(comment.devin_review_id ?? "");
+  const type = determineType(id, body);
+
+  return {
+    filePath: header?.file_path ?? "",
+    startLine: header?.start_line ?? null,
+    endLine: header?.end_line ?? null,
+    side: header?.side ?? "RIGHT",
+    title: parseTitle(body),
+    description: parseDescription(body),
+    severity: parseSeverity(body),
+    recommendation: parseRecommendation(body),
+    needsInvestigation: body.toLowerCase().includes("needs investigation"),
+    type,
+    isResolved: thread.is_resolved,
+    isOutdated: thread.is_outdated,
+    htmlUrl: comment.html_url ?? null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Identify Devin review comments
+// ---------------------------------------------------------------------------
+
+function isDevinComment(comment: ReviewComment): boolean {
+  return (
+    comment.devin_review_id != null ||
+    comment.hidden_header?.includes("devin-review-comment") === true ||
+    comment.author?.login === "devin-ai-integration" ||
+    comment.author?.login === "devin-ai-integration[bot]" ||
+    comment.author?.login === "devin-ai[bot]"
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface FilterOptions {
+  /** Include lifeguard-analysis items, not just bugs */
+  includeAnalysis?: boolean;
+  /** Include resolved items */
+  includeResolved?: boolean;
+  /** Include outdated items */
+  includeOutdated?: boolean;
+}
+
+/**
+ * Extract all LifeguardFlags from a digest response.
+ * Default: only unresolved, non-outdated bugs.
+ */
+export function extractFlags(
+  digest: DigestResponse,
+  opts?: FilterOptions
+): LifeguardFlag[] {
+  const flags: LifeguardFlag[] = [];
+
+  for (const thread of digest.review_threads) {
+    // Apply thread-level filters
+    if (!opts?.includeResolved && thread.is_resolved) continue;
+    if (!opts?.includeOutdated && thread.is_outdated) continue;
+
+    // Extract from first Devin comment in the thread
+    for (const comment of thread.comments) {
+      if (!isDevinComment(comment)) continue;
+
+      const flag = extractFlag(thread, comment);
+      if (flag) {
+        flags.push(flag);
+        break; // One flag per thread
+      }
+    }
+  }
+
+  // Filter by type
+  if (!opts?.includeAnalysis) {
+    return flags.filter((f) => f.type === "lifeguard-bug");
+  }
+
+  return flags;
+}

package/src/format.ts

@@ -0,0 +1,162 @@
+import type { LifeguardFlag, ParsedPR } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// ANSI color helpers (no dependency)
+// ---------------------------------------------------------------------------
+
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  bgRed: "\x1b[41m",
+  bgYellow: "\x1b[43m",
+  bgBlue: "\x1b[44m",
+};
+
+function severityColor(severity: string): string {
+  switch (severity.toLowerCase()) {
+    case "severe":
+    case "critical":
+      return c.red;
+    case "warning":
+      return c.yellow;
+    default:
+      return c.cyan;
+  }
+}
+
+function severityBadge(severity: string): string {
+  const upper = severity.toUpperCase();
+  switch (severity.toLowerCase()) {
+    case "severe":
+    case "critical":
+      return `${c.bgRed}${c.white}${c.bold} ${upper} ${c.reset}`;
+    case "warning":
+      return `${c.bgYellow}${c.bold} ${upper} ${c.reset}`;
+    default:
+      return `${c.bgBlue}${c.white} ${upper} ${c.reset}`;
+  }
+}
+
+function typeBadge(type: LifeguardFlag["type"]): string {
+  if (type === "lifeguard-bug") {
+    return `${c.red}${c.bold}BUG${c.reset}`;
+  }
+  return `${c.cyan}${c.bold}INFO${c.reset}`;
+}
+
+// ---------------------------------------------------------------------------
+// Terminal formatter
+// ---------------------------------------------------------------------------
+
+function formatLocation(flag: LifeguardFlag): string {
+  if (!flag.filePath) return "";
+  const file = `${c.cyan}${flag.filePath}${c.reset}`;
+  if (flag.startLine == null) return file;
+  const line =
+    flag.endLine != null && flag.endLine !== flag.startLine
+      ? `${c.dim}:${flag.startLine}-${flag.endLine}${c.reset}`
+      : `${c.dim}:${flag.startLine}${c.reset}`;
+  return `${file}${line}`;
+}
+
+function wrapText(text: string, indent: number, maxWidth: number): string {
+  const pad = " ".repeat(indent);
+  const words = text.split(/\s+/);
+  const lines: string[] = [];
+  let current = "";
+
+  for (const word of words) {
+    if (current.length + word.length + 1 > maxWidth - indent) {
+      lines.push(pad + current);
+      current = word;
+    } else {
+      current = current ? `${current} ${word}` : word;
+    }
+  }
+  if (current) lines.push(pad + current);
+  return lines.join("\n");
+}
+
+export function formatTerminal(flags: LifeguardFlag[], pr: ParsedPR): string {
+  const lines: string[] = [];
+
+  // Header
+  const bugCount = flags.filter((f) => f.type === "lifeguard-bug").length;
+  const analysisCount = flags.filter((f) => f.type === "lifeguard-analysis").length;
+
+  const parts: string[] = [];
+  if (bugCount > 0) parts.push(`${c.red}${c.bold}${bugCount} bug${bugCount === 1 ? "" : "s"}${c.reset}`);
+  if (analysisCount > 0) parts.push(`${c.cyan}${analysisCount} suggestion${analysisCount === 1 ? "" : "s"}${c.reset}`);
+
+  if (parts.length === 0) {
+    lines.push(`\n  ${c.green}${c.bold}No unresolved bugs${c.reset} in ${c.dim}${pr.owner}/${pr.repo}#${pr.number}${c.reset}\n`);
+    return lines.join("\n");
+  }
+
+  lines.push(
+    `\n  ${parts.join(", ")} in ${c.dim}${pr.owner}/${pr.repo}#${pr.number}${c.reset}\n`
+  );
+
+  // Each flag
+  for (const flag of flags) {
+    const badge = typeBadge(flag.type);
+    const location = formatLocation(flag);
+    const sev = severityBadge(flag.severity);
+
+    lines.push(`  ${badge}  ${location}  ${sev}`);
+
+    if (flag.title) {
+      lines.push(`  ${c.bold}${c.white}${flag.title}${c.reset}`);
+    }
+
+    // Show description (first paragraph, stripped of markdown/HTML noise)
+    if (flag.description && flag.description !== flag.title) {
+      const desc = flag.description
+        .replace(/<details>[\s\S]*?<\/details>/g, "") // remove <details> blocks
+        .replace(/<!--[\s\S]*?-->/g, "") // remove HTML comments
+        .replace(/^\[.*?\]\(.*?\)$/gm, "") // remove markdown links on own line
+        .replace(/<a[\s\S]*?<\/a>/g, "") // remove <a> tags
+        .replace(/<picture>[\s\S]*?<\/picture>/g, "") // remove <picture> tags
+        .replace(/<img[^>]*>/g, "") // remove <img> tags
+        .replace(/^---\s*$/gm, "") // remove horizontal rules
+        .replace(/^\*Was this helpful\?.*$/gm, "") // remove feedback prompt
+        .replace(/^#+\s*.+$/gm, "") // remove headings
+        .replace(/\*\*(.+?)\*\*/g, "$1") // remove bold markers
+        .replace(/`([^`]+)`/g, "$1") // remove inline code markers
+        .trim()
+        .split("\n\n")[0]! // first paragraph only
+        .split("\n")
+        .filter((l) => l.trim())
+        .join(" ")
+        .trim();
+
+      if (desc) {
+        lines.push(wrapText(`${c.dim}${desc}${c.reset}`, 2, 100));
+      }
+    }
+
+    if (flag.recommendation) {
+      lines.push(
+        `  ${c.green}→ ${flag.recommendation}${c.reset}`
+      );
+    }
+
+    lines.push(""); // blank line between flags
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// JSON formatter
+// ---------------------------------------------------------------------------
+
+export function formatJSON(flags: LifeguardFlag[]): string {
+  return JSON.stringify(flags, null, 2);
+}

package/src/parse-pr.ts

@@ -0,0 +1,33 @@
+import type { ParsedPR } from "./types.js";
+
+const GITHUB_URL_RE =
+  /(?:https?:\/\/)?github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/;
+const SHORTHAND_RE = /^([^/#]+)\/([^/#]+)#(\d+)$/;
+const PATH_RE = /^([^/#]+)\/([^/#]+)\/pull\/(\d+)$/;
+
+/** Also accept Devin review URLs: app.devin.ai/review/owner/repo/pull/123 */
+const DEVIN_URL_RE =
+  /(?:https?:\/\/)?app\.devin\.ai\/review\/([^/]+)\/([^/]+)\/pull\/(\d+)/;
+
+export function parsePR(input: string): ParsedPR {
+  const match =
+    input.match(GITHUB_URL_RE) ??
+    input.match(DEVIN_URL_RE) ??
+    input.match(SHORTHAND_RE) ??
+    input.match(PATH_RE);
+
+  if (!match) {
+    throw new Error(
+      `Invalid PR reference: ${input}\n` +
+        `Expected: owner/repo#123 or https://github.com/owner/repo/pull/123`
+    );
+  }
+
+  const [, owner, repo, num] = match;
+  return {
+    owner: owner!,
+    repo: repo!,
+    number: parseInt(num!, 10),
+    prPath: `github.com/${owner}/${repo}/pull/${num}`,
+  };
+}

package/src/types.ts

@@ -0,0 +1,106 @@
+// ---------------------------------------------------------------------------
+// PR reference
+// ---------------------------------------------------------------------------
+
+export interface ParsedPR {
+  owner: string;
+  repo: string;
+  number: number;
+  /** e.g. "github.com/owner/repo/pull/123" */
+  prPath: string;
+}
+
+// ---------------------------------------------------------------------------
+// Cached auth token
+// ---------------------------------------------------------------------------
+
+export interface CachedToken {
+  accessToken: string;
+  /** epoch ms when token was obtained */
+  obtainedAt: number;
+  /** epoch ms when token expires (from JWT `exp` claim) */
+  expiresAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Devin Digest API response (partial — fields we care about)
+// ---------------------------------------------------------------------------
+
+export interface DigestResponse {
+  id: number;
+  title: string;
+  state: string;
+  author?: { login: string; avatar_url?: string; is_bot?: boolean };
+  head_ref: string;
+  base_ref: string;
+  additions: number;
+  deletions: number;
+  review_threads: ReviewThread[];
+  comments: ReviewComment[];
+  reviews: Review[];
+  checks: Check[];
+  [key: string]: unknown;
+}
+
+export interface ReviewThread {
+  is_resolved: boolean;
+  is_outdated: boolean;
+  resolved_by?: { login: string; avatar_url?: string } | null;
+  comments: ReviewComment[];
+}
+
+export interface ReviewComment {
+  id: number | string;
+  body: string;
+  body_html?: string;
+  /** Non-null means this is a Devin review comment */
+  devin_review_id?: string | null;
+  /** Structured metadata header hidden from display */
+  hidden_header?: string | null;
+  html_url?: string | null;
+  author?: { login: string; avatar_url?: string; is_bot?: boolean };
+  pull_request_review?: { id: number; state: string } | null;
+  reaction_groups?: unknown[];
+  [key: string]: unknown;
+}
+
+export interface Review {
+  id: number;
+  body: string;
+  body_html?: string;
+  state: string;
+  author?: { login: string; avatar_url?: string; is_bot?: boolean };
+  devin_review_id?: string | null;
+  [key: string]: unknown;
+}
+
+export interface Check {
+  id: string;
+  name: string;
+  status: string;
+  conclusion: string | null;
+  workflow_name?: string;
+  is_required?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Extracted bug/flag
+// ---------------------------------------------------------------------------
+
+export interface LifeguardFlag {
+  filePath: string;
+  startLine: number | null;
+  endLine: number | null;
+  side: "LEFT" | "RIGHT";
+  title: string;
+  description: string;
+  severity: string;
+  recommendation: string;
+  needsInvestigation: boolean;
+  type: "lifeguard-bug" | "lifeguard-analysis";
+  /** Source thread resolution status */
+  isResolved: boolean;
+  isOutdated: boolean;
+  /** URL to the comment on GitHub */
+  htmlUrl: string | null;
+}