flowforge-map 0.1.0__tar.gz → 0.2.0__tar.gz

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowforge-map
-Version: 0.1.0
+Version: 0.2.0
 Summary: Map what your app depends on (LLMs, MCP servers, APIs), check their health and security, and see what could run faster. Local and free; the scan needs no AI.
 Project-URL: Homepage, https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator
 Project-URL: Issues, https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator/issues
@@ -19,9 +19,11 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: System :: Monitoring
 Requires-Python: >=3.12
 Requires-Dist: anthropic>=1.11.0
+Requires-Dist: cryptography>=43
 Requires-Dist: fastapi>=0.115
 Requires-Dist: httpx>=0.27
 Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: keyring>=25
 Requires-Dist: mcp>=1.2
 Requires-Dist: openai>=1.40
 Requires-Dist: pydantic>=2.8
@@ -53,7 +55,7 @@ What makes it different: **it knows which chain of steps is the bottleneck and s
 
 ## Quick start
 
-### Install (from the first release, v0.1.0)
+### Install
 
 ```bash
 uvx flowforge-map --example      # try it: a sample app's maps in your browser, no keys, nothing sent
@@ -111,7 +113,22 @@ FlowForge is also an **MCP server**, so Claude Code, Codex or Antigravity can as
 claude mcp add flowforge -- uv --directory /path/to/flowforge run flowforge mcp --repo /path/to/your/app
 ```
 
-Your agent gets six read-only tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings` and `what_changed`. Every answer is masked (key values never appear), FlowForge never edits your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+Your agent gets seven read-only tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys` and `what_changed`. Every answer is masked (key values never appear), FlowForge never edits your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+
+### Keys your coding agent never sees
+
+Your agent only needs a key's **name**: the code it writes reads `os.environ["STRIPE_SECRET_KEY"]`. You give FlowForge the value once, and your app gets it when it starts:
+
+```bash
+flowforge key add STRIPE_SECRET_KEY        # typed hidden; saved in your OS keychain
+flowforge key list                         # each key the code reads: saved · in .env · missing
+flowforge key import                       # move a .env into FlowForge (then delete the .env)
+flowforge run -- python app.py             # your app starts with the keys in its environment
+```
+
+Each command takes `--repo PATH` (default: the folder you're in). On the map, a 🔑 badge marks a block whose key is missing, and the ⚠ list has a box to paste it into. Your agent's `get_keys` tool gets names, statuses and the command to ask you to run, never a value. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
+
+What this does and doesn't promise: the key is never handed to your agent and isn't left in a file it reads by habit. An agent that can run commands as you could still run `flowforge run -- printenv`, or read your keychain, so it isn't impossible. MCP servers your coding tool starts get their environment from that tool, not from FlowForge.
 
 ### Send someone the map
 
@@ -238,6 +255,7 @@ FlowForge itself keeps keys out of its runs, events, cache, logs and the dashboa
 | `POST /connectors/{id}/test` | One harmless check (MCP and local apps) |
 | `GET /connectors/{id}/activity`, `GET /connectors/{id}/tools` | What an app has done; an MCP server's tools |
 | `GET /security` | The scan's security findings, by level, with the fix and a prompt for each (D31) |
+| `GET /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}` | The keys the code reads and their status; save one (write-only: the value never comes back) or forget it (D36) |
 | `GET /health/tools`, `GET /stats/savings`, `GET /meta`, `GET /presets` | Tool health, money and time, app info, ready-made apps |
 | `GET /workflows`, `GET /workflows/{name}` | The example workflows |
 | `GET /flow?layer=mine\|planner` | The flow map: blocks, lines, positions, critical path, your edits |

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/README.md

@@ -21,7 +21,7 @@ What makes it different: **it knows which chain of steps is the bottleneck and s
 
 ## Quick start
 
-### Install (from the first release, v0.1.0)
+### Install
 
 ```bash
 uvx flowforge-map --example      # try it: a sample app's maps in your browser, no keys, nothing sent
@@ -79,7 +79,22 @@ FlowForge is also an **MCP server**, so Claude Code, Codex or Antigravity can as
 claude mcp add flowforge -- uv --directory /path/to/flowforge run flowforge mcp --repo /path/to/your/app
 ```
 
-Your agent gets six read-only tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings` and `what_changed`. Every answer is masked (key values never appear), FlowForge never edits your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+Your agent gets seven read-only tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys` and `what_changed`. Every answer is masked (key values never appear), FlowForge never edits your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+
+### Keys your coding agent never sees
+
+Your agent only needs a key's **name**: the code it writes reads `os.environ["STRIPE_SECRET_KEY"]`. You give FlowForge the value once, and your app gets it when it starts:
+
+```bash
+flowforge key add STRIPE_SECRET_KEY        # typed hidden; saved in your OS keychain
+flowforge key list                         # each key the code reads: saved · in .env · missing
+flowforge key import                       # move a .env into FlowForge (then delete the .env)
+flowforge run -- python app.py             # your app starts with the keys in its environment
+```
+
+Each command takes `--repo PATH` (default: the folder you're in). On the map, a 🔑 badge marks a block whose key is missing, and the ⚠ list has a box to paste it into. Your agent's `get_keys` tool gets names, statuses and the command to ask you to run, never a value. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
+
+What this does and doesn't promise: the key is never handed to your agent and isn't left in a file it reads by habit. An agent that can run commands as you could still run `flowforge run -- printenv`, or read your keychain, so it isn't impossible. MCP servers your coding tool starts get their environment from that tool, not from FlowForge.
 
 ### Send someone the map
 
@@ -206,6 +221,7 @@ FlowForge itself keeps keys out of its runs, events, cache, logs and the dashboa
 | `POST /connectors/{id}/test` | One harmless check (MCP and local apps) |
 | `GET /connectors/{id}/activity`, `GET /connectors/{id}/tools` | What an app has done; an MCP server's tools |
 | `GET /security` | The scan's security findings, by level, with the fix and a prompt for each (D31) |
+| `GET /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}` | The keys the code reads and their status; save one (write-only: the value never comes back) or forget it (D36) |
 | `GET /health/tools`, `GET /stats/savings`, `GET /meta`, `GET /presets` | Tool health, money and time, app info, ready-made apps |
 | `GET /workflows`, `GET /workflows/{name}` | The example workflows |
 | `GET /flow?layer=mine\|planner` | The flow map: blocks, lines, positions, critical path, your edits |

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/backend/flowforge/agent/server.py

@@ -1,4 +1,4 @@
-"""FlowForge as an MCP server (D28, D29): five read-only tools a coding agent can ask about the repo it works in.
+"""FlowForge as an MCP server (D28, D29, D36): read-only tools a coding agent can ask about the repo it works in.
 
 The map and the flow are read fresh from the repo on every call (plain code, nothing run, no LLM: D20). The
 dashboard's database supplies what only it knows, when it maps the same repo: measured latencies, past checks,
@@ -28,6 +28,7 @@ from flowforge.flowmap.validate import code_writes, critical
 from flowforge.nodes.check_node import CheckNode
 from flowforge.scan import ScanResult, scan
 from flowforge.scheduler.executor import StepState, run_workflow
+from flowforge.security.keystore import KeyStore, report
 from flowforge.security.logfilter import Redactor, redact_code, secret_values_for
 from flowforge.storage import Storage, now_iso
 
@@ -160,6 +161,10 @@ def headline(tool: str, data: dict[str, Any]) -> str | None:
     if tool == "get_security_findings":
         counts = data["summary"]
         return " · ".join(f"{counts[k]} {k}" for k in ("high", "medium", "low") if counts.get(k)) or "Nothing found"
+    if tool == "get_keys":
+        counts = data["summary"]
+        parts = [f"{counts[k]} {w}" for k, w in (("missing", "missing"), ("env_file", "in .env")) if counts.get(k)]
+        return " · ".join(parts) or ("All saved" if data["keys"] else "No keys read")
     if tool == "what_changed":
         if not data["saved"]:
             return "No saved map yet"
@@ -181,6 +186,15 @@ def _security_data(result: ScanResult) -> dict[str, Any]:
             "note": "Catches known key formats and these patterns, not everything. Values are never shown."}
 
 
+def _keys_data(root: Path, result: ScanResult) -> dict[str, Any]:
+    """Names and statuses only: this server, which the agent starts, never reads a value (D36)."""
+    found = report(KeyStore(root), result, verify=False)
+    return {"keys": found, "summary": dict(Counter(k["status"] for k in found if k["status"] != "saved")),
+            "run": "flowforge run -- <the command that starts the app>",
+            "note": "saved means FlowForge has it on record; this server never reads a value, so the user's "
+                    "`flowforge key list` is what confirms it can be read"}
+
+
 def _flow_data(result: Any) -> dict[str, Any]:
     if result.flow is None:
         return {"available": False, "message": result.message}
@@ -218,7 +232,8 @@ def preview(repo: Path, storage: Storage) -> dict[str, Any]:
     tone = "bad" if "down" in checked else "warn" if "warn" in checked else "ok" if checked else "plain"
     read = r.flow()
     flow, advice = _flow_data(read), _advice_data(read)
-    security = _security_data(read.scan or r.scan())
+    scanned = read.scan or r.scan()
+    security, keys = _security_data(scanned), _keys_data(r.root, scanned)
     worst = next((lv for lv in ("high", "medium", "low") if security["summary"].get(lv)), None)
     cards = [
         {"tool": "get_map", "headline": headline("get_map", deps), "sub": kinds, "tone": "plain"},
@@ -228,6 +243,8 @@ def preview(repo: Path, storage: Storage) -> dict[str, Any]:
         {"tool": "get_security_findings", "headline": headline("get_security_findings", security),
          "sub": "keys in code, plain http, risky MCP servers",
          "tone": {"high": "bad", "medium": "warn"}.get(worst or "", "ok")},
+        {"tool": "get_keys", "headline": headline("get_keys", keys),
+         "sub": "names only: the user types each key, hidden", "tone": "warn" if keys["summary"] else "ok"},
         {"tool": "get_flow", "headline": headline("get_flow", flow) if flow["available"] else None,
          "sub": "as written → could be" if flow["available"] else flow["message"], "tone": "plain"},
         {"tool": "get_advice", "headline": (_plural(len(advice["advice"]), "way") + " to be faster")
@@ -312,6 +329,14 @@ def build_server(repo: Path, storage: Storage, *, transport: httpx.AsyncBaseTran
         shown. Catches known key formats and these patterns, not everything."""
         return r.answer("get_security_findings", _security_data(r.scan()))
 
+    @server.tool(annotations=READ)
+    def get_keys() -> dict[str, Any]:
+        """The keys the repo's code reads from its environment (names that look like keys), each with where it is
+        read, the dependencies that use it, and its status: saved in FlowForge, only in .env, or missing. You never
+        get a value and never need one: write code that reads the name from the environment, then ask the user to
+        run the `command` given (they type the key, hidden). Their app gets the keys with `flowforge run -- <app>`."""
+        return r.answer("get_keys", _keys_data(r.root, r.scan()))
+
     @server.tool(annotations=READ)
     def what_changed() -> dict[str, Any]:
         """After an edit: the dependencies added or removed since the map saved in the dashboard, and the flow's

flowforge_map-0.2.0/backend/flowforge/api/keys.py

@@ -0,0 +1,107 @@
+"""Keys the coding agent never sees (D36): their statuses for the map, and the dashboard's write-only box.
+
+GET    /keys          {repo, example, summary: {missing, env_file}, keys: [{name, status, ref, deps, command}]}
+PUT    /keys/{name}   {"value": "..."} → {name, status: "saved"}; the value is never sent back
+DELETE /keys/{name}   → {name, removed}
+"""
+
+from __future__ import annotations
+
+import os
+from collections import Counter
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, ConfigDict
+
+from flowforge.api.scan import repo_path
+from flowforge.scan import ScanResult
+from flowforge.scan import scan as scan_repo
+from flowforge.security.keystore import BadKey, KeyStore, report
+from flowforge.state import AppState, app_state
+
+router = APIRouter()
+
+
+class KeyValue(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    value: str
+
+
+def learn_saved_keys(s: AppState, repo: Path | None) -> None:
+    """The redactor masks every value saved for this folder from now on, wherever it would show (D36)."""
+    if repo is None or s.example:
+        return
+    try:
+        s.redactor.learn(KeyStore(repo).env().values())
+    except Exception:   # a keychain that can't be read must not stop FlowForge
+        pass
+
+
+def _scan(s: AppState, repo: Path) -> ScanResult:
+    """The map's stored scan, so a re-scan updates the keys; the folder read again if none is stored."""
+    analysis = s.flows["deps"].analysis() if "deps" in s.flows else None
+    stored = (analysis or {}).get("scan")
+    if stored:
+        try:
+            return ScanResult.model_validate(stored)
+        except ValueError:
+            pass
+    return scan_repo(repo)
+
+
+_LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+
+
+def _this_machine(name: str | None) -> bool:
+    chosen = os.getenv("FLOWFORGE_HOST", "")
+    return bool(name) and (name in _LOOPBACK or (name == chosen and chosen not in ("0.0.0.0", "::")))
+
+
+def from_this_machine(request: Request) -> None:
+    """Saving or forgetting a key needs the dashboard's own address (D36). A web page can't do it: through DNS
+    rebinding its Host is its own name, and from another site its Origin is."""
+    host = urlsplit(f"//{request.headers.get('host', '')}").hostname
+    origin = request.headers.get("origin")
+    if not _this_machine(host) or (origin is not None and not _this_machine(urlsplit(origin).hostname)):
+        raise HTTPException(403, "Keys can only be saved from the dashboard on this machine.")
+
+
+def _writable(s: AppState) -> Path:
+    repo = repo_path(s)
+    if s.example:
+        raise HTTPException(409, "Example data: keys aren't saved. Map your own folder to add keys.")
+    if repo is None:
+        raise HTTPException(409, "Map a folder first: keys belong to one folder.")
+    return repo
+
+
+@router.get("/keys")
+def keys() -> dict[str, Any]:
+    s = app_state()
+    repo = repo_path(s)
+    if repo is None or not repo.is_dir():
+        return {"repo": None, "example": s.example, "summary": {}, "keys": []}
+    found = report(KeyStore(repo), _scan(s, repo))
+    summary = Counter(k["status"] for k in found if k["status"] != "saved")
+    return {"repo": repo.name, "example": s.example, "summary": dict(summary), "keys": found}
+
+
+@router.put("/keys/{name}", dependencies=[Depends(from_this_machine)])
+def save_key(name: str, body: KeyValue) -> dict[str, Any]:
+    s = app_state()
+    repo = _writable(s)
+    try:
+        KeyStore(repo).add(name, body.value)
+    except BadKey as e:
+        raise HTTPException(400, str(e)) from None
+    s.redactor.learn([body.value.strip()])
+    return {"name": name, "status": "saved"}
+
+
+@router.delete("/keys/{name}", dependencies=[Depends(from_this_machine)])
+def remove_key(name: str) -> dict[str, Any]:
+    repo = _writable(app_state())
+    return {"name": name, "removed": KeyStore(repo).remove(name)}

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/backend/flowforge/api/scan.py

@@ -110,6 +110,9 @@ def post_scan(body: ScanRequest) -> dict[str, Any]:
     if not path.is_dir():
         raise HTTPException(422, "that isn't a folder on this machine")
     path = path.resolve()
+    from flowforge.api.keys import learn_saved_keys  # here: keys imports this module
+
+    learn_saved_keys(s, path)   # before the map is stored, so a saved key's value is masked in it (D36)
     try:
         choose_repo(s.storage, s.flows, path, body.replace)
     except RepoChangeError as err:

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/backend/flowforge/cli.py

@@ -6,6 +6,8 @@
     uv run flowforge scan PATH        print the folder's dependencies as JSON; nothing stored, nothing sent
     uv run flowforge mcp [--repo P]   an MCP server for your coding agent, over stdio (D29); P defaults to here
     uv run flowforge serve --reload   (used by `npm run dev`; `serve` is optional)
+    uv run flowforge key add NAME     save a key for this folder, typed hidden (D36); also: list, remove, import
+    uv run flowforge run -- CMD ...   start your app with the saved keys in its environment (D36)
 """
 
 from __future__ import annotations
@@ -41,6 +43,14 @@ def parse(argv: list[str] | None) -> argparse.Namespace:
 
 
 def main(argv: list[str] | None = None) -> None:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["key"]:
+        keys_command(argv[1:])
+        return
+    if argv[:1] == ["run"]:
+        run_with_keys(argv[1:])
+        return
+
     import uvicorn
 
     args = parse(argv)
@@ -104,5 +114,97 @@ def scan_folder(path: str | None) -> None:
     print(json.dumps(scan(Path(path).expanduser()).model_dump(mode="json"), indent=2))
 
 
+_SHOWN = {"saved": "saved", "unreadable": "can't read", "env_file": "in .env", "missing": "missing"}
+
+
+def keys_command(argv: list[str]) -> None:
+    """`flowforge key add|list|remove|import`: keys for one folder, which only `flowforge run` hands out (D36).
+    Values are never printed."""
+    from flowforge.security.keystore import NAME, BadKey, KeyStore, report
+
+    parser = argparse.ArgumentParser(prog="flowforge key", description="Keep your app's keys out of files and away "
+                                     "from your coding agent. Values are never shown.")
+    parser.add_argument("action", choices=["add", "list", "remove", "import"])
+    parser.add_argument("name", nargs="?", help="add/remove: the env var name, e.g. STRIPE_SECRET_KEY; "
+                                                "import: the file (default .env in the folder)")
+    parser.add_argument("--repo", default=".", help="the app's folder (default: here)")
+    args = parser.parse_args(argv)
+    repo = Path(args.repo).expanduser()
+    if not repo.is_dir():
+        parser.error(f"{args.repo} is not a folder")
+    store = KeyStore(repo)
+    if args.action in ("add", "remove") and not (args.name and NAME.fullmatch(args.name)):
+        parser.error("name the key as an env var name, e.g. STRIPE_SECRET_KEY")
+
+    if args.action == "add":
+        value = _read_value(args.name)
+        try:
+            where = store.add(args.name, value)
+        except BadKey as e:
+            parser.error(str(e))
+        print(f"Saved {args.name} in {'your keychain' if where == 'keychain' else 'FlowForge (encrypted file)'}.")
+        print("  Your app gets it with: flowforge run -- <the command that starts it>")
+    elif args.action == "remove":
+        print(f"Removed {args.name}." if store.remove(args.name) else f"{args.name} wasn't saved.")
+    elif args.action == "import":
+        source = Path(args.name).expanduser() if args.name else repo / ".env"
+        if not source.is_file():
+            parser.error(f"{source} isn't a file")
+        names = store.import_env(source)
+        print(f"Saved {len(names)} from {source.name}: {', '.join(names) or 'nothing to save'}.")
+        if names:
+            print(f"  Delete {source.name} once your app runs with `flowforge run -- ...`: a coding agent can read it.")
+    else:
+        from flowforge.scan import scan
+
+        found = report(store, scan(repo))
+        if not found:
+            print("No keys: the code reads none, and none are saved.")
+        width = max((len(k["name"]) for k in found), default=0)
+        for k in found:
+            print(f"{k['name']:<{width}}  {_SHOWN[k['status']]:<10}  {k['ref'] or ''}")
+        todo = [k for k in found if k["command"]]
+        if todo:
+            print()
+            for k in todo:
+                print(f"  {k['command']}")
+
+
+def _read_value(name: str) -> str:
+    """The key, typed hidden; or one line from a pipe (`pass show x | flowforge key add X`). Never echoed."""
+    import getpass
+
+    if sys.stdin.isatty():
+        return getpass.getpass(f"{name} (typed hidden): ")
+    return sys.stdin.readline().rstrip("\r\n")
+
+
+def run_with_keys(argv: list[str]) -> None:
+    """`flowforge run [--repo P] -- CMD ...`: CMD starts with this folder's saved keys added to its environment.
+    The command is a list (never a shell), and its exit code is FlowForge's (D36)."""
+    import subprocess
+
+    from flowforge.security.keystore import KeyStore
+
+    parser = argparse.ArgumentParser(prog="flowforge run", description="Start your app with its saved keys.")
+    parser.add_argument("--repo", default=".", help="the folder whose keys to use (default: here)")
+    parser.add_argument("command", nargs=argparse.REMAINDER, help="-- then the command that starts your app")
+    args = parser.parse_args(argv)
+    command = args.command[1:] if args.command[:1] == ["--"] else args.command
+    if not command:
+        parser.error("give the command after --, e.g. flowforge run -- python app.py")
+    if not Path(args.repo).expanduser().is_dir():
+        parser.error(f"{args.repo} is not a folder")
+    env = {**os.environ, **KeyStore(Path(args.repo)).env()}
+    try:
+        code = subprocess.call(command, env=env)
+    except FileNotFoundError:
+        print(f"flowforge run: {command[0]} not found", file=sys.stderr)
+        code = 127
+    except KeyboardInterrupt:
+        code = 130
+    raise SystemExit(code)
+
+
 if __name__ == "__main__":
     main()

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/backend/flowforge/flowmap/diff.py

@@ -141,5 +141,30 @@ def apply_choices(old: Flow, new: Flow, changes: list[dict[str, Any]],
 
     kept_edges = [e for e in edges if e.source in nodes and e.target in nodes]
     suggestions = [s for s in new.suggestions if s.node in nodes]
-    return Flow(kind=new.kind, nodes=[nodes[i] for i in order if i in nodes], edges=kept_edges,
-                suggestions=suggestions), drop_edits
+    # the new map as it is (its source, reader, advice, times and actions: D25, D33, D35), with the blocks and lines
+    # you chose; advice about a block you declined goes with it
+    advice = [a for a in new.advice if all(i in nodes for i in a.nodes)]
+    return new.model_copy(deep=True, update={
+        "nodes": [nodes[i] for i in order if i in nodes], "edges": kept_edges, "suggestions": suggestions,
+        "advice": advice, "actions": _actions_kept(old, new, set(nodes))}), drop_edits
+
+
+def _actions_kept(old: Flow, new: Flow, kept: set[str]) -> list:
+    """Each action's call groups (D33) for the blocks you kept: a call you kept against the re-scan comes back
+    into its action's "as written", in the group it had; a call you declined leaves it."""
+    restored = kept - {n.id for n in new.nodes}
+    old_parts = {a.id: a.parts for a in old.actions}
+    out = []
+    for action in new.actions:
+        parts = [[i for i in p if i in kept] for p in action.parts]
+        have = {i for p in parts for i in p}
+        for p in old_parts.get(action.id, []):
+            if extra := [i for i in p if i in restored and i not in have]:
+                # back into the group it ran with, if one of its partners is still there; else on its own
+                group = next((g for g in parts if any(i in g for i in p if i not in restored)), None)
+                if group is None:
+                    parts.append(extra)
+                else:
+                    group += extra
+        out.append(action.model_copy(update={"parts": [p for p in parts if p]}))
+    return out

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/backend/flowforge/flowmap/models.py

@@ -153,6 +153,7 @@ class Flow(_Model):
     written_ms: float | None = None   # code flows: every call one after another, as the code is written (D25)
     patterns: list[str] = Field(default_factory=list)   # code flows: languages read by patterns, less exact (D32)
     actions: list[Action] = Field(default_factory=list)   # code flows: one per entry point, slowest first (D33)
+    reader: int = 0   # the reader that made it (flowmap.planner.READER); an older one is read again on start (D35)
 
     @model_validator(mode="after")
     def _structure(self) -> Flow:

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/backend/flowforge/flowmap/planner.py

@@ -56,9 +56,16 @@ class FixturePlanner:
 APP_ID, TOOLS_ID = "app", "tools"
 
 
+# The version of what the scan and the flow reader put on a map. Raise it when a change to either changes a map:
+# maps saved by an older reader are read again on start (D35).
+READER = 1
+
+
 class ScanPlanner:
     """A real repo (D21): scan the folder, draw one block per dependency off the app (or your coding tools)."""
 
+    reader = READER
+
     def __init__(self, root: str | Path):
         self.root = Path(root)
 
@@ -95,7 +102,7 @@ def draft_from_scan(result: ScanResult) -> Draft:
         files=sorted({e.ref.rsplit(":", 1)[0] for d in deps for e in d.evidence})[:200],
         scan=result.model_dump(mode="json"))
     facts = [(d.id, d.kind, d.target, d.status, [e.ref for e in d.evidence]) for d in deps]
-    return Draft(flow=Flow(kind="dependencies", nodes=nodes, edges=edges), trace=None, analysis=analysis,
+    return Draft(flow=Flow(kind="dependencies", nodes=nodes, edges=edges, reader=READER), trace=None, analysis=analysis,
                  fact_sheet_hash=fact_hash(facts))
 
 
@@ -103,6 +110,8 @@ class CodeFlowPlanner:
     """A real repo's flow (D25): read its Python, draw the order its entry points call their dependencies, weighted
     by the latest checks (D24). `latencies` is asked each time, so a re-scan picks up newer checks."""
 
+    reader = READER
+
     def __init__(self, root: str | Path, latencies: Callable[[], dict[str, float]] = dict):
         self.root = Path(root)
         self.latencies = latencies
@@ -114,11 +123,12 @@ class CodeFlowPlanner:
         if result.flow is None:
             raise NoFlow(result.message or "No flow to draw.")
         flow = result.flow
+        flow.reader = READER
         steps = [n for n in flow.nodes if n.kind in CALL_KINDS]
         measured = sum(n.estimate_source == "measured" for n in steps)
         analysis = Analysis(
             stages=[
-                AnalysisStage(title="Read your Python", done=f"{len(result.entries)} entry point"
+                AnalysisStage(title="Read your code", done=f"{len(result.entries)} entry point"
                               f"{'s' if len(result.entries) != 1 else ''}, nothing run or sent"),
                 AnalysisStage(title="Followed the calls", done=f"{len(steps)} calls, "
                               f"{sum(n.kind == 'decision' for n in flow.nodes)} decisions"),

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/backend/flowforge/flowmap/service.py

@@ -222,9 +222,17 @@ class FlowService:
         return self.first_map()
 
     def first_map(self) -> int | None:
-        """Draw the first map if there is none. Returns its version, or None without a Planner."""
-        if self.planner is None or self.store.count_flow_versions():
+        """Draw the first map if there is none, or read the folder again when the saved map was made by an older
+        reader (D35). Returns the new version, or None when nothing was drawn."""
+        if self.planner is None:
             return None
+        if self.store.count_flow_versions():
+            latest = self.store.latest_flow_version("accepted")
+            if latest is None or (latest["flow"] or {}).get("reader", 0) >= getattr(self.planner, "reader", 0):
+                return None
+            pending = self.store.latest_flow_version("pending")
+            if pending is not None:   # a re-scan made by the older reader: read again below, so it is out of date
+                self.store.update_flow_version(pending["version"], "discarded")
         try:
             draft = self.planner.analyze(0)
         except NoFlow as why:

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/backend/flowforge/home.py

@@ -44,6 +44,20 @@ def install_kind() -> str:
     return "uvx" if "archive-v" in Path(sys.prefix).as_posix() else "pip"
 
 
+def command_line(*args: str) -> str:
+    """A `flowforge …` command for a person to type, matching how FlowForge was installed (D34, D36)."""
+    import shlex
+
+    kind = install_kind()
+    if kind == "checkout":
+        prefix = ["uv", "--directory", str(CHECKOUT), "run", "flowforge"]
+    elif kind == "uvx":
+        prefix = ["uvx", DIST_NAME]
+    else:
+        prefix = ["flowforge"]
+    return shlex.join([*prefix, *args])
+
+
 def flowforge_home() -> Path:
     return Path(os.getenv("FLOWFORGE_HOME") or Path.home() / ".flowforge")
 

{flowforge_map-0.1.0 → flowforge_map-0.2.0}/backend/flowforge/main.py

@@ -12,6 +12,7 @@ import json
 import os
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from pathlib import Path
 from typing import Any
 
 from dotenv import load_dotenv
@@ -23,6 +24,7 @@ from flowforge.api import agent as agent_api
 from flowforge.api import checks as checks_api
 from flowforge.api import connectors as connectors_api
 from flowforge.api import flowmap as flowmap_api
+from flowforge.api import keys as keys_api
 from flowforge.api import runs as runs_api
 from flowforge.api import scan as scan_api
 from flowforge.api import security as security_api
@@ -85,6 +87,8 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
         s.flows["deps"].planner = ScanPlanner(scan_api.EXAMPLE_REPO)
         s.flows["flow"].planner = CodeFlowPlanner(scan_api.EXAMPLE_REPO, lambda: example_data.latencies(storage))
     else:   # your folder: from --repo or the last one chosen, mapped now if it has no maps yet
+        keys_api.learn_saved_keys(s, Path(os.environ["FLOWFORGE_REPO"]) if os.getenv("FLOWFORGE_REPO")
+                                  else scan_api.repo_path(s))
         scan_api.startup_repo(storage, s.flows)
     if example:  # offline nodes and a seeded history, never mixed with real data (D16)
         example_data.install(s)
@@ -114,6 +118,7 @@ app.include_router(scan_api.router)
 app.include_router(checks_api.router)
 app.include_router(agent_api.router)
 app.include_router(security_api.router)
+app.include_router(keys_api.router)
 
 
 @app.get("/workflows")