flowforge-map 0.1.0__py3-none-any.whl

flowforge/api/flowmap.py

@@ -0,0 +1,174 @@
+"""The maps and the connector catalog (D17, D21).
+
+Every /flow route takes ?map=deps|flow: the dependency map from a scan (the default) or the flow map.
+
+GET    /flow?layer=mine|planner          the map: blocks, lines, positions, critical path, counts
+PUT    /flow/positions                   save block positions (drag end; Re-tidy sends replace=true)
+POST   /flow/overrides                   one edit on top of the Planner's version (never the user's code)
+DELETE /flow/overrides/{id}              undo one edit
+DELETE /flow/nodes/{node_id}/overrides   back to the Planner's version for one block
+GET    /flow/trace                       the traced test order the map replays
+GET    /flow/analysis                    how the Planner drew the map (stages, log, files, calls, dropped)
+GET    /flow/versions                    every version, newest first
+POST   /flow/recheck                     a new pending version and its diff
+GET    /flow/versions/{n}                a pending version's diff
+POST   /flow/versions/{n}/accept         take the chosen changes; older versions stay listed
+POST   /flow/versions/{n}/discard        keep the current map as it is
+GET    /catalog                          every app, each on_map | connected | none
+POST   /catalog/{id}/test                a mock test run: offline, canned, no key
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Body, HTTPException, Query
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from flowforge.connectors import catalog as catalog_mod
+from flowforge.connectors.registry import _describe
+from flowforge.flowmap.models import Override
+from flowforge.flowmap.service import FlowService, OverrideError, VersionError
+from flowforge.state import app_state
+
+router = APIRouter()
+
+
+MapId = Annotated[str, Query(alias="map", pattern="^(deps|flow)$")]
+
+
+def flows(map_id: str = "deps") -> FlowService:
+    service = (app_state().flows or {}).get(map_id)
+    if service is None:
+        raise HTTPException(503, "the map is not set up")
+    return service
+
+
+class Positions(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    positions: dict[str, tuple[float, float]] = Field(max_length=500)
+    replace: bool = False
+
+
+class Choices(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    take: dict[str, bool | str] = Field(default_factory=dict)
+
+
+@router.get("/flow")
+def get_flow(layer: str = Query("mine", pattern="^(mine|planner)$"), map_id: MapId = "deps") -> dict[str, Any]:
+    return flows(map_id).current(layer)
+
+
+@router.put("/flow/positions")
+def put_positions(body: Positions, map_id: MapId = "deps") -> dict[str, int]:
+    flows(map_id).set_positions(body.positions, replace=body.replace)
+    return {"saved": len(body.positions)}
+
+
+@router.post("/flow/overrides", status_code=201)
+def add_override(body: Annotated[Any, Body()], map_id: MapId = "deps") -> dict[str, Any]:
+    try:
+        override = Override.model_validate(body)
+    except ValidationError as exc:
+        raise HTTPException(422, _describe(exc)) from None
+    try:
+        return flows(map_id).add_override(override)
+    except OverrideError as err:
+        raise HTTPException(422, str(err)) from None
+
+
+@router.delete("/flow/overrides/{override_id}", status_code=204)
+def delete_override(override_id: int, map_id: MapId = "deps") -> None:
+    if not flows(map_id).delete_override(override_id):
+        raise HTTPException(404, "unknown edit")
+
+
+@router.delete("/flow/nodes/{node_id}/overrides")
+def reset_node(node_id: str, map_id: MapId = "deps") -> dict[str, int]:
+    return {"removed": flows(map_id).reset_node(node_id)}
+
+
+@router.get("/flow/trace")
+def get_trace(map_id: MapId = "deps") -> dict[str, Any]:
+    trace = flows(map_id).trace()
+    if trace is None:
+        raise HTTPException(404, "there is no traced test run yet")
+    return trace
+
+
+@router.get("/flow/analysis")
+def get_analysis(map_id: MapId = "deps") -> dict[str, Any]:
+    analysis = flows(map_id).analysis()
+    if analysis is None:
+        raise HTTPException(404, "the Planner hasn't drawn a map yet")
+    return analysis
+
+
+@router.get("/flow/versions")
+def list_versions(map_id: MapId = "deps") -> list[dict[str, Any]]:
+    return flows(map_id).versions()
+
+
+@router.post("/flow/recheck")
+def recheck(map_id: MapId = "deps") -> dict[str, Any]:
+    try:
+        return flows(map_id).recheck()
+    except VersionError as err:
+        raise HTTPException(409, str(err)) from None
+
+
+@router.get("/flow/versions/{version}")
+def pending_version(version: int, map_id: MapId = "deps") -> dict[str, Any]:
+    try:
+        return flows(map_id).pending_view(version)
+    except VersionError as err:
+        raise HTTPException(404, str(err)) from None
+
+
+@router.post("/flow/versions/{version}/accept")
+def accept_version(version: int, body: Choices, map_id: MapId = "deps") -> dict[str, Any]:
+    try:
+        return flows(map_id).accept(version, body.take)
+    except VersionError as err:
+        raise HTTPException(409, str(err)) from None
+
+
+@router.post("/flow/versions/{version}/discard", status_code=204)
+def discard_version(version: int, map_id: MapId = "deps") -> None:
+    try:
+        flows(map_id).discard(version)
+    except VersionError as err:
+        raise HTTPException(409, str(err)) from None
+
+
+# --- catalog ----------------------------------------------------------------------------------------
+
+def _connectors() -> dict[str, Any]:
+    return {c.id: c for c in app_state().registry.all()}
+
+
+def _on_map() -> set[str]:
+    """Apps the code calls: confirmed blocks with evidence on either map's Planner version (D17, D21). A block
+    counts by its connected app or, on the dependency map, by the known service it was recognised as."""
+    found: set[str] = set()
+    for service in (app_state().flows or {}).values():
+        flow = service.planner_flow()
+        if flow is None:
+            continue
+        found |= {app for n in flow.nodes if n.status == "confirmed" and any(ev.confirms for ev in n.evidence)
+                  for app in (n.connector, n.catalog) if app}
+    return found
+
+
+@router.get("/catalog")
+def get_catalog() -> dict[str, Any]:
+    return catalog_mod.catalog(_connectors(), _on_map())
+
+
+@router.post("/catalog/{app_id}/test")
+def test_app(app_id: str) -> dict[str, Any]:
+    entry = catalog_mod.find(app_id, _connectors())
+    if entry is None:
+        raise HTTPException(404, "unknown app")
+    return catalog_mod.mock_test(entry)

flowforge/api/runs.py

@@ -0,0 +1,284 @@
+"""Runs: validate, start, list, inspect, stream, stop (D7, D12, D16).
+
+POST /validate                 workflow JSON → {"ok", "order", "levels", "critical_path", "warnings"} or 422
+POST /runs?policy=&use_cache=  workflow JSON → {"run_id", "warnings"}; the run executes in the background
+GET  /runs?status=&limit=&before=  run summaries, newest first
+GET  /runs/{run_id}            → {"status", "error", "result", "summary"}; served from storage after a restart
+GET  /runs/{run_id}/events     → Server-Sent Events, replayed from the start (live or stored)
+POST /runs/{run_id}/stop       → cancels a running run
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from collections.abc import AsyncIterator
+from dataclasses import asdict
+from datetime import datetime, timedelta
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query
+from fastapi.encoders import jsonable_encoder
+from fastapi.sse import EventSourceResponse, ServerSentEvent
+
+from flowforge.nodes.base import NodeError, TransientNodeError, current_run_id
+from flowforge.nodes.mcp_node import MCPNode, check_call
+from flowforge.scheduler import graph
+from flowforge.scheduler.critical_path import critical_path
+from flowforge.scheduler.durations import estimate_weights
+from flowforge.scheduler.executor import POLICIES, Policy, check_nodes, run_workflow
+from flowforge.schema import Workflow
+from flowforge.state import Run, app_state, plain
+from flowforge.templating import referenced_steps
+
+MCP_CHECK_TIMEOUT_S = 5  # pre-run tool discovery; slower servers get a warning instead (D12)
+
+router = APIRouter()
+
+
+def check_graph(workflow: Workflow) -> graph.DAG:
+    try:
+        dag = graph.build_dag(workflow)
+        check_nodes(workflow, app_state().nodes)  # unknown connector, type mismatch, bad fallback (D10)
+    except (graph.CycleError, ValueError) as exc:
+        raise HTTPException(422, str(exc)) from exc
+    return dag
+
+
+async def check_mcp_calls(workflow: Workflow) -> list[str]:
+    """Check each MCP step's tool and literal arguments against its server before a run (D12).
+
+    A wrong call → 422 with the reason. An unreachable server → a warning; the step is
+    still checked when it runs. Templated arguments are checked at run time only.
+    """
+    nodes = app_state().nodes
+    errors: list[str] = []
+    warnings: list[str] = []
+    for step in workflow.steps:
+        node = nodes.get(step.connector or step.type)
+        tool = step.params.get("tool")
+        if step.type != "mcp" or not isinstance(node, MCPNode) or not isinstance(tool, str) or referenced_steps(tool):
+            continue
+        arguments = step.params.get("arguments", {})
+        try:
+            tools = await asyncio.wait_for(node.list_tools(step.params.get("server")), MCP_CHECK_TIMEOUT_S)
+        except (TransientNodeError, TimeoutError) as exc:
+            warnings.append(f"step '{step.id}': could not reach the MCP server to check tool '{tool}' "
+                            f"({str(exc) or type(exc).__name__}); it will be checked when the step runs")
+            continue
+        except NodeError as exc:
+            errors.append(f"step '{step.id}': {exc}")
+            continue
+        problem = check_call(tools, tool, None if referenced_steps(arguments) else arguments)
+        if problem:
+            errors.append(f"step '{step.id}': {problem}")
+    if errors:
+        raise HTTPException(422, "; ".join(errors))
+    return warnings
+
+
+# --- run summaries (D16) ---------------------------------------------------------------------------
+
+def totals(result: dict[str, Any]) -> dict[str, Any]:
+    """Per-run numbers for history and savings, from a (redacted) RunResult dict."""
+    tokens = 0
+    credits = 0.0
+    work_ms = 0.0
+    for step in result["steps"].values():
+        if step["started_at"] is not None and step["finished_at"] is not None:
+            work_ms += (step["finished_at"] - step["started_at"]) * 1000
+        usage = step["output"].get("usage") if isinstance(step["output"], dict) else None
+        if isinstance(usage, dict) and not step["cache_hit"]:
+            tokens += int(usage.get("prompt_tokens") or 0) + int(usage.get("completion_tokens") or 0)
+            credits += float(usage.get("credits") or 0)
+    return {"makespan_ms": result["makespan_ms"], "api_calls": result["api_calls"],
+            "cache_hits": result["cache_hits"], "tokens": tokens, "credits": credits, "work_ms": work_ms}
+
+
+def failure_reason(workflow: Workflow, result: dict[str, Any]) -> str | None:
+    """The first failure in plain words, and how many later steps it skipped."""
+    steps = result["steps"]
+    failed = sorted((s for s in steps.values() if s["state"] == "failed"), key=lambda s: s["finished_at"] or 0)
+    if not failed:
+        return None
+    first = failed[0]
+    step = workflow.step(first["step_id"])
+    title = step.description or step.id
+    dag = graph.build_dag(workflow)
+    skipped = sum(1 for d in graph.descendants(dag, step.id) if steps[d]["state"] == "skipped")
+    text = f'Step "{title}" failed: {first["error"]}.'
+    if skipped:
+        text += f" {skipped} step{'s' if skipped != 1 else ''} after it {'were' if skipped != 1 else 'was'} skipped."
+    if len(failed) > 1:
+        text += f" {len(failed) - 1} other step{'s' if len(failed) > 2 else ''} also failed."
+    return text
+
+
+# a step with no connector runs on its type's default; these are the connectors behind them (D10)
+DEFAULT_CONNECTOR = {"llm": "nim", "mcp": "fetch"}
+
+
+def outline(workflow: Workflow) -> list[dict[str, Any]]:
+    """What the dashboard needs to draw a run: no params, which could hold anything."""
+    return [{"id": s.id, "title": s.description or s.id, "type": s.type, "connector": s.connector,
+             "depends_on": list(s.depends_on)} for s in workflow.steps]
+
+
+def connectors_used(steps: list[dict[str, Any]]) -> list[str]:
+    used: list[str] = []
+    for step in steps:
+        connector = step["connector"] or DEFAULT_CONNECTOR.get(step["type"])
+        if connector and connector not in used:
+            used.append(connector)
+    return used
+
+
+def summary(row: dict[str, Any], live: Run | None = None) -> dict[str, Any]:
+    status = live.status if live is not None else row["status"]
+    steps = json.loads(row["steps_json"]) if row.get("steps_json") else []
+    return {
+        "id": row["id"], "plan": row["workflow_name"] or row["workflow_id"], "workflow_id": row["workflow_id"],
+        "status": status, "policy": row["policy"], "started_at": row["started_at"],
+        "finished_at": row["finished_at"], "time_ms": row["makespan_ms"], "api_calls": row["api_calls"],
+        "cache_hits": row["cache_hits"], "tokens": row["tokens"], "credits": row["credits"],
+        "work_ms": row["work_ms"], "failure_reason": row["failure_reason"], "connectors": connectors_used(steps),
+    }
+
+
+# --- routes ----------------------------------------------------------------------------------------
+
+@router.post("/validate")
+async def validate(workflow: Workflow) -> dict[str, Any]:
+    dag = check_graph(workflow)
+    warnings = await check_mcp_calls(workflow)
+    s = app_state()
+    weights = estimate_weights(workflow, s.storage.duration_history(workflow.id))
+    cp = critical_path(dag, weights)
+    return {
+        "ok": True,
+        "order": graph.topological_order(dag),
+        "levels": graph.levels(dag),
+        "weights": weights,
+        "critical_path": cp.path,
+        "critical_path_ms": cp.length_ms,
+        "warnings": warnings,
+    }
+
+
+@router.post("/runs")
+async def create_run(workflow: Workflow, policy: Policy = "critical_path", use_cache: bool = True) -> dict[str, Any]:
+    if policy not in POLICIES:
+        raise HTTPException(422, f"policy must be one of {POLICIES}")
+    check_graph(workflow)
+    warnings = await check_mcp_calls(workflow)
+    return {"run_id": start_run(workflow, policy=policy, use_cache=use_cache), "warnings": warnings}
+
+
+def start_run(workflow: Workflow, *, policy: Policy = "critical_path", use_cache: bool = True,
+              started_at: datetime | None = None) -> str:
+    """Start `workflow` in the background; it is recorded from its first event (D16).
+
+    `started_at` back-dates the stored run (example-data history only).
+    """
+    s = app_state()
+    run_id = uuid.uuid4().hex[:12]
+    s.storage.start_run(run_id, workflow.id, workflow.name or workflow.id, policy,
+                        started_at.isoformat(timespec="milliseconds") if started_at else None, outline(workflow))
+    run = s.runs[run_id] = Run(run_id, workflow, s.storage, s.redactor)
+    # a snapshot: editing a connector mid-run never swaps a node out from under this run (D16)
+    nodes, buckets = dict(s.nodes), dict(s.rate_limits)
+
+    def finish(status: str, result: dict[str, Any] | None, reason: str | None) -> None:
+        run.status, run.result = status, result
+        finished_at = None
+        if started_at is not None:
+            elapsed = timedelta(milliseconds=result["makespan_ms"]) if result else timedelta()
+            finished_at = (started_at + elapsed).isoformat(timespec="milliseconds")
+        s.storage.finish_run(run_id, status, result, totals(result) if result else {}, reason, finished_at)
+
+    async def execute() -> None:
+        current_run_id.set(run_id)  # artifact folder for this run's large outputs (D12)
+        try:
+            raw = await run_workflow(
+                workflow, nodes, policy=policy, use_cache=use_cache,
+                rate_limits=buckets, storage=s.storage, on_event=run.push,
+            )
+            result = plain(asdict(raw), s.redactor)
+            finish(raw.status, result, failure_reason(workflow, result))
+        except asyncio.CancelledError:
+            status = "interrupted" if s.shutting_down else "stopped"
+            reason = "The server stopped while this was running." if s.shutting_down else "Stopped by you."
+            run.push({"type": "run", "state": status})
+            finish(status, None, reason)
+        except Exception as exc:  # validation passed, so this is an engine bug — surface it
+            run.error = s.redactor.redact_text(f"{type(exc).__name__}: {exc}")
+            run.push({"type": "run", "state": "error", "error": run.error})
+            finish("error", None, run.error)
+        finally:
+            run.done = True
+            run.changed.set()
+
+    run.task = asyncio.create_task(execute())
+    s.tasks.add(run.task)
+    run.task.add_done_callback(s.tasks.discard)
+    return run_id
+
+
+@router.get("/runs")
+def list_runs(status: str | None = None, limit: int = Query(50, ge=1, le=500),
+              before: str | None = None) -> list[dict[str, Any]]:
+    s = app_state()
+    return [summary(row, s.runs.get(row["id"])) for row in s.storage.list_runs(status, limit, before)]
+
+
+@router.get("/runs/{run_id}")
+def run_status(run_id: str) -> dict[str, Any]:
+    s = app_state()
+    row = s.storage.get_run(run_id)
+    if row is None:
+        raise HTTPException(404, "unknown run")
+    live = s.runs.get(run_id)
+    steps = json.loads(row["steps_json"]) if row.get("steps_json") else []
+    if live is not None:
+        return {"status": live.status, "error": live.error, "result": live.result, "summary": summary(row, live),
+                "steps": steps}
+    return {"status": row["status"], "error": row["failure_reason"] if row["status"] == "error" else None,
+            "result": row["result"], "summary": summary(row), "steps": steps}
+
+
+@router.get("/runs/{run_id}/events", response_class=EventSourceResponse)
+async def run_events(run_id: str) -> AsyncIterator[ServerSentEvent]:
+    s = app_state()
+    run = s.runs.get(run_id)
+    if run is None:  # finished before this server started: replay what was stored
+        if s.storage.get_run(run_id) is None:
+            raise HTTPException(404, "unknown run")
+        for seq, event in enumerate(s.storage.run_events(run_id)):
+            yield ServerSentEvent(data=jsonable_encoder(event), id=str(seq))
+        yield ServerSentEvent(data={"type": "end"}, event="end")
+        return
+    sent = 0
+    while True:
+        run.changed.clear()
+        while sent < len(run.events):
+            yield ServerSentEvent(data=jsonable_encoder(run.events[sent]), id=str(sent))
+            sent += 1
+        if run.done:
+            yield ServerSentEvent(data={"type": "end"}, event="end")
+            return
+        await run.changed.wait()
+
+
+@router.post("/runs/{run_id}/stop")
+def stop_run(run_id: str) -> dict[str, str]:
+    s = app_state()
+    run = s.runs.get(run_id)
+    if run is None:
+        if s.storage.get_run(run_id) is None:
+            raise HTTPException(404, "unknown run")
+        raise HTTPException(409, "this run is not running")
+    if run.done or run.task is None:
+        raise HTTPException(409, "this run is not running")
+    run.task.cancel()
+    return {"status": "stopping"}

flowforge/api/scan.py

@@ -0,0 +1,117 @@
+"""Choose the folder whose dependency map you see (D21). One repo per database in V1.
+
+GET  /scan                       the folder, whether this is example mode, and a summary of the last scan
+POST /scan {path, replace?}      scan a folder and draw its map; a different folder needs replace (a fresh map)
+
+Re-scanning the same folder is POST /flow/recheck: a new version and a diff, never an overwrite (D17).
+"""
+
+from __future__ import annotations
+
+import os
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, ConfigDict, Field
+
+from flowforge.flowmap.planner import CodeFlowPlanner, ScanPlanner
+from flowforge.flowmap.service import FlowService
+from flowforge.home import resource
+from flowforge.state import AppState, app_state
+from flowforge.storage import Storage
+
+REPO_SETTING = "repo_path"
+EXAMPLE_REPO = resource("example")   # scanned live in example mode; shipped inside the package (D34)
+
+router = APIRouter()
+
+
+class ScanRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    path: str = Field(min_length=1, max_length=4096)
+    replace: bool = False
+
+
+class RepoChangeError(ValueError):
+    """A different folder while a map exists: it needs an explicit replace (D21)."""
+
+
+def map_repo(storage: Storage, maps: dict[str, FlowService], path: Path, fresh: bool) -> None:
+    """Both maps of one folder: what it depends on (D21) and the order its code calls them (D25), weighted by the
+    latest checks (D24)."""
+    maps["deps"].map_folder(ScanPlanner(path), fresh=fresh)
+    if "flow" in maps:
+        maps["flow"].map_folder(CodeFlowPlanner(path, storage.latest_latencies), fresh=fresh)
+
+
+def choose_repo(storage: Storage, maps: dict[str, FlowService], path: Path, replace: bool) -> None:
+    """Map `path`: the same folder keeps its maps; a different one starts fresh maps, but only with `replace`."""
+    current = storage.setting(REPO_SETTING)
+    changed = current != str(path)
+    if changed and current and maps["deps"].has_map() and not replace:
+        raise RepoChangeError(f"there is already a map of {Path(current).name}; mapping {path.name} starts a fresh map")
+    if changed:
+        storage.set_setting(REPO_SETTING, str(path))
+        if current:
+            storage.clear_checks()   # another repo's results don't belong to this one (D24)
+    map_repo(storage, maps, path, fresh=changed)
+
+
+def startup_repo(storage: Storage, maps: dict[str, FlowService]) -> None:
+    """At start-up outside example mode: FLOWFORGE_REPO (`flowforge --repo`), else the folder chosen last time.
+    A different folder needs FLOWFORGE_REPO_REPLACE=1 (`--replace`); otherwise FlowForge refuses to start."""
+    chosen = os.getenv("FLOWFORGE_REPO")
+    if chosen:
+        path = Path(chosen).expanduser()
+        if not path.is_dir():
+            raise RuntimeError(f"FLOWFORGE_REPO={chosen} is not a folder")
+        try:
+            choose_repo(storage, maps, path.resolve(), replace=os.getenv("FLOWFORGE_REPO_REPLACE") == "1")
+        except RepoChangeError as err:
+            raise RuntimeError(f"{err}. Run with --replace to start it fresh.") from None
+        return
+    saved = storage.setting(REPO_SETTING)
+    if saved and Path(saved).is_dir():
+        map_repo(storage, maps, Path(saved), fresh=False)
+
+
+def repo_path(s: AppState) -> Path | None:
+    if s.example:
+        return EXAMPLE_REPO
+    saved = s.storage.setting(REPO_SETTING)
+    return Path(saved) if saved else None
+
+
+@router.get("/scan")
+def get_scan() -> dict[str, Any]:
+    s = app_state()
+    repo = repo_path(s)
+    analysis = s.flows["deps"].analysis() if "deps" in s.flows else None
+    summary = None
+    if analysis and analysis.get("scan"):
+        deps = analysis["scan"]["dependencies"]
+        summary = {"files": analysis["scan"]["files_scanned"], "dependencies": len(deps),
+                   "unconfirmed": sum(d["status"] == "unconfirmed" for d in deps),
+                   "kinds": dict(Counter(d["kind"] for d in deps))}
+    return {"repo": str(repo) if repo else None, "name": repo.name if repo else None, "example": s.example,
+            "summary": summary}
+
+
+@router.post("/scan", status_code=201)
+def post_scan(body: ScanRequest) -> dict[str, Any]:
+    """Read-only and offline (D20): the folder is read, never run, and nothing is sent anywhere."""
+    s = app_state()
+    if s.example:
+        raise HTTPException(409, "Example mode always maps the sample app. Run FlowForge without --example "
+                                 "to scan your own folder.")
+    path = Path(body.path).expanduser()
+    if not path.is_dir():
+        raise HTTPException(422, "that isn't a folder on this machine")
+    path = path.resolve()
+    try:
+        choose_repo(s.storage, s.flows, path, body.replace)
+    except RepoChangeError as err:
+        raise HTTPException(409, f"{err} (send replace: true)") from None
+    return {"repo": str(path), "name": path.name, "version": s.flows["deps"].current().get("version")}

flowforge/api/security.py

@@ -0,0 +1,31 @@
+"""Security findings (D31): what the map's scan found unsafe, from the stored scan, so a re-scan updates it. A scan
+stored before D31 never ran the finders, so the folder is read again (plain code, nothing run or sent: D20).
+
+GET /security   {repo, scanned, summary: {high, medium, low}, findings: [...]}
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+from fastapi import APIRouter
+
+from flowforge.api.scan import repo_path
+from flowforge.scan import scan as scan_repo
+from flowforge.state import app_state
+
+router = APIRouter()
+
+
+@router.get("/security")
+def security() -> dict[str, Any]:
+    s = app_state()
+    repo = repo_path(s)
+    analysis = s.flows["deps"].analysis() if "deps" in s.flows else None
+    scan = (analysis or {}).get("scan")
+    if scan and not scan.get("findings_checked") and repo is not None and repo.is_dir():
+        scan = scan_repo(repo).model_dump(mode="json")
+    findings = scan.get("findings", []) if scan else []
+    return {"repo": repo.name if repo else None, "scanned": scan is not None,
+            "summary": dict(Counter(f["level"] for f in findings)), "findings": findings}