graphban-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: gban — a Graphban client for the human at a terminal
 Project-URL: Homepage, https://github.com/asc-me/graphban
 Project-URL: Repository, https://github.com/asc-me/graphban
@@ -130,7 +130,7 @@ project is not a mistake anybody notices quickly.
 `setup` mints a project-scoped credential, writes the `graphban` and `gbfleet` MCP entries
 into every parent harness that would actually read them, stores that key next to the login
 session (a `gb_sk_…`, never the refresh token), installs the supervisor if it is missing,
-drops the delegation skill into `.claude/skills/`, and then **verifies** rather than
+drops the shipped skills into `.claude/skills/` and `.agents/skills/`, and then **verifies** rather than
 asserting: it asks the new credential what it can actually see. Restart the session that will
 call `delegate`/`spawn` afterwards — MCP servers are read at startup.
 

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/README.md

@@ -115,7 +115,7 @@ project is not a mistake anybody notices quickly.
 `setup` mints a project-scoped credential, writes the `graphban` and `gbfleet` MCP entries
 into every parent harness that would actually read them, stores that key next to the login
 session (a `gb_sk_…`, never the refresh token), installs the supervisor if it is missing,
-drops the delegation skill into `.claude/skills/`, and then **verifies** rather than
+drops the shipped skills into `.claude/skills/` and `.agents/skills/`, and then **verifies** rather than
 asserting: it asks the new credential what it can actually see. Restart the session that will
 call `delegate`/`spawn` afterwards — MCP servers are read at startup.
 

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphban-cli"
-version = "0.7.0"
+version = "0.8.0"
 description = "gban — a Graphban client for the human at a terminal"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -43,3 +43,24 @@ packages = ["src/gban"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src", "tests"]
+
+# Read by `scripts/scan_ci.py` (`bandit -c pyproject.toml -r .`, GRPH-1110). Any other finding
+# is fixed or carries a line-level `# nosec <id>` with its reason.
+[tool.bandit]
+exclude_dirs = [
+    # Test code asserts by design (B101) and fakes credentials. It is not in the wheel.
+    "tests",
+    # A local virtualenv is third-party code, audited by pip-audit, not ours to lint.
+    ".venv",
+]
+skips = [
+    # B404 (import subprocess): this is a developer CLI whose job is driving git, gh and the
+    # user's own tools. Importing subprocess is the feature, not a smell.
+    "B404",
+    # B603 (subprocess without shell=True): fires on EVERY argv-list call, which is the safe
+    # form. B602 (shell=True) stays on, and that is the injection check that matters.
+    "B603",
+    # B607 (partial executable path): `git`/`gh` are resolved from the user's own PATH on
+    # their own machine on purpose; hardcoding /usr/bin/git breaks every Homebrew install.
+    "B607",
+]

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/src/gban/cli.py

@@ -442,6 +442,7 @@ def cmd_stack(args) -> int:
     text = stackmap.canonical(record)
     if args.dry_run:
         sys.stdout.write(text)
+        print(f"{PROG}: dry run, nothing posted", file=sys.stderr)
         return 0
     if not project:
         print(f"{PROG}: `{PROG} stack map` needs a project to post. Pass --project, set "
@@ -463,8 +464,31 @@ def cmd_stack(args) -> int:
               f"${config.API_KEY_ENV}, or run `{PROG} setup`. The login session is not a "
               f"key and is not sent.", file=sys.stderr)
         return EXIT_REFUSED
-    stackmap.post_record(url, key, record)
+    # The record goes to stdout only after the server took it: a refused post must not
+    # leave behind something that reads like a record that was sent (GRPH-1103).
+    try:
+        receipt = stackmap.post_record(url, key, record)
+    except Refused as exc:
+        try:
+            reasons = json.loads(exc.detail)
+        except ValueError:
+            reasons = None
+        if not isinstance(reasons, list):
+            raise
+        print(f"{PROG}: the server refused the app map (HTTP {exc.status}):", file=sys.stderr)
+        for reason in reasons:
+            if isinstance(reason, dict):
+                print(f"     {reason.get('path', '?')}: {reason.get('reason', '')}",
+                      file=sys.stderr)
+            else:
+                print(f"     {reason}", file=sys.stderr)
+        return EXIT_REFUSED
     sys.stdout.write(text)
+    receipt = receipt if isinstance(receipt, dict) else {}
+    sha = str(receipt.get("mapped_sha") or record.get("mapped_sha") or "")[:7]
+    said = [f"{k} {receipt[k]}" for k in ("mapped_at", "posted_by") if receipt.get(k)]
+    print(f"{PROG}: posted {receipt.get('project_id') or project} app map at {sha} to {url}"
+          + (f" ({', '.join(said)})" if said else ""), file=sys.stderr)
     return 0
 
 

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/src/gban/client.py

@@ -85,11 +85,15 @@ class Client:
 
     # ---- transport ---------------------------------------------------------------------
     def _open(self, method: str, path: str, body: dict | None, headers: dict) -> tuple[int, dict]:
+        if not self.url.startswith(("http://", "https://")):
+            # urlopen would read `file:` and friends too, and send the credential with it.
+            raise Unreachable(f"could not reach {self.url}: not an http(s) URL")
         data = json.dumps(body).encode() if body is not None else None
         request = urllib.request.Request(self.url + path, data=data, method=method,
                                          headers={"Content-Type": "application/json", **headers})
         try:
-            with urllib.request.urlopen(request, timeout=TIMEOUT) as response:
+            # bandit B310: the scheme is checked to be http(s) above.
+            with urllib.request.urlopen(request, timeout=TIMEOUT) as response:  # nosec B310
                 raw = response.read().decode() or "{}"
                 return response.status, (json.loads(raw) if raw.strip() else {})
         except urllib.error.HTTPError as exc:
@@ -115,6 +119,10 @@ class Client:
             detail = payload.get("detail") or payload.get("message") or f"HTTP {status}"
             if isinstance(detail, dict):
                 detail, hint = (detail.get("message") or str(detail)), detail.get("hint", "")
+            elif isinstance(detail, list):
+                # A list of reasons (e.g. `{path, reason}` from a refused app map) stays JSON,
+                # so a caller can read it back rather than parse a Python repr.
+                detail, hint = json.dumps(detail), payload.get("hint", "")
             else:
                 hint = payload.get("hint", "")
             raise Refused(status, str(detail), str(hint))

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/src/gban/setup.py

@@ -585,13 +585,19 @@ def supervisor(install: bool) -> list[dict]:
 # `backend/app/services/artifacts.py` maps the `skill` tier to `.claude/skills/{slug}/SKILL.md`,
 # `file_additive`, frontmatter with `name` and `description` followed by numbered steps. A skill
 # written here in a different shape would be one the inventory scan reports and the learning loop
-# cannot reason about.
+# cannot reason about. That copy is what Claude, Grok, Cursor, and gbagent read.
+#
+# Qwen 0.23, agy, and dsh do not read `.claude/skills`. They read `<repo>/.agents/skills`
+# (Qwen also reads `.qwen/skills`; one of the two is enough). The same bytes go there.
+# gbagent walks both trees and keeps one copy per `name`.
 #
 # Every directory under `skills/` that holds a SKILL.md is installed. Naming only
 # `graphban-delegation` here is how a second skill (`watch-wave`) would exist in the
 # wheel and never reach a checkout.
 
 SKILL_SLUG = "graphban-delegation"
+#: Inventory path first. The second is the directory the other harnesses share.
+SKILL_DEST_DIRS = (".claude/skills", ".agents/skills")
 
 
 def skills_root() -> Path:
@@ -613,20 +619,28 @@ def shipped_slugs() -> list[str]:
     )
 
 
-def install_skill(repo: Path, slug: str = SKILL_SLUG) -> tuple[str, Path]:
-    """`(status, path)`. Never overwrites: a person may have edited theirs, and a setup command
-    that silently replaced it would take that edit away without saying so."""
-    dest = repo / ".claude" / "skills" / slug / "SKILL.md"
+def skill_dests(repo: Path, slug: str) -> list[Path]:
+    return [repo / rel / slug / "SKILL.md" for rel in SKILL_DEST_DIRS]
+
+
+def install_skill(repo: Path, slug: str = SKILL_SLUG) -> list[tuple[str, Path]]:
+    """One `(status, path)` per harness directory. Never overwrites: a person may have edited
+    theirs, and a setup command that silently replaced it would take that edit away without
+    saying so. A dest that differs does not block the other directories."""
     body = skill_source(slug).read_text(encoding="utf-8")
-    if dest.exists():
-        return ("same" if dest.read_text(encoding="utf-8") == body else "differs"), dest
-    dest.parent.mkdir(parents=True, exist_ok=True)
-    dest.write_text(body, encoding="utf-8")
-    return "written", dest
+    out = []
+    for dest in skill_dests(repo, slug):
+        if dest.exists():
+            out.append(("same" if dest.read_text(encoding="utf-8") == body else "differs", dest))
+            continue
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(body, encoding="utf-8")
+        out.append(("written", dest))
+    return out
 
 
 def skill(repo: Path) -> list[dict]:
-    """Teach the agent the two calls, once, in the place its harness looks."""
+    """Teach the agent the procedure, in every directory a fleet harness reads."""
     slugs = shipped_slugs()
     if not slugs:
         return [_line("local", UNKNOWN, "skill",
@@ -634,17 +648,20 @@ def skill(repo: Path) -> list[dict]:
     lines = []
     for slug in slugs:
         try:
-            status, dest = install_skill(repo, slug)
+            outcomes = install_skill(repo, slug)
         except OSError as exc:
             lines.append(_line("local", UNKNOWN, "skill",
                                f"could not write {slug}: {exc}"))
             continue
-        if status == "differs":
-            lines.append(_line("local", UNKNOWN, "skill",
-                               f"{dest} exists and differs from the one shipped here — left alone"))
-            continue
-        lines.append(_line("local", PASS, "skill",
-                           f"{dest}" + ("" if status == "written" else " (already current)")))
+        current = []
+        for status, dest in outcomes:
+            if status == "differs":
+                lines.append(_line("local", UNKNOWN, "skill",
+                                   f"{dest} exists and differs from the one shipped here — left alone"))
+            else:
+                current.append(f"{dest}" + ("" if status == "written" else " (already current)"))
+        if current:
+            lines.append(_line("local", PASS, "skill", "; ".join(current)))
     return lines
 
 

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/src/gban/skills/graphban-delegation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: graphban-delegation
-description: Hand a Graphban work item to a child agent running on a cheaper model, and enable delegation on a project that does not have it yet. Use when asked to delegate, fan out, spawn a worker, or run a wave.
+description: Hand a Graphban work item to a child agent running on a cheaper model, and enable delegation on a project that does not have it yet. Use when asked to delegate, fan out, spawn a worker, mint seats, retire a wave, or run a wave.
 ---
 
 # Delegating a Graphban item
@@ -186,6 +186,15 @@ chose the item, wrote the brief and picked the tier; review exists to be a secon
 So a delegated item needs a second agent to review it. Plan for that, or the work stops at
 `review` with nobody entitled to clear it.
 
+## Before a wave of seats
+
+`delegate(seat=true)` is one item. Several seats is `mint_enrolment`.
+
+- `propose_allocation` first. It names workers and which cluster each would take. Nothing is assigned until `assign_role`.
+- `collision_clusters(holds=true)` before claiming. `predicted: true` means the grouping used inferred areas.
+- `mint_enrolment(review_only=true)` when that seat may review and must not take build work. The child still registers as `worker`. One seat per agent: two agents on one seat cannot review each other.
+- `retire_wave` revokes the seats you minted and releases what they hold. It does not stop the processes. `agents_still_running` are still building against dead seats.
+
 ## When not to use this
 
 For a whole backlog, ask the person to run `gbfleet until` instead. It runs the wave with no

graphban_cli-0.8.0/src/gban/skills/graphban-orient/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: graphban-orient
+description: >
+  Read a Graphban-tracked repo through the code graph before grep or a wide
+  file read. Use when starting work, finding where code lives, or before
+  search_code, code_neighbors, get_code_map, search_memory, or a filesystem
+  crawl. Use when the user runs /graphban-orient.
+user-invocable: true
+---
+
+# Orient
+
+Ask the graph before you read the tree. One graph call replaces a crawl.
+
+1. `get_context` once per session. Keep the project id, `missing_tiers`, and gitops. A later call does not refresh a manifest that was fetched at connect.
+2. Unset gitops (`source` unmeasured, or `control` `linked_unreachable`) is unmeasured. Leave the base branch, the branch pattern, and the release doc alone until a field has a source.
+3. `search_code(query, top_k=5)` before grep.
+4. `code_neighbors(path)` before opening a file to learn what calls it or what it calls.
+5. `search_memory(query, top_k=3)` once per task. Leave `include_candidates` off. A candidate is not a published fact. Writing a shard is `graphban-work`.
+6. `related_work(id)` once you have an item id.
+7. Open a file when you have a path and a question.
+
+List reads stay on the default `fields=lean`. `search_items` and `get_backlog` return id, title, and status. The one full item read is `get_item_details`, for the item you took. Claiming is `graphban-work`.
+
+`get_code_map` takes a `kind` and a small `limit`. With neither, the reply is up to 200 nodes. Check `truncated` when you do call it.
+
+Looking around uses the reads above. `describe_code`, `link_code`, and `unlink_code` write the graph.
+
+A spec question is `graphban-prd`. `get_prd` is for editing a spec, not for finding a file.
+
+`missing_tiers` on `get_context` means those tools were left out of the prompt. The tier decides what is listed. Scope and role decide what a call may do.

graphban_cli-0.8.0/src/gban/skills/graphban-prd/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: graphban-prd
+description: >
+  Author, grill, decompose, or close a Graphban PRD. Use when writing a spec,
+  running a grill, answer_grill, update_prd, decompose_prd, request_rebaseline,
+  close_prd, or submit_verdict, or when the user runs /graphban-prd.
+user-invocable: true
+---
+
+# PRDs
+
+Approval is the grill finishing. `update_prd` cannot set `approved`.
+
+Read with one call. `get_prd` when you will edit. `prd_coverage` for gaps: `shaped: false` is not a clean pass, `gaps` means no tasks, `empty_sections` means no substance. `prd_acceptance` with one `view` for delivery. `completeness` is the view that lists baselined sections with nothing delivered.
+
+## Grill
+
+`grill_prd` returns the next questions and records nothing. Ask the author. `answer_grill` with their words. `graded: false` means the grader was not asked and this answer was not judged. Call `grill_prd` again while `outstanding` remains. `complete` is the grill finishing, which is what reaches approved.
+
+Recording an answer with `update_prd` replaces markdown and leaves the PRD in `draft`, with no turns and no dimensions.
+
+## Edit
+
+`update_prd(section=<the ## heading>, body=<that section>)` rewrites one section. A whole-body replace needs `base_hash` from `get_prd`. A moved hash is a refusal. `status` on this call is `draft` or `review`.
+
+## Decompose
+
+`decompose_prd` with `create` false first. One proposed task per uncovered section. The task carries the section's framing, so the worker does not also read the PRD. Framing sections are tasks only when `include_prose` is true. `create` true files them once the grill has approved the PRD.
+
+## Rebaseline
+
+`request_rebaseline(reason_type, reason)` in your own words. `reason_type` is `learning`, `scope-change`, or `correction`. It reopens the grill. The current baseline governs until a new one is earned. Adding a section is a new PRD. A closed PRD is refused.
+
+## Close
+
+`close_prd` is terminal. Every section that `completeness` says has nothing delivered appears once in `dispositions`, as `promoted` (`promote_to` `item` or `prd`) or `deferred` with a reason. After close, further work is a new PRD.
+
+## Verdict
+
+`submit_verdict` citations are `{kind, ref}` and must resolve. `kind` is `code` (a code-graph path), `intent` (a baseline section — what an absence finding cites), or `evidence` (an item key). A citation that does not resolve is rejected. Signing work you claimed is flagged.

graphban_cli-0.8.0/src/gban/skills/graphban-review/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: graphban-review
+description: >
+  Review a Graphban item you did not build: claim_review, sign_off, or bounce.
+  Use when reviewing, signing off, or bouncing an item, or when the user runs
+  /graphban-review.
+user-invocable: true
+---
+
+# Review
+
+Review is a second person. `claim_review` refuses the builder.
+
+1. `claim_review`. `claimed: false` means the item is yours, or it needs `gh` or `human-only` you did not declare. Stop on that item.
+2. The diff is the `branch` on the claim. Read that branch. A review does not orient the whole repo.
+3. `sign_off` needs `evidence` and the `commit` SHA you reviewed. It refuses the builder, and it refuses the delegation's `delegated_by`. Above the effort bar it also refuses without a `sabotage` receipt: something broken on purpose and caught by a test. `tests_failed` of zero means the test cannot fail.
+4. `waive` is `{predicate: reason}` for a check that could not run. A check that ran and failed stays failed. The field does not clear it.
+5. `bounce(id, reason)` sends it to `next`. The author keeps the worktree for one lease, then the fleet can take it. The person who delegated the item may bounce it. They may not sign it off.
+6. When the item cites a PRD, call `prd_acceptance` with one `view`. Those views describe what happened. They do not report complete. `get_prd` for the whole body is an edit, not a review. Authoring is `graphban-prd`.
+
+`release_item` on a review claim leaves the item in `review`. A bounce is `bounce`.

graphban_cli-0.8.0/src/gban/skills/graphban-scan/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: graphban-scan
+description: >
+  Record Graphban code-health scans without treating a missing scan as clean.
+  Use when running a security or health scan, or calling scans_due, scan_status,
+  or record_scan, or when the user runs /graphban-scan.
+user-invocable: true
+---
+
+# Scans
+
+A missing scan is not a clean scan.
+
+1. `scans_due(head_sha)`. An empty due list is not all-clean. Rows that were `never_scanned`, including security, stay listed.
+2. `scan_status` for one path, or with no path for every deployable. Pass `head_sha`. States are `clean_at_sha`, `has_findings`, `never_scanned`, or `stale`.
+3. Run the scanner. `record_scan` needs `scanner_id`, `path`, and `scanned_sha`.
+   - `findings: []` is clean at that SHA. A clean row without a SHA cannot age.
+   - The same `scanner_id` and path replaces the previous row.
+   - The security category is pip-audit, bandit, npm-audit, and semgrep. Other categories are `refactor`, `stub`, `deadcode`, `coverage`, `tests`, and `work`.
+   - Category `tests` also sends `tests.passed`, `tests.failed`, and `tests.skipped`.
+   - Each finding needs a `summary`. Findings are untrusted. `scanner_id`, `scanner_version`, and the reporter are provenance.
+
+A clean row is not a tracker item. A finding that already names `link_ref` points at work that exists.

graphban_cli-0.8.0/src/gban/skills/graphban-work/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: graphban-work
+description: >
+  Claim and finish one Graphban item: register, claim_cluster or claim_next,
+  heartbeat, evidence, release. Use when claiming work, implementing an item,
+  updating item status, recording evidence, or when the user runs /graphban-work.
+user-invocable: true
+---
+
+# Work an item
+
+Take one item, leave a receipt, hand it to review. Reading the repo is `graphban-orient`: `search_code`, then `code_neighbors`, before grep or a wide read.
+
+1. In a fleet, `register_agent` once before any claim. Read `active_role`, `heartbeat_interval_seconds`, and `tools_off_limits`. A name in `tools_off_limits` is still in the prompt; the server refuses the call. Heartbeat on that interval. Pass `agent_id` from this registration on later calls.
+2. Fleet: `claim_cluster`. Solo: `claim_next`. `claimed: false` names who holds the area and when it frees. That is the answer. Take different work.
+3. `get_item_details` once. The `brief` suggests `lane` and `tier` with a basis. You still choose both if you hand it to a child.
+4. `heartbeat(id, status=<one line>, files=[the paths you are in])` on the lease interval. A heartbeat is not a `fleet_status` poll.
+5. `update_item` as you go. Evidence appends. Touchpoints union: send the files you actually touched. An empty touchpoint list writes nothing. Status goes to `review`.
+6. Stopping unfinished: `release_item`. A blocker that is still true tomorrow is status `blocked` with `blocker` set. `backlog` is claimable and will be handed out again. A build claim released without `to_status` goes back to `next`.
+
+Signing off is `graphban-review`. The builder does not set `done`.
+
+Memory, when the next agent cannot see the lesson in the diff:
+
+- `search_memory` first, as in `graphban-orient`.
+- `add_memory`. Read the returned `status`. `candidate` does not appear in later search. A near-duplicate is rejected.
+- `publish_memory` asks a judge. `kept: false` is a normal result.
+
+Handing the item to a child is `graphban-delegation`. That is a `delegate`, not a second claim.

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/src/gban/skills/watch-wave/SKILL.md

@@ -30,8 +30,16 @@ Items: ID1, ID2, …
 Children if known: AGENT_IDS
 PRs if known: #N
 
-Call gbfleet__ps, graphban__fleet_status(view="live"), and
-graphban__get_item_details for each item.
+Call gbfleet__ps and graphban__fleet_status(view="live").
+
+Read each watched item from agents[].holdings (id, status, phase). Live
+omits offline agents and drops the bounced flag.
+
+For a watched id that is in no holding, one graphban__search_items call
+with query set to that id and fields=lean. Not get_item_details.
+
+Call graphban__get_item_details for a single id only when its status or
+phase changed since the last fire, or when you need the bounce reason.
 
 Report <=12 lines: running vs stopped, each item's status/claim/PR, quiet
 (silent_for / quiet), bounce, or expired-nothing-claimed.

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/src/gban/stackmap.py

@@ -42,7 +42,8 @@ _SKIP_DIRS = frozenset({
     ".next", "coverage", "vendor", ".gbfleet", ".hg", ".svn",
 })
 _MAX_BYTES = 1_000_000
-_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "0.0.0.0", "host.docker.internal"})
+# bandit B104: hostnames to recognise in a URL, nothing binds to them.
+_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "0.0.0.0", "host.docker.internal"})  # nosec B104
 #: Where a local host lands when no table row or single infra node of its kind claims it.
 #: One node for "this machine", whatever spelling the URL used: `host.docker.internal` is
 #: Docker's name for the same host `localhost` names, not a service the app calls.
@@ -853,6 +854,13 @@ class _Builder:
         self.by_dir: dict[str, str] = {}
         self.kind_of: dict[str, str] = {}
         self.warnings: list[str] = []
+        # Which compose services name an env variable, and which read a template
+        # through `env_file:`. Every service counts, not only the ones that build a
+        # component: a repo-root template is attributed from these.
+        self.env_users: dict[str, set[str]] = {}
+        self.env_file_users: dict[str, set[str]] = {}
+        # Names each `.env.example` declares, keyed by its directory.
+        self.template_names: dict[str, set[str]] = {}
 
     def _ids(self) -> set[str]:
         return set(self.components) | set(self.infra) | set(self.external) | set(self.unresolved)
@@ -1109,6 +1117,32 @@ def _extends(service: Marked) -> tuple[str, str, int] | None:
     return None
 
 
+def _env_files(service: Marked, compose: Path, repo: Path) -> list[str]:
+    """Repo-relative paths a service's `env_file:` names."""
+    if not isinstance(service.value, dict):
+        return []
+    node = service.value.get("env_file")
+    if not isinstance(node, Marked):
+        return []
+    items = node.value if isinstance(node.value, list) else [node]
+    out: list[str] = []
+    for item in items:
+        if not isinstance(item, Marked):
+            continue
+        raw = item.value
+        if isinstance(raw, dict):
+            # The long form: `- path: ./x.env`.
+            raw = raw.get("path").value if isinstance(raw.get("path"), Marked) else None
+        if not isinstance(raw, str) or not raw.strip():
+            continue
+        try:
+            target = (compose.parent / raw.strip().strip("'\"")).resolve()
+            out.append(target.relative_to(repo.resolve()).as_posix())
+        except ValueError:
+            continue
+    return out
+
+
 def _walk_compose(builder: _Builder, path: Path) -> None:
     text = _read_text(path)
     if text is None:
@@ -1185,7 +1219,13 @@ def _walk_compose(builder: _Builder, path: Path) -> None:
             builder.add_edge(src, target, protocol, "depends_on", prov)
         env_node = service.value.get("environment")
         for ename, raw, line in _as_env(env_node if isinstance(env_node, Marked) else None):
+            for mentioned in [ename] + _INTERP.findall(raw):
+                mentioned = re.split(r"[:?+-]", mentioned, maxsplit=1)[0].strip()
+                if mentioned:
+                    builder.env_users.setdefault(mentioned, set()).add(src)
             builder.apply_env_name(ename, raw, line, file, [src], "compose.env")
+        for template in _env_files(service, path, builder.repo):
+            builder.env_file_users.setdefault(template, set()).add(src)
 
 
 def _walk_dockerfile(builder: _Builder, path: Path) -> None:
@@ -1247,6 +1287,61 @@ def _walk_manifest(builder: _Builder, path: Path) -> None:
                          str(row.get("label") or ""), prov)
 
 
+def _template_entries(text: str) -> list[tuple[str, str, int]]:
+    """`(name, raw_value, line)` for each assignment in an env template."""
+    entries: list[tuple[str, str, int]] = []
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):].strip()
+        if "=" not in line:
+            continue
+        name, _, raw_value = line.partition("=")
+        name = name.strip()
+        if len(raw_value) >= 2 and raw_value[0] == raw_value[-1] and raw_value[0] in ("'", '"'):
+            raw_value = raw_value[1:-1]
+        entries.append((name, raw_value, lineno))
+    return entries
+
+
+def _note_template(builder: _Builder, path: Path) -> None:
+    text = _read_text(path)
+    if text is None:
+        return
+    names = {name for name, _raw, _line in _template_entries(text)}
+    builder.template_names.setdefault(_rel(path.parent, builder.repo), set()).update(names)
+
+
+def _root_consumers(builder: _Builder, file: str,
+                    entries: list[tuple[str, str, int]]) -> dict[str, list[str]] | None:
+    """Per name, the compose services a repo-root template's variable belongs to.
+
+    Any compose service counts, a plain `image:` one too. None only when no
+    service names any of the template's variables or reads it: the caller then
+    falls back to every component and says so. A name compose does not mention goes to
+    the components whose own directory template declares it, else to the
+    component at the repo root, else to nobody. The node is still drawn.
+    """
+    readers = builder.env_file_users.get(file, set())
+    names = [name for name, _raw, _line in entries if _interesting_env(name)]
+    if not readers and not any(name in builder.env_users for name in names):
+        return None
+    root = builder.by_dir.get("")
+    out: dict[str, list[str]] = {}
+    for name in names:
+        users = readers | builder.env_users.get(name, set())
+        if not users:
+            users = {builder.by_dir[folder]
+                     for folder, declared in builder.template_names.items()
+                     if folder and name in declared and folder in builder.by_dir}
+        if not users and root:
+            users = {root}
+        out[name] = sorted(users)
+    return out
+
+
 def _walk_env_template(builder: _Builder, path: Path) -> None:
     text = _read_text(path)
     if text is None:
@@ -1254,8 +1349,15 @@ def _walk_env_template(builder: _Builder, path: Path) -> None:
         return
     file = _rel(path, builder.repo)
     directory = _rel(path.parent, builder.repo)
+    entries = _template_entries(text)
+    consumers: dict[str, list[str]] | None = None
     if directory == "":
+        consumers = _root_consumers(builder, file, entries)
         sources = sorted(builder.components)
+        if consumers is None and len(sources) > 1:
+            builder.warnings.append(
+                f"{file}: no compose service names its variables or reads it; "
+                f"its names are attributed to every component")
     else:
         owner = builder.owner(directory)
         sources = [owner] if owner else []
@@ -1266,19 +1368,9 @@ def _walk_env_template(builder: _Builder, path: Path) -> None:
         # the names belong to, so the edges have somewhere to start.
         sources = [builder.add_component(
             ".", "", ".", _provenance(file, "env.template", 1))]
-    for lineno, raw in enumerate(text.splitlines(), 1):
-        line = raw.strip()
-        if not line or line.startswith("#"):
-            continue
-        if line.startswith("export "):
-            line = line[len("export "):].strip()
-        if "=" not in line:
-            continue
-        name, _, raw_value = line.partition("=")
-        name = name.strip()
-        if len(raw_value) >= 2 and raw_value[0] == raw_value[-1] and raw_value[0] in ("'", '"'):
-            raw_value = raw_value[1:-1]
-        builder.apply_env_name(name, raw_value, lineno, file, sources, "env.template")
+    for name, raw_value, lineno in entries:
+        named = consumers.get(name, sources) if consumers is not None else sources
+        builder.apply_env_name(name, raw_value, lineno, file, named, "env.template")
 
 
 def _sha(repo: Path) -> str:
@@ -1333,9 +1425,11 @@ def build_record(start: Path, *, project_id: str = "") -> tuple[dict, list[str]]
     for path in files:
         if _is_manifest(path):
             _walk_manifest(builder, path)
-    for path in files:
-        if path.name == ".env.example":
-            _walk_env_template(builder, path)
+    templates = [path for path in files if path.name == ".env.example"]
+    for path in templates:
+        _note_template(builder, path)
+    for path in templates:
+        _walk_env_template(builder, path)
     if not (builder.components or builder.infra or builder.external or builder.unresolved):
         raise MapError("nothing to map: no compose service, Dockerfile or known dependency")
     return builder.finish(sha), builder.warnings

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/src/gban/swamp.py

@@ -35,7 +35,7 @@ from gban.doctor import FAIL, PASS, UNKNOWN, _line
 #: What `docs/swamp.md` §5 names. Changing either renames somebody's existing wiring, so they
 #: are constants rather than options.
 VAULT = "secrets"
-SECRET_KEY = "graphban-api-key"
+SECRET_KEY = "graphban-api-key"  # nosec B105 — the vault entry's NAME, not its value
 VAULT_TYPE = "local_encryption"
 
 #: The adapter repository, a SIBLING of the checkout — `docs/swamp.md` says "sibling, not this

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/tests/test_session.py

@@ -154,6 +154,47 @@ def test_an_unreachable_server_is_a_different_exit_code_from_an_expired_session(
     assert "could not reach" in capsys.readouterr().err
 
 
+@pytest.mark.parametrize("url", ["file:///etc/passwd", "gb.example.com", "ftp://gb.example.com"])
+def test_a_url_that_is_not_http_is_refused_before_anything_is_opened(url, monkeypatch):
+    """GRPH-1112. urlopen reads `file:` too, and would send the credential along. Sabotage:
+    delete the scheme check and urlopen is reached, so this fails."""
+    from gban.client import Client
+
+    def opened(*_args, **_kwargs):
+        raise AssertionError("urlopen was reached")
+
+    monkeypatch.setattr("gban.client.urllib.request.urlopen", opened)
+    with pytest.raises(Unreachable, match="not an http\\(s\\) URL"):
+        Client(url, api_key="KEY").call("GET", "/api/whoami")
+
+
+@pytest.mark.parametrize("url", ["http://127.0.0.1:8000", "https://gb.example.com/"])
+def test_an_http_or_https_server_url_still_reaches_urlopen(url, monkeypatch):
+    """GRPH-1112. The check must not refuse a configured server URL gban is meant to use."""
+    from gban.client import Client
+    seen = []
+
+    class _Response:
+        status = 200
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *_exc):
+            return False
+
+        def read(self):
+            return b'{"ok": true}'
+
+    def opened(request, timeout):
+        seen.append(request.full_url)
+        return _Response()
+
+    monkeypatch.setattr("gban.client.urllib.request.urlopen", opened)
+    assert Client(url, api_key="KEY").call("GET", "/api/whoami") == {"ok": True}
+    assert seen == [url.rstrip("/") + "/api/whoami"]
+
+
 def test_a_refusal_is_printed_in_the_servers_own_words_with_its_hint(home, monkeypatch, capsys):
     """4 / D8. Sabotage: re-word the refusal and this fails — the client would then hold a
     second copy of a rule the server already enforces."""

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/tests/test_setup.py

@@ -515,6 +515,8 @@ def test_setup_installs_the_skill_where_the_product_says_skills_live(tmp_path, w
     dest = repo / ".claude" / "skills" / "graphban-delegation" / "SKILL.md"
     assert dest.exists()
     assert dest.read_text().startswith("---\nname: graphban-delegation\n")
+    other = repo / ".agents" / "skills" / "graphban-delegation" / "SKILL.md"
+    assert other.read_text() == dest.read_text()
     # THE CALL: skipping `skill()` in run() would leave this dest missing the
     # watcher paragraph while skill_source() tests still passed.
     body = dest.read_text()
@@ -533,9 +535,11 @@ def test_setup_installs_every_shipped_skill(tmp_path, wired):
     assert "graphban-delegation" in slugs
     assert "watch-wave" in slugs
     for slug in slugs:
-        dest = repo / ".claude" / "skills" / slug / "SKILL.md"
-        assert dest.exists(), slug
-        assert dest.read_text() == setup_mod.skill_source(slug).read_text()
+        body = setup_mod.skill_source(slug).read_text()
+        for rel in setup_mod.SKILL_DEST_DIRS:
+            dest = repo / rel / slug / "SKILL.md"
+            assert dest.exists(), dest
+            assert dest.read_text() == body
     assert sum(1 for l in lines if l.get("name") == "skill" and l.get("status") == "PASS") == len(slugs)
 
 
@@ -552,6 +556,9 @@ def test_an_edited_skill_is_left_alone(tmp_path, wired):
 
     assert dest.read_text() == "mine\n"
     assert any("left alone" in l["detail"] for l in lines)
+    # The edited copy stays. The directory a different harness reads is still installed.
+    agents = repo / ".agents" / "skills" / "graphban-delegation" / "SKILL.md"
+    assert agents.read_text() == setup_mod.skill_source("graphban-delegation").read_text()
     # Editing one skill does not skip the others.
     other = repo / ".claude" / "skills" / "watch-wave" / "SKILL.md"
     assert other.exists()

{graphban_cli-0.7.0 → graphban_cli-0.8.0}/tests/test_stackmap.py

@@ -537,3 +537,184 @@ def test_ignored_and_untracked_files_are_not_mapped(tmp_path):
         (repo / stray / "Dockerfile").write_text("FROM python:3.12\n", encoding="utf-8")
     record, _ = stackmap.build_record(repo)
     assert [n["dir"] for n in record["components"]] == ["app"]
+
+
+def _root_template_repo(tmp_path, compose: str | None) -> Path:
+    repo = tmp_path / "rooted"
+    repo.mkdir()
+    for name in ("api", "web"):
+        (repo / name).mkdir()
+        (repo / name / "requirements.txt").write_text("stripe==8.0\n", encoding="utf-8")
+    if compose is not None:
+        (repo / "compose.yml").write_text(compose, encoding="utf-8")
+    (repo / ".env.example").write_text("OPENAI_API_KEY=\n", encoding="utf-8")
+    _commit(repo)
+    return repo
+
+
+def test_a_root_template_name_goes_to_the_service_that_declares_it(tmp_path):
+    """GRPH-1104: a root .env.example drew web -> openai when only api reads it."""
+    repo = _root_template_repo(tmp_path,
+        "services:\n"
+        "  api:\n"
+        "    build: ./api\n"
+        "    environment:\n"
+        "      - OPENAI_API_KEY\n"
+        "  web:\n"
+        "    build: ./web\n")
+    record, warnings = stackmap.build_record(repo)
+    to_openai = [(e["from"], e["to"]) for e in record["edges"] if e["to"] == "openai"]
+    assert to_openai == [("api", "openai")]
+    assert not [e for e in record["edges"] if e["from"] == "web" and e["to"] != "stripe"]
+    assert warnings == []
+    assert canonical(record) == canonical(stackmap.build_record(repo)[0])
+
+
+def test_a_root_template_with_no_compose_goes_to_every_component_and_says_so(tmp_path):
+    repo = _root_template_repo(tmp_path, None)
+    record, warnings = stackmap.build_record(repo)
+    assert sorted(n["id"] for n in record["components"]) == ["api", "web"]
+    assert sorted(e["from"] for e in record["edges"] if e["to"] == "openai") == ["api", "web"]
+    assert [w for w in warnings if ".env.example" in w]
+
+
+def test_a_root_template_read_through_env_file_goes_to_its_reader(tmp_path):
+    repo = _root_template_repo(tmp_path,
+        "services:\n"
+        "  api:\n"
+        "    build: ./api\n"
+        "  web:\n"
+        "    build: ./web\n"
+        "    env_file: .env.example\n")
+    record, warnings = stackmap.build_record(repo)
+    assert [e["from"] for e in record["edges"] if e["to"] == "openai"] == ["web"]
+    assert warnings == []
+
+
+@pytest.mark.parametrize("worker_env", [
+    "    environment:\n      - OPENAI_API_KEY\n",
+    "    env_file: .env.example\n",
+])
+def test_a_root_template_named_only_by_an_image_service_is_not_every_component(
+        tmp_path, worker_env):
+    """GRPH-1104 bounce: a service that builds nothing still counts as compose naming it."""
+    repo = tmp_path / "imaged"
+    repo.mkdir()
+    for name in ("api", "web"):
+        (repo / name).mkdir()
+        (repo / name / "requirements.txt").write_text("stripe==8.0\n", encoding="utf-8")
+    (repo / "compose.yml").write_text(
+        "services:\n"
+        "  api:\n"
+        "    build: ./api\n"
+        "  web:\n"
+        "    build: ./web\n"
+        "  worker:\n"
+        "    image: alpine\n" + worker_env, encoding="utf-8")
+    (repo / ".env.example").write_text("OPENAI_API_KEY=\nANTHROPIC_API_KEY=\n",
+                                       encoding="utf-8")
+    _commit(repo)
+    record, warnings = stackmap.build_record(repo)
+    assert not [e for e in record["edges"]
+                if e["from"] in ("api", "web") and e["to"] in ("openai", "anthropic")]
+    assert [e["from"] for e in record["edges"] if e["to"] == "openai"] == ["worker"]
+    assert not [w for w in warnings if ".env.example" in w]
+    assert {"openai", "anthropic"} <= {n["id"] for n in record["external"]}
+
+
+def test_this_repo_root_template_draws_no_web_edge_to_a_model_provider():
+    record, _ = stackmap.build_record(ROOT)
+    providers = {"anthropic", "openai", stackmap.LOCAL_NODE}
+    assert not [e for e in record["edges"] if e["from"] == "web" and e["to"] in providers]
+    assert _edge(record, "web", "api", "depends_on")
+    ids = {n["id"] for n in record["external"] + record["infrastructure"]}
+    assert providers <= ids
+
+
+# ---- what a post says it did (GRPH-1103) ----------------------------------------------------
+# A real HTTP server on loopback, so the confirmation and the refusal go through the same
+# transport and error parsing a person's post does.
+
+
+@pytest.fixture()
+def fake_server():
+    import threading
+    from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+    state = {"requests": [], "status": 200, "reply": {}}
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_POST(self):  # noqa: N802
+            raw = self.rfile.read(int(self.headers.get("Content-Length") or 0))
+            state["requests"].append((self.path, self.headers.get("X-API-Key"), json.loads(raw)))
+            reply = state["reply"](json.loads(raw)) if callable(state["reply"]) else state["reply"]
+            data = json.dumps(reply).encode()
+            self.send_response(state["status"])
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+
+        def log_message(self, *_args):
+            pass
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    state["url"] = f"http://127.0.0.1:{server.server_address[1]}"
+    try:
+        yield state
+    finally:
+        server.shutdown()
+        server.server_close()
+
+
+def _mapped_app(isolated, monkeypatch) -> tuple[Path, str]:
+    repo = isolated / "app"
+    repo.mkdir()
+    _write_app(repo)
+    sha = _commit(repo)
+    monkeypatch.setenv("GBFLEET_API_KEY", "gb_sk_seat")
+    return repo, sha
+
+
+def test_a_real_post_says_it_posted_and_where(isolated, monkeypatch, capsys, fake_server):
+    repo, sha = _mapped_app(isolated, monkeypatch)
+    fake_server["reply"] = lambda body: {**body, "mapped_at": "2026-10-23T10:00:00Z",
+                                         "posted_by": "seat-1"}
+    assert main(["--server", fake_server["url"], "--project", "demo",
+                 "stack", "map", "--repo", str(repo)]) == 0
+    assert len(fake_server["requests"]) == 1
+    captured = capsys.readouterr()
+    assert captured.out == canonical(fake_server["requests"][0][2])
+    assert (f"gban: posted demo app map at {sha[:7]} to {fake_server['url']}"
+            in captured.err)
+    assert "posted_by seat-1" in captured.err
+    assert "dry run" not in captured.err
+
+
+def test_dry_run_says_nothing_was_posted(isolated, monkeypatch, capsys, fake_server):
+    repo, _ = _mapped_app(isolated, monkeypatch)
+    assert main(["--server", fake_server["url"], "--project", "demo",
+                 "stack", "map", "--dry-run", "--repo", str(repo)]) == 0
+    captured = capsys.readouterr()
+    assert fake_server["requests"] == []
+    assert "gban: dry run, nothing posted" in captured.err
+    assert "posted demo" not in captured.err
+    assert json.loads(captured.out)["project_id"] == "demo"
+
+
+def test_a_refused_post_prints_the_reasons_and_not_the_record(isolated, monkeypatch, capsys,
+                                                              fake_server):
+    repo, _ = _mapped_app(isolated, monkeypatch)
+    fake_server["status"] = 422
+    fake_server["reply"] = {"detail": [{"path": "edges[2].to", "reason": "unresolved node"},
+                                       {"path": "mapped_sha", "reason": "unknown is not a commit"}]}
+    assert main(["--server", fake_server["url"], "--project", "demo",
+                 "stack", "map", "--repo", str(repo)]) == EXIT_REFUSED
+    assert len(fake_server["requests"]) == 1
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert "edges[2].to: unresolved node" in captured.err
+    assert "mapped_sha: unknown is not a commit" in captured.err
+    assert "posted demo" not in captured.err