secura-cli 0.1.4

package/src/help.mjs

@@ -0,0 +1,66 @@
+/** Help / usage text for the `secura` CLI. */
+
+import { bold, dim, cyan } from "./ansi.mjs";
+
+export function printHelp() {
+  const p = (s = "") => process.stdout.write(s + "\n");
+  p();
+  p(`${bold("secura")} — AuthTrack static analysis (SAST) from the command line`);
+  p();
+  p("Streams a five-scanner scan (Semgrep, Bearer, OSV-Scanner, Gitleaks, CodeQL)");
+  p("from the AuthTrack backend and renders it live in your terminal.");
+  p();
+  p(bold("USAGE"));
+  p(`  secura scan [target] [options]`);
+  p(`  secura version`);
+  p(`  secura --help`);
+  p();
+  p(bold("TARGETS"));
+  p(`  ${cyan(".")}                        the current directory (default)`);
+  p(`  ${cyan("./path/to/repo")}           a local folder`);
+  p(`  ${cyan("owner/repo")}               a public GitHub repo (shorthand)`);
+  p(`  ${cyan("https://github.com/o/r")}   any public Git URL (cloned by the backend)`);
+  p();
+  p(bold("COMMON"));
+  p(`  secura scan .`);
+  p(`  secura scan owner/repo --fast`);
+  p(`  secura scan . --fail-on high            ${dim("# CI gate")}`);
+  p(`  secura scan . --json report.json`);
+  p();
+  p(`Run ${cyan("secura scan --help")} for every flag.`);
+  p();
+}
+
+export function printScanHelp() {
+  const p = (s = "") => process.stdout.write(s + "\n");
+  p();
+  p(`${bold("secura scan")} [target] [options]`);
+  p();
+  p("Fans out to five scanners at once, merges and deduplicates their findings,");
+  p("retrieves similar known-vulnerable patterns, then has an LLM confirm or rule");
+  p("out each finding and write a patch for the confirmed ones.");
+  p();
+  p(bold("OPTIONS"));
+  p(`  -f, --fast                 Skip CodeQL (its DB build dominates the run).`);
+  p(`  -l, --language <lang>      CodeQL language (javascript, python, java, go,`);
+  p(`                             ruby, csharp, cpp). Auto-detected when omitted.`);
+  p(`  -t, --max-triage <n>       Cap findings sent to LLM triage (default 25).`);
+  p(`      --fail-on <sev>        Exit 1 if a confirmed finding is ≥ this severity`);
+  p(`                             (critical|high|medium|low). For CI gates.`);
+  p(`  -o, --json <path>          Write the full report as JSON to <path>.`);
+  p(`      --max-findings <n>     How many confirmed findings to print (default 20).`);
+  p(`      --show-fixes           Print the generated fix diffs in full.`);
+  p(`  -q, --quiet                Suppress the live view; print only the report.`);
+  p();
+  p(bold("BACKEND"));
+  p(`      --api <url>            Backend base URL`);
+  p(`                             (default $SECURA_API or http://localhost:8000/api/v1).`);
+  p(`      --token <token>        Bearer token, if the backend requires one`);
+  p(`                             (default $SECURA_TOKEN).`);
+  p(`      --upload               Package the local dir and upload it, even for a`);
+  p(`                             local backend. Automatic for a remote --api.`);
+  p();
+  p(bold("EXIT CODES"));
+  p(`  0  clean      1  --fail-on breached      2  bad target / failure      130  interrupted`);
+  p();
+}

package/src/monitor.mjs

@@ -0,0 +1,157 @@
+/**
+ * Port of ScanMonitor (backend/app/cli/main.py): fold each `node_update` event
+ * into the running totals the terminal view needs.
+ *
+ * The graph streams one update per completed node, and the triage loop streams
+ * one per finding, so state is accumulated here rather than re-derived from any
+ * single partial snapshot — identical semantics to the Python monitor.
+ */
+
+// Mirrors frontend/src/lib/static-analysis.ts and main.py so the CLI and the
+// web UI describe the same five engines in the same words.
+export const TOOL_ORDER = ["semgrep", "bearer", "osv-scanner", "gitleaks", "codeql"];
+
+export const TOOL_KIND = {
+  semgrep: "SAST",
+  bearer: "SAST + privacy",
+  "osv-scanner": "SCA",
+  gitleaks: "Secrets",
+  codeql: "Taint analysis",
+};
+
+// Backend graph node name → the tool whose row it fills in.
+const NODE_TO_TOOL = {
+  run_semgrep: "semgrep",
+  run_bearer: "bearer",
+  run_osv_scanner: "osv-scanner",
+  run_gitleaks: "gitleaks",
+  run_codeql: "codeql",
+};
+
+export const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
+
+export const STAGE_LABELS = {
+  dispatch: "Resolving target",
+  scan: "Running 5 scanners in parallel",
+  merge: "Merging and deduplicating",
+  rag: "Retrieving similar known-vulnerable patterns",
+  triage: "AI triage",
+  fixes: "Generating fixes",
+  report: "Building report",
+  done: "Complete",
+};
+
+export class ScanMonitor {
+  constructor(target, includeCodeql) {
+    this.target = target;
+    this.includeCodeql = includeCodeql;
+    this.started = Date.now();
+    this.stage = "dispatch";
+    this.language = "detecting…";
+
+    this.tools = {};
+    for (const name of TOOL_ORDER) {
+      this.tools[name] = { state: "pending", count: 0, duration: 0, note: "", sample: false };
+    }
+    if (!includeCodeql) {
+      this.tools.codeql = {
+        state: "skipped", count: 0, duration: 0, note: "skipped (--fast)", sample: false,
+      };
+    }
+
+    this.mergeStats = {};
+    this.safePatterns = 0;
+    this.ragMatched = null;
+    this.ragTotal = 0;
+
+    this.triageDone = 0;
+    this.triageTotal = 0;
+    this.confirmed = 0;
+    this.discarded = 0;
+
+    this.fixes = 0;
+    this.report = {};
+    this.errors = [];
+  }
+
+  startScanners() {
+    for (const row of Object.values(this.tools)) {
+      if (row.state === "pending") row.state = "running";
+    }
+  }
+
+  elapsedSeconds() {
+    return (Date.now() - this.started) / 1000;
+  }
+
+  /** Fold one `node_update` into the running totals. */
+  ingest(node, state) {
+    const s = state || {};
+
+    if (node === "dispatch") {
+      this.language = s.codeql_language || "auto";
+      this.stage = "scan";
+      this.startScanners();
+      return;
+    }
+
+    if (node in NODE_TO_TOOL) {
+      const tool = NODE_TO_TOOL[node];
+      const status = (s.tool_status || {})[tool] || {};
+      const skipped = String(status.note || "").toLowerCase().includes("skipped");
+      this.tools[tool] = {
+        state: skipped ? "skipped" : status.ok ? "ok" : "failed",
+        count: status.finding_count || 0,
+        duration: status.duration_s || 0,
+        note: status.note || "",
+        sample: Boolean(status.used_sample),
+      };
+      return;
+    }
+
+    if (node === "merge_findings") {
+      this.stage = "merge";
+      this.mergeStats = s.merge_stats || {};
+      this.safePatterns = (s.safe_patterns || []).length;
+      return;
+    }
+
+    if (node === "retrieve_context") {
+      this.stage = "rag";
+      const findings = s.merged_findings || [];
+      this.ragTotal = findings.length;
+      this.ragMatched = findings.filter((f) => (f.context || []).length).length;
+      return;
+    }
+
+    if (node === "triage") {
+      this.stage = "triage";
+      const progress = s.triage_progress || {};
+      if (progress.done !== undefined && progress.done !== null) this.triageDone = progress.done;
+      if (progress.total !== undefined && progress.total !== null) this.triageTotal = progress.total;
+      return;
+    }
+
+    if (node === "confirm_finding") {
+      this.confirmed += (s.triaged_findings || []).length || 1;
+      return;
+    }
+
+    if (node === "discard_finding") {
+      this.discarded += (s.false_positives || []).length || 1;
+      return;
+    }
+
+    if (node === "fix_generator") {
+      this.stage = "fixes";
+      this.fixes = (s.fixes || []).length;
+      this.errors.push(...(s.errors || []));
+      return;
+    }
+
+    if (node === "report_builder") {
+      this.stage = "report";
+      this.report = s.static_report || {};
+    }
+  }
+}

package/src/pack.mjs

@@ -0,0 +1,119 @@
+/**
+ * Package a local directory as a gzipped tarball for upload to a remote backend.
+ *
+ * The tree is walked in Node — skipping the same directories/files the scanners
+ * ignore, and never following symlinks — and the resulting relative file list is
+ * handed to the system `tar` via `-T`. Walking ourselves (rather than leaning on
+ * tar's `--exclude` globbing, which differs between GNU tar and bsdtar) keeps the
+ * archive contents identical on Windows, macOS and Linux, and guarantees only
+ * regular files under the root make it in.
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// CLI-side cap on the packaged archive; the backend enforces its own uncompressed
+// limits on extraction. A repo bigger than this should be scanned as a Git URL.
+export const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100 MB
+
+// Mirrors EXCLUDE_DIRS / EXCLUDE_GLOBS in
+// backend/app/agents/static_analysis/tools.py.
+const EXCLUDE_DIRS = new Set([
+  "node_modules", ".git", ".venv", "venv", "__pycache__", "dist", "build",
+  ".next", "out", "coverage", "vendor", "site-packages", "target",
+  ".mypy_cache", ".pytest_cache", ".ruff_cache", ".turbo", ".cache",
+]);
+const EXCLUDE_SUFFIXES = [".min.js", ".min.css", ".map", ".lock", ".bundle.js"];
+
+const isExcludedFile = (name) => EXCLUDE_SUFFIXES.some((s) => name.endsWith(s));
+
+export function hasTar() {
+  try {
+    const r = spawnSync("tar", ["--version"], { stdio: "ignore" });
+    return !r.error && r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function walk(root) {
+  const files = [];
+  const stack = [""]; // relative paths, "" = root
+  while (stack.length) {
+    const rel = stack.pop();
+    const abs = rel ? path.join(root, rel) : root;
+    let entries;
+    try {
+      entries = fs.readdirSync(abs, { withFileTypes: true });
+    } catch {
+      continue; // unreadable directory — skip it
+    }
+    for (const ent of entries) {
+      if (ent.isSymbolicLink()) continue; // never archive links
+      const childRel = rel ? `${rel}/${ent.name}` : ent.name;
+      if (ent.isDirectory()) {
+        if (!EXCLUDE_DIRS.has(ent.name)) stack.push(childRel);
+      } else if (ent.isFile() && !isExcludedFile(ent.name)) {
+        files.push(childRel); // forward-slashed; tar accepts these on Windows too
+      }
+    }
+  }
+  return files;
+}
+
+function safeUnlink(p) {
+  try {
+    fs.unlinkSync(p);
+  } catch {
+    /* already gone */
+  }
+}
+
+/**
+ * Build the tarball. Returns { path, fileCount, cleanup }. `cleanup()` removes
+ * the archive and must be called by the caller once the upload finishes.
+ */
+export function packDir(dir) {
+  if (!hasTar()) {
+    throw new Error(
+      "`tar` was not found on your PATH, so local code can't be packaged for a remote backend.\n" +
+      "  Fixes: install tar (bundled with Windows 10 1803+, macOS and Linux),\n" +
+      "         scan a public Git repo URL instead (the backend clones it),\n" +
+      "         or run the backend on this machine and drop --upload."
+    );
+  }
+
+  const files = walk(dir);
+  if (files.length === 0) {
+    throw new Error(`Nothing to scan under ${dir} (it's empty, or every file is excluded).`);
+  }
+
+  const stamp = `${process.pid}-${Date.now()}`;
+  const listPath = path.join(os.tmpdir(), `secura-files-${stamp}.txt`);
+  const archivePath = path.join(os.tmpdir(), `secura-upload-${stamp}.tar.gz`);
+
+  try {
+    fs.writeFileSync(listPath, files.join("\n") + "\n", "utf8");
+    // -C dir + relative names → the paths archive at the tarball root.
+    const r = spawnSync("tar", ["-czf", archivePath, "-C", dir, "-T", listPath], {
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+    if (r.error) throw r.error;
+    if (r.status !== 0) {
+      const stderr = r.stderr ? r.stderr.toString().trim() : "";
+      throw new Error(`tar exited ${r.status}${stderr ? `: ${stderr}` : ""}`);
+    }
+    return {
+      path: archivePath,
+      fileCount: files.length,
+      cleanup: () => safeUnlink(archivePath),
+    };
+  } catch (err) {
+    safeUnlink(archivePath);
+    throw new Error(`Failed to package ${dir}: ${err.message}`);
+  } finally {
+    safeUnlink(listPath); // the list is consumed by tar; drop it either way
+  }
+}

package/src/render.mjs

@@ -0,0 +1,271 @@
+/**
+ * Terminal rendering: the in-place live view during a run, and the final report.
+ *
+ * Ports renderable() / _tool_table() / _print_report() from
+ * backend/app/cli/main.py — same layout, same severity colours, same wording —
+ * but with hand-rolled ANSI instead of Rich, so the package stays dependency-free.
+ */
+
+import {
+  bold, dim, red, green, yellow, blue, magenta, cyan, gray,
+  severityText, clip, visibleLength, hideCursor, showCursor, colorEnabled,
+} from "./ansi.mjs";
+import { TOOL_ORDER, TOOL_KIND, STAGE_LABELS } from "./monitor.mjs";
+
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+const termWidth = () => process.stdout.columns || 90;
+const reportWidth = () => Math.max(40, Math.min(termWidth(), 96));
+
+const padEnd = (s, n) => String(s).padEnd(n);
+const padStart = (s, n) => String(s).padStart(n);
+
+// ── Live view ────────────────────────────────────────────────────────────────
+
+function toolRow(name, row, frame) {
+  let mark;
+  switch (row.state) {
+    case "running": mark = blue(SPINNER[frame % SPINNER.length]); break;
+    case "ok": mark = green("✔"); break;
+    case "failed": mark = yellow("!"); break;
+    case "skipped": mark = dim("–"); break;
+    default: mark = dim("·");
+  }
+  const count = row.state === "pending" || row.state === "running" ? "—" : String(row.count);
+  const duration = row.duration ? `${row.duration.toFixed(1)}s` : "";
+  let note = row.note || "";
+  if (row.sample) note = note ? `sample data — ${note}` : "using sample data";
+
+  return (
+    `${mark} ${bold(padEnd(name, 11))} ${dim(padEnd(TOOL_KIND[name], 15))} ` +
+    `${padStart(count, 4)} ${dim(padStart(duration, 6))}  ${dim(note)}`
+  );
+}
+
+/** The multi-line live frame; mirrors ScanMonitor.renderable(). */
+export function renderLive(monitor, frame) {
+  const width = reportWidth();
+  const lines = [];
+
+  lines.push(bold("Static Analysis") + dim("  ·  5 scanners → merge → RAG triage → fixes"));
+  lines.push(`${dim("target   ")}${cyan(monitor.target)}`);
+  lines.push(`${dim("language ")}${monitor.language}`);
+  lines.push(
+    `${dim("stage    ")}${bold(blue(STAGE_LABELS[monitor.stage] || monitor.stage))}` +
+    dim(`   (${Math.round(monitor.elapsedSeconds())}s elapsed)`)
+  );
+  lines.push("");
+
+  for (const name of TOOL_ORDER) {
+    lines.push(toolRow(name, monitor.tools[name], frame));
+  }
+
+  if (monitor.mergeStats && Object.keys(monitor.mergeStats).length) {
+    const s = monitor.mergeStats;
+    lines.push(
+      `${dim("merge    ")}${s.total_raw || 0} raw ${dim("→")} ${bold(cyan(`${s.total_after_dedup || 0} unique`))}` +
+      dim(`  (${s.duplicates_removed || 0} duplicates removed, ${s.multi_tool_confirmed || 0} multi-tool, ${s.with_taint_path || 0} with taint path)`)
+    );
+  }
+  if (monitor.safePatterns) {
+    lines.push(green(`controls ${monitor.safePatterns} existing security control(s) detected`));
+  }
+  if (monitor.ragMatched !== null) {
+    lines.push(magenta(`rag      ${monitor.ragMatched}/${monitor.ragTotal} finding(s) matched a known-vulnerable pattern`));
+  }
+  if (monitor.triageTotal) {
+    lines.push(
+      `${dim("triage   ")}${blue(bar(monitor.triageDone, monitor.triageTotal))} ${monitor.triageDone}/${monitor.triageTotal}` +
+      `${dim("   confirmed ")}${bold(red(String(monitor.confirmed)))}${dim("   ruled out ")}${bold(gray(String(monitor.discarded)))}`
+    );
+  }
+  if (monitor.fixes) {
+    lines.push(green(`fixes    ${monitor.fixes} remediation(s) generated`));
+  }
+
+  return lines.map((l) => clip(l, width)).join("\n");
+}
+
+function bar(done, total, width = 24) {
+  if (total <= 0) return "░".repeat(width);
+  const filled = Math.max(0, Math.min(width, Math.round((width * done) / total)));
+  return "█".repeat(filled) + "░".repeat(width - filled);
+}
+
+/**
+ * Redraws a block of text in place by moving the cursor up over the previous
+ * frame and clearing to the end of the screen. No-op when stdout is not a TTY
+ * (piped / CI) — the run then prints nothing until the final report.
+ */
+export class LiveView {
+  constructor(stream = process.stdout) {
+    this.stream = stream;
+    this.lastLines = 0;
+    this.active = colorEnabled && Boolean(stream.isTTY);
+  }
+
+  start() {
+    if (this.active) hideCursor();
+  }
+
+  render(text) {
+    if (!this.active) return;
+    if (this.lastLines > 0) this.stream.write(`\x1b[${this.lastLines}A`); // cursor up
+    this.stream.write("\x1b[0J"); // clear to end of screen
+    this.stream.write(text + "\n");
+    this.lastLines = text.split("\n").length;
+  }
+
+  stop() {
+    if (this.active) showCursor();
+    this.lastLines = 0;
+  }
+}
+
+// ── Final report ───────────────────────────────────────────────────────────
+
+/** A rounded-border panel with a title, wrapping the body to fit. */
+function panel(title, body, width = reportWidth()) {
+  const inner = width - 4;
+  const bodyLines = [];
+  for (const para of String(body).split("\n")) {
+    const wrapped = wrapText(para, inner);
+    for (const w of wrapped) bodyLines.push(w);
+  }
+  const top = `╭─ ${bold(title)} ${"─".repeat(Math.max(0, width - visibleLength(title) - 5))}╮`;
+  const bottom = `╰${"─".repeat(width - 2)}╯`;
+  const mid = bodyLines.map((l) => `│ ${l}${" ".repeat(Math.max(0, inner - visibleLength(l)))} │`);
+  return [top, ...mid, bottom].join("\n");
+}
+
+function wrapText(text, width) {
+  if (width <= 0) return [text];
+  const words = text.split(/\s+/).filter(Boolean);
+  if (words.length === 0) return [""];
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    if (!line) {
+      line = word;
+    } else if (visibleLength(line) + 1 + visibleLength(word) <= width) {
+      line += ` ${word}`;
+    } else {
+      lines.push(line);
+      line = word;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+const out = (s = "") => process.stdout.write(s + "\n");
+
+/** Print the finished report: summary, per-tool accounting, then findings. */
+export function printReport(report, { showFixes = false, maxFindings = 20 } = {}) {
+  if (!report || Object.keys(report).length === 0) {
+    out(yellow("No report was produced."));
+    return;
+  }
+
+  out();
+  const repo = report.source_repo || "";
+  const scanned = repo || report.target_path || "";
+  if (scanned) out(dim("scanned  ") + cyan(scanned) + (repo ? dim("  (cloned)") : ""));
+  out(panel("Summary", report.summary || "No summary available."));
+
+  // ── Headline counters ──
+  out();
+  const counter = (label, value) => out(`  ${dim(padEnd(label, 30))}${value}`);
+  counter("unique findings", String(report.total_after_merge || 0));
+  counter("confirmed", red(String(report.confirmed_count || 0)));
+  counter("ruled out as false positives", String(report.ruled_out_count || 0));
+  if (report.not_triaged_count) counter("not triaged (cap reached)", String(report.not_triaged_count));
+  counter("fixes generated", green(String(report.fixes_count || 0)));
+  counter("with a CodeQL taint path", String(report.with_taint_path_count || 0));
+
+  // ── Severity breakdown of confirmed findings ──
+  const severities = report.severity_breakdown || {};
+  if (Object.keys(severities).length) {
+    out();
+    out(bold("Confirmed by severity"));
+    for (const name of ["critical", "high", "medium", "low", "info"]) {
+      if (severities[name]) out(`  ${padEnd(severityText(name), 18)} ${severities[name]}`);
+    }
+  }
+
+  // ── Per-tool contribution ──
+  const perTool = report.findings_per_tool || {};
+  if (Object.keys(perTool).length) {
+    out();
+    out(bold("Per-tool contribution"));
+    out(dim(`  ${padEnd("scanner", 13)}${padStart("raw", 5)}${padStart("after merge", 14)}${padStart("time", 8)}`));
+    for (const name of TOOL_ORDER) {
+      const e = perTool[name];
+      if (!e) continue;
+      const t = `${(e.duration_s || 0).toFixed(1)}s`;
+      out(`  ${padEnd(name, 13)}${padStart(String(e.raw || 0), 5)}${padStart(String(e.after_merge || 0), 14)}${dim(padStart(t, 8))}`);
+    }
+  }
+
+  // ── Confirmed findings ──
+  const confirmed = report.confirmed_findings || [];
+  if (confirmed.length) {
+    out();
+    out(bold("Confirmed findings"));
+    for (const f of confirmed.slice(0, maxFindings)) {
+      const evidence = f.taint_path
+        ? "taint path"
+        : f.multi_tool_confirmed
+        ? "multi-tool"
+        : "single tool";
+      out(
+        `  ${severityText(f.final_severity || f.severity)}  ${bold(f.category || "")}  ` +
+        `${cyan(`${f.file}:${f.line}`)}  ${dim(`[${evidence}]`)}`
+      );
+      if (f.rule_id) out(`      ${dim(f.rule_id)}`);
+      const reason = (f.triage_reason || "").trim();
+      if (reason) out(`      ${reason}`);
+      if (f.taint_path) {
+        const chain = f.taint_path.map((step) => `${step.file}:${step.line}`).join(" → ");
+        out(`      ${green("flow:")} ${dim(chain)}`);
+      }
+      out();
+    }
+    if (confirmed.length > maxFindings) {
+      out(dim(`  …and ${confirmed.length - maxFindings} more (raise with --max-findings)`));
+      out();
+    }
+  }
+
+  // ── Existing security controls ──
+  const safe = report.safe_patterns || [];
+  if (safe.length) {
+    out(bold(green("Security controls already in place")));
+    for (const p of safe) {
+      out(`  ${green("✔")} ${p.description || ""}`);
+      out(`      ${dim(`${p.path}:${p.line}`)}`);
+    }
+    out();
+  }
+
+  // ── Fixes ──
+  const fixes = report.fixes || [];
+  if (fixes.length && showFixes) {
+    out(bold("Generated fixes"));
+    for (const fix of fixes) {
+      out(`  ${cyan(`${fix.file}:${fix.line}`)} ${dim(`(${fix.rule_id}, grounded in ${fix.grounded_in})`)}`);
+      out(panel("diff", fix.diff_text || ""));
+      if (fix.explanation) out(`  ${fix.explanation}\n`);
+    }
+  } else if (fixes.length) {
+    out(dim(`${fixes.length} fix(es) generated — rerun with --show-fixes to print the diffs.`));
+  }
+
+  // ── Warnings ──
+  const errors = report.errors || [];
+  if (errors.length) {
+    out();
+    out(yellow("Warnings"));
+    for (const e of errors) out(`  ${yellow("•")} ${dim(e)}`);
+  }
+}

package/src/target.mjs

@@ -0,0 +1,52 @@
+/**
+ * Classify a scan target as a Git repo or a local path.
+ *
+ * Mirrors is_git_url / normalize_git_url in
+ * backend/app/agents/static_analysis/tools.py (and the isGitUrl already ported
+ * into frontend/src/components/scan/cli-hint.tsx) so the CLI, the web UI and the
+ * backend agree on what counts as a repo URL.
+ *
+ * A URL target is sent to the backend verbatim as `target_path`; the graph's
+ * dispatch node shallow-clones and normalises it (including `owner/repo`
+ * shorthand), exactly as the Python CLI relies on.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const GIT_URL_RE = /^(?:https?:\/\/|git@|ssh:\/\/|git:\/\/)[\w.@:\/~-]+?(?:\.git)?\/?$/i;
+const GIT_SHORTHAND_RE = /^[\w.-]+\/[\w.-]+$/;
+
+export function isGitUrl(target) {
+  if (!target) return false;
+  const t = String(target).trim();
+  if (!t) return false;
+  // An existing local path is never a URL, even if it looks like owner/repo.
+  try {
+    if (fs.existsSync(t)) return false;
+  } catch {
+    /* ignore fs errors — fall through to the pattern tests */
+  }
+  if (GIT_URL_RE.test(t)) return true;
+  return GIT_SHORTHAND_RE.test(t) && !/^[.\/~]/.test(t);
+}
+
+function expandHome(p) {
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+/**
+ * → { kind: "url", value, display } for a repo (value = raw target, sent as-is),
+ * → { kind: "path", value, display } for a local dir (value = absolute path).
+ */
+export function classifyTarget(rawTarget) {
+  const raw = String(rawTarget ?? ".").trim() || ".";
+  if (isGitUrl(raw)) {
+    return { kind: "url", value: raw, display: raw };
+  }
+  const resolved = path.resolve(expandHome(raw));
+  return { kind: "path", value: resolved, display: raw };
+}