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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.8.0
+Version: 0.8.2
 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
@@ -202,8 +202,10 @@ What it reads:
 
 - Compose files (`compose.yml`, `docker-compose.yml`, and the `compose.*` / `docker-compose.*` variants): a service with `build` is a deployable, a service with only `image` is infrastructure, and `depends_on` is an edge. `environment` contributes variable **names** and, when a value is a literal URL, the bare host.
 - Dockerfiles (`Dockerfile`, `Dockerfile.*`, `*.Dockerfile`), for the deployable they sit in and for a `FROM` image the table knows.
-- Dependency manifests (`package.json`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `Cargo.toml`, `Gemfile`), matched against the known-SDK table and attributed to the deployable whose directory contains them.
-- `.env.example` only. A real `.env` is not a template and is not opened. Source files are not scanned.
+- Dependency manifests (`package.json`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `Cargo.toml`, `Gemfile`). Every `package.json` and `Cargo.toml` is a component named from the manifest's `name`. The known-SDK table adds edges; it is not what decides whether the component exists. `file:` and `workspace:` dependencies (and a Cargo `path` or `workspace = true`) are internal edges. Other manifests still become a component only when a dependency hits the table, and that edge is attributed to the component whose directory contains the file.
+- Deploy manifests (`vercel.json`, `railway.json`, `railway.toml`, `fly.toml`, `netlify.toml`, `render.yaml`) are a platform node. The file body is not stored.
+- `.env.example` only. A real `.env` is not a template and is not opened. A commented `KEY=` is read and the edge is `state: documented` rather than `set`. `*_TOKEN`, `*_CLIENT_ID`, and `*_CLIENT_SECRET` count, and so do `*_BASE` and `*_ISSUER` when the value is a URL. A passphrase (`AUTH_SECRET`, `ENCRYPTION_KEY`) is not an edge unless a table row names it. Values stay out of the record.
+- Source files are not scanned. There is no source-HTTP pass in this command. stderr always prints a coverage line: files read, files that produced nothing, commented template keys skipped, and that source was not scanned. Exit 0 means the record was built.
 
 The known-SDK table ships at `cli/src/gban/data/stack_sdks.toml` and is versioned with `gban`. A checkout may add rows in `.graphban/stack-sdks.toml` (same shape); those rows are consulted first.
 

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

@@ -187,8 +187,10 @@ What it reads:
 
 - Compose files (`compose.yml`, `docker-compose.yml`, and the `compose.*` / `docker-compose.*` variants): a service with `build` is a deployable, a service with only `image` is infrastructure, and `depends_on` is an edge. `environment` contributes variable **names** and, when a value is a literal URL, the bare host.
 - Dockerfiles (`Dockerfile`, `Dockerfile.*`, `*.Dockerfile`), for the deployable they sit in and for a `FROM` image the table knows.
-- Dependency manifests (`package.json`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `Cargo.toml`, `Gemfile`), matched against the known-SDK table and attributed to the deployable whose directory contains them.
-- `.env.example` only. A real `.env` is not a template and is not opened. Source files are not scanned.
+- Dependency manifests (`package.json`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `Cargo.toml`, `Gemfile`). Every `package.json` and `Cargo.toml` is a component named from the manifest's `name`. The known-SDK table adds edges; it is not what decides whether the component exists. `file:` and `workspace:` dependencies (and a Cargo `path` or `workspace = true`) are internal edges. Other manifests still become a component only when a dependency hits the table, and that edge is attributed to the component whose directory contains the file.
+- Deploy manifests (`vercel.json`, `railway.json`, `railway.toml`, `fly.toml`, `netlify.toml`, `render.yaml`) are a platform node. The file body is not stored.
+- `.env.example` only. A real `.env` is not a template and is not opened. A commented `KEY=` is read and the edge is `state: documented` rather than `set`. `*_TOKEN`, `*_CLIENT_ID`, and `*_CLIENT_SECRET` count, and so do `*_BASE` and `*_ISSUER` when the value is a URL. A passphrase (`AUTH_SECRET`, `ENCRYPTION_KEY`) is not an edge unless a table row names it. Values stay out of the record.
+- Source files are not scanned. There is no source-HTTP pass in this command. stderr always prints a coverage line: files read, files that produced nothing, commented template keys skipped, and that source was not scanned. Exit 0 means the record was built.
 
 The known-SDK table ships at `cli/src/gban/data/stack_sdks.toml` and is versioned with `gban`. A checkout may add rows in `.graphban/stack-sdks.toml` (same shape); those rows are consulted first.
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "graphban-cli"
-version = "0.8.0"
+version = "0.8.2"
 description = "gban — a Graphban client for the human at a terminal"
 readme = "README.md"
 requires-python = ">=3.12"

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

@@ -433,12 +433,14 @@ def cmd_stack(args) -> int:
     start = Path(args.repo).expanduser() if args.repo else Path.cwd()
     project = (config.resolve(args.project, config.PROJECT_ENV, "project") or "").strip()
     try:
-        record, warnings = stackmap.build_record(start, project_id=project)
+        record, warnings, coverage = stackmap.build_record(start, project_id=project)
     except stackmap.MapError as exc:
         print(f"{PROG}: {exc}", file=sys.stderr)
         return EXIT_REFUSED
     for warning in warnings:
         print(f"{PROG}: {warning}", file=sys.stderr)
+    # Always. A three-node map that exits 0 is not a finished topology.
+    print(f"{PROG}: {coverage}", file=sys.stderr)
     text = stackmap.canonical(record)
     if args.dry_run:
         sys.stdout.write(text)

{graphban_cli-0.8.0 → graphban_cli-0.8.2}/src/gban/data/stack_sdks.toml

@@ -148,6 +148,27 @@ label = "SendGrid"
 protocol = "https"
 domains = ["sendgrid.com", "sendgrid.net"]
 
+[[sdk]]
+id = "resend"
+packages = ["resend"]
+node = "resend"
+group = "external"
+kind = ""
+label = "Resend"
+protocol = "https"
+domains = ["resend.com"]
+
+[[sdk]]
+id = "vercel"
+packages = ["@vercel/functions"]
+prefix = "@vercel/"
+node = "vercel"
+group = "external"
+kind = ""
+label = "Vercel"
+protocol = "https"
+domains = ["vercel.com", "vercel.app"]
+
 [[sdk]]
 id = "supabase"
 packages = ["supabase", "@supabase/supabase-js"]
@@ -175,3 +196,13 @@ group = "infrastructure"
 kind = "redis"
 label = "Redis"
 protocol = "redis"
+
+[[env]]
+id = "creem"
+names = ["CREEM_API_KEY"]
+node = "creem"
+group = "external"
+kind = ""
+label = "Creem"
+protocol = "https"
+domains = ["creem.io"]

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

@@ -1,6 +1,10 @@
 ---
 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, mint seats, retire a wave, or run a wave.
+description: >
+  Hand one Graphban item to one child on a cheaper model, and enable
+  delegation on a project that does not have it yet. Use when asked to
+  delegate one item, spawn one worker, mint seats, or retire a wave.
+  A whole PRD is /graphban-wave.
 ---
 
 # Delegating a Graphban item
@@ -197,6 +201,5 @@ So a delegated item needs a second agent to review it. Plan for that, or the wor
 
 ## When not to use this
 
-For a whole backlog, ask the person to run `gbfleet until` instead. It runs the wave with no
-model in the loop; fanning the same work out by hand keeps your context awake for the wave's
-entire length just to poll and adjudicate.
+A whole PRD is `graphban-wave`. It runs `gbfleet until` for that PRD. Fanning the items out
+from here keeps a frontier context polling for the wave's whole length.

graphban_cli-0.8.2/src/gban/skills/graphban-grill/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: graphban-grill
+description: >
+  Settle a Graphban PRD grill from the product why and the PRD's intent.
+  Auto-record answers the context already decides, and ask the user only
+  the questions it does not. Use when grilling a PRD, running a grill,
+  answer_grill, or when the user runs /graphban-grill.
+user-invocable: true
+---
+
+# Grill
+
+`grill_prd` returns questions and records nothing. An answer counts only after `answer_grill`. The grader ignores the PRD body: a decision that exists only in the document is still unanswered.
+
+## Sources
+
+Read both before you classify a question.
+
+1. `get_prd`. The intent is the framing: Problem, Goals, Non-goals, and an intent heading when the PRD has one.
+2. Why the app exists: `docs/product-overview.md` (philosophy, goals, non-goals) and `docs/design-philosophy.md`. This bounds the PRD. It does not fill a hole the PRD left open.
+
+A source decides a question only when you can quote the sentence. Memory, code, and a guess are not sources.
+
+## Split
+
+For each question, write a one- or two-sentence recommendation, then:
+
+- **accept** — that sentence already decides it, the two sources do not conflict, and the answer is words rather than a prototype. Record it.
+- **ask** — the sources are silent, they conflict, both readings are reasonable, or the question needs a prototype. These are the only questions you put to the user.
+
+Silence is ask. A fluent inference is ask. Do not accept a new boundary, a new error behavior, or a new contract field that neither source states.
+
+## Record an accept
+
+Fold the decision into the PRD with `update_prd(section=...)` first. Then `answer_grill` once, with that decision alone.
+
+One call per decision. A reply that covers several dimensions is one answer, and the grader leaves the rest outstanding.
+
+Say `deferred` only when a source already defers it. "Later" without that word stays unanswered.
+
+Read the return:
+
+- `graded: false` — stop. Say `ungraded_reason`. Do not send another answer.
+- `stalled: true` — stop. Tell the user. Three answers moved nothing.
+- `complete: true` — the grill finished and the body just froze. The fold had to happen before this call.
+- `body_absorbed: false` — the transcript is ahead of the spec. Fold the answers it names before you continue.
+
+Do not set `approved`. Finishing the grill does that.
+
+## Ask
+
+Show only the ask list. For each: the question, the recommendation, and one line on why the sources do not decide it.
+
+Record nothing from this list until the user answers. `answer_grill` with their words. Fold that section the same way, before the next call.
+
+If they accept a recommendation, the recorded answer is their acceptance of that text. The recommendation alone is not a turn.

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

@@ -0,0 +1,31 @@
+---
+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`, `stale`, `tool_missing`, `not_applicable`, `incomplete`, or `not_computable`.
+3. Run the scanner. `record_scan` needs `scanner_id`, `path`, and `scanned_sha`.
+   - Send `result`, one of four:
+     - `complete`: the scanner finished. `findings: []` is then clean at that SHA.
+     - `tool_missing`: the scanner is not installed. Not clean; it stays due.
+     - `not_applicable`: the scanner does not apply here. It stops being due.
+     - `incomplete`: output without a finish. Send the findings it produced; it stays due.
+   - `findings: []` without `result: complete` is refused and nothing is stored. An empty list alone is not a clean scan.
+   - Every result needs `scanned_sha`, so it goes stale when HEAD moves.
+   - The same `scanner_id` and path keeps the previous rows. The newest is the cell.
+   - 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.
+   - Send the grain a person acts on (GRPH-1127). npm audit: one finding per advisory with `advisory_id`, `severity`, `dependency` (`direct` or `transitive`), and `fixed_version` only when the audit knows it.
+   - knip: unused exports are ONE finding with `kind: unused_export`, `count`, severity `info`; unused types are one with `kind: unused_type`. Unused files and undeclared imports stay one finding each, with a `path`. The server stores what you send; it never splits or merges.
+
+A clean row is not a tracker item. A finding that already names `link_ref` points at work that exists.

graphban_cli-0.8.2/src/gban/skills/graphban-wave/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: graphban-wave
+description: >
+  Drain one grilled PRD with gbfleet until: build, review, and merge until
+  that PRD has nothing ready. Use when running a wave, spawning a wave for a
+  PRD, looping until the PRD is done, or when the user runs /graphban-wave.
+  One item is /graphban-delegation. Decompose is /graphban-prd.
+user-invocable: true
+---
+
+# Drain a PRD
+
+One command runs the cycle. Do not spawn the items. Do not stay in the loop.
+
+## Before
+
+`prd_coverage` for this PRD.
+
+`gaps` or `shaped: false` — stop. Filing the tasks is `graphban-prd`. Do not `decompose_prd` here. An idle drain is not a finished PRD.
+
+Coverage has tasks — continue.
+
+## Dry run
+
+Same flags as the real run, plus `--dry-run`. It mints nothing.
+
+```bash
+gbfleet until --repo . --server <url> --project <id> --adapter <vendor> \
+  --prd <prd_id> --merge \
+  --tier cheap=<adapter[:model]> --tier frontier=<adapter[:model]> \
+  --dry-run
+```
+
+`--prd` is required. Without it the loop drains every ready item in the project. `backlog` is claimable, so parking work there does not scope the wave. `--prd` refuses a pre-minted seats file.
+
+Read the dry run before installing. Held clusters name who holds them. `predicted: true` is a lower-confidence grouping. A plan for the wrong PRD is a stop.
+
+A backend change whose acceptance is the Postgres suite needs `--allow psql` on both the dry run and the install.
+
+## Run
+
+Drop `--dry-run` and hand the process to the machine. This session ending must not kill it.
+
+```bash
+gbfleet service install --name <prd_id> -- --repo . --server <url> --project <id> \
+  --adapter <vendor> --prd <prd_id> --merge \
+  --tier cheap=<adapter[:model]> --tier frontier=<adapter[:model]>
+```
+
+`--tier` is what a tier means on this machine. Omit a tier the Fleet tier map already pins. `--request cheap` or `--request frontier` forces every delegation to that tier. The default follows each item's brief. Do not pick a model per item.
+
+A service already installed under that name: `gbfleet service status --name <prd_id>` and leave it. A second `until` on the same repo mints another child onto the same cluster.
+
+`gbfleet service status` prints the PATH the unit captured. An empty PATH is a drain that will not find the adapter. The API key is the one already stored for this repo. Do not print it, and do not pass a new one.
+
+## While it runs
+
+Status is `gbfleet service status --name <prd_id>`. The ledger is `fleet_status`. Do not attach a spawn watcher, and do not spawn a replacement.
+
+`until` is idle when that PRD has nothing ready, nothing unsigned, and no live lease. `WAVE_IDLE` while items are still `next`, or held in review, is not done.
+
+`review-unsigned` can be a review row outside this PRD. Say which item. Do not start another drain over it, and do not `sign_off` it yourself.
+
+`--merge` lands the pull requests this wave opened. Leave every other open pull request. A salvage branch can be the only copy of the work.