Tyler J King
061e2206ea
Documents the 2 crates (gsh binary + libgsh library), the GSH_* env-var contract that bascule sets and forge-fuse reads (Phase 3 shell-IS-session), the cross-workspace dependency on forge-core::CorpusCapabilityCeiling for the runtime three-way intersection, and the local dev-environment/ playbook for the WSL2 + Bascule + Hetzner Keycloak + Entra federation flow. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Tyler J King <tking@guildhouse.dev>
51 lines
2.1 KiB
Markdown
51 lines
2.1 KiB
Markdown
# CLAUDE.md — gsh
|
|
|
|
The governed shell. Operator-facing CLI that bascule launches after
|
|
OIDC → DID derivation; the binary that consumes `GSH_*` env vars,
|
|
loads the AC, validates the corpus, and runs governed commands.
|
|
Substrate-level (carries the Guildhouse brand intentionally per
|
|
`TODO.md` Layout Principle).
|
|
|
|
## Crates
|
|
|
|
- **gsh** — The governed shell binary itself (`GCAP-SPEC-SHELLBOUND-
|
|
SDK-0001`). Consumes `GSH_DID`, `GSH_ACCORD_HASH`, `GSH_SHELL_CLASS`,
|
|
`GSH_POSTURE_LEVEL`, `GSH_CAPABILITY_SET` from bascule + propagates
|
|
to subprocesses via `org-ops-core::context::GshContext` headers.
|
|
- **libgsh** — Library: AC validation, capability-request building,
|
|
corpus gate. The shell binary's reusable surface.
|
|
|
|
## Cross-workspace dependencies
|
|
|
|
**Consumes:** `guildhouse-did` (Did parsing/derivation),
|
|
`bascule-workspace/bascule-core` (`AuthorizationContext` shape),
|
|
`org-ops-core` (env-var contract for child-process governance
|
|
threading), `forge-core::shell_context` (re-exported
|
|
`CorpusCapabilityCeiling` for runtime intersection).
|
|
|
|
**Consumed by:** the operator's interactive session — invoked by
|
|
bascule-shell after OIDC auth, by `dev-environment/bascule-local.toml`
|
|
locally on WSL2.
|
|
|
|
## Build / Test
|
|
|
|
```bash
|
|
CARGO_TARGET_DIR=target-tking cargo build --workspace
|
|
CARGO_TARGET_DIR=target-tking cargo test --workspace
|
|
```
|
|
|
|
## Architectural notes
|
|
|
|
- **`GSH_*` env contract** is the load-bearing interop with bascule
|
|
(which sets them) and forge-fuse (which reads them via
|
|
`forge-fuse::ShellContext::from_env`). The contract:
|
|
`GSH_DID`, `GSH_ACCORD_HASH`, `GSH_SHELL_CLASS=Application|System`,
|
|
`GSH_POSTURE_LEVEL` (1..=5 DEFCON), `GSH_CAPABILITY_SET` (hex
|
|
bitmask `0x{:08x}`).
|
|
- **Phase 3 forge-fuse (shell-IS-session)** consumes these env vars
|
|
to compute the per-mount effective capability via
|
|
`manifest_cap ∩ shell_cap ∩ corpus_cap`.
|
|
- **Local dev environment** at `dev-environment/` shows the WSL2 +
|
|
Bascule + gsh + Hetzner Keycloak + Entra federation flow end-to-end.
|
|
- The brand-bound `gsh` name (vs a `substrate-shell`) is preserved
|
|
intentionally — revisit when the substrate brand solidifies.
|