Reorg: split HTTP surface into egress vs typed-operation shapes; document front-selection rule #115

New issue

Closed

opened 2026-06-08 00:03:43 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-06-08 00:03:43 +00:00

Owner

Reorg: the HTTP surface is two shapes; name both, and document the front-selection rule

Follow-up to cli-guard issue 113.
The proposed HTTP bucket lumps egress with specverb/guardfile/specgen/
specdrv/respfmt. Weighing the real top integrations shows those are two
different shapes that deserve separate naming.

The two HTTP shapes

egress / allowlist (egress, the CONNECT-proxy concern) - "what hosts may
this send to." Serves the otel stack (datadog/honeycomb/new relic, all
otel-wrapped) and package-manager registry fetches. The broader HTTP shape by
usage.
typed-operation guard (guardfile/specverb/specgen/specdrv + the
Overlay) - "may this caller invoke this operation." Serves ~forgejo.

The front-selection rule (worth writing into architecture.md)

The surface that guards an integration is chosen by CLI maturity, not OpenAPI
availability. Several top integrations ship an OpenAPI spec and we still guard
the CLI: gh/GitHub, kubectl/k8s, az/Azure. Forgejo is on the HTTP front
because it has no good CLI, not because it has a spec. Consequence: the
typed-operation HTTP front stays small by construction, since most platforms
ship a CLI.

Usage tally backing this:

CLI passthrough (~13): gh, aws, brew, kubectl, git, tailscale, gcloud, az,
uv, npm, cargo, go, ssh.
HTTP typed-operation (~1): forgejo (trello weakly).
HTTP egress: otel stack + registry fetches.
MCP: mcporter.

`gh*cache` placement

ghcache/ghidcache/ghratelimit are proposed under HTTP, but GitHub is
guarded via the gh CLI passthrough. If those caches back gh operations
they belong with CLI, not HTTP - unless cli-guard makes direct GitHub HTTP calls
independent of gh (rate-limit / id resolution). Pin this down before the move.

Ask

Name the HTTP sub-shapes explicitly in the tree (e.g. http/egress,
http/spec) rather than one flat http/.
Add the front-selection rule to the docs/architecture.md that
cli-guard issue 113
item 3 proposes.
Resolve gh*cache ownership.

## Reorg: the HTTP surface is two shapes; name both, and document the front-selection rule Follow-up to [cli-guard issue 113](https://forgejo.coilysiren.me/coilyco-flight-deck/cli-guard/issues/113). The proposed HTTP bucket lumps `egress` with `specverb`/`guardfile`/`specgen`/ `specdrv`/`respfmt`. Weighing the real top integrations shows those are two different shapes that deserve separate naming. ### The two HTTP shapes * **egress / allowlist** (`egress`, the CONNECT-proxy concern) - "what hosts may this send to." Serves the otel stack (datadog/honeycomb/new relic, all otel-wrapped) and package-manager registry fetches. The broader HTTP shape by usage. * **typed-operation guard** (`guardfile`/`specverb`/`specgen`/`specdrv` + the Overlay) - "may this caller invoke this operation." Serves ~`forgejo`. ### The front-selection rule (worth writing into architecture.md) The surface that guards an integration is chosen by **CLI maturity, not OpenAPI availability**. Several top integrations ship an OpenAPI spec and we still guard the CLI: `gh`/GitHub, `kubectl`/k8s, `az`/Azure. Forgejo is on the HTTP front because it has *no* good CLI, not because it has a spec. Consequence: the typed-operation HTTP front stays small by construction, since most platforms ship a CLI. Usage tally backing this: - **CLI passthrough** (~13): gh, aws, brew, kubectl, git, tailscale, gcloud, az, uv, npm, cargo, go, ssh. - **HTTP typed-operation** (~1): forgejo (trello weakly). - **HTTP egress**: otel stack + registry fetches. - **MCP**: mcporter. ### `gh*cache` placement `ghcache`/`ghidcache`/`ghratelimit` are proposed under HTTP, but GitHub is guarded via the `gh` **CLI passthrough**. If those caches back `gh` operations they belong with CLI, not HTTP - unless cli-guard makes direct GitHub HTTP calls independent of `gh` (rate-limit / id resolution). Pin this down before the move. ### Ask - Name the HTTP sub-shapes explicitly in the tree (e.g. `http/egress`, `http/spec`) rather than one flat `http/`. - Add the front-selection rule to the `docs/architecture.md` that [cli-guard issue 113](https://forgejo.coilysiren.me/coilyco-flight-deck/cli-guard/issues/113) item 3 proposes. - Resolve `gh*cache` ownership.

coilysiren added the

label

2026-06-17 07:05:22 +00:00

coilysiren commented

2026-06-17 08:23:18 +00:00

Author

Owner

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: burndown-2026-06.

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: `burndown-2026-06`.

coilysiren

2026-06-17 08:23:18 +00:00