go

module

v0.0.0-...-ba2b7b8 Latest Latest Go to latest Published: Jul 29, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/eshu-hq/eshu

Links

Open Source Insights

README ¶

Go Runtime

The Go module owns the Eshu runtime: CLI, API, MCP server, ingester, reducer, workflow coordinator, local owner mode, storage adapters, parser support, and query surfaces.

Use Local Testing for the focused gate that matches the surface you touched. The root README and local runbooks show install paths for users; this directory is for maintainers working on the runtime.

Where to read next

This directory is the Go module root. Two children carry the actual code and the rich documentation:

go/cmd/ — every Eshu binary, with per-binary README.md, doc.go, and scoped AGENTS.md.
go/internal/ — every internal package, with per-package README.md, doc.go, and scoped AGENTS.md.

Open go/cmd/README.md for the binary-to-runtime map and go/internal/README.md for the internal-package layout diagram and the where-to-start-by-intent table.

Pipeline at a glance

flowchart LR
  source[git source] --> collector
  collector --> parser
  parser --> facts[(facts)]
  facts --> projector
  projector --> reducer
  projector --> cypher
  reducer --> cypher
  cypher --> graph[(graph backend)]
  facts --> postgres[(postgres)]
  api --> graph
  api --> postgres
  mcp[mcp-server] --> api

Per-package documentation convention

Every Go package directory under go/ carries three docs with separate jobs:

doc.go for the godoc contract.
README.md for the architectural and operational lens humans read.
AGENTS.md for scoped instructions that Codex and other coding-agent harnesses load while editing that package tree.

The eshu-folder-doc-keeper skill at .agents/skills/ defines the writing standards. The drift checker at scripts/check-docs-stale.sh warns when source moves under a stale README/doc.go pair. The slop gate at scripts/verify-doc-claims.sh confirms every backticked Go identifier appears in source and every file:line cite resolves correctly.

Dependencies

This is the Go module root, not a Go package. Internal package boundaries are documented under go/internal/*/README.md and go/internal/*/doc.go.

Telemetry

The runtime telemetry contract is owned by internal/telemetry. All runtime-affecting packages route metrics, spans, and structured logs through that contract.

docs/public/architecture.md
docs/public/deployment/service-runtimes.md
docs/public/reference/local-testing.md

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
admin-status command Package main runs the admin-status binary, which renders the shared Eshu status report from Postgres for local CLI inspection.	Package main runs the admin-status binary, which renders the shared Eshu status report from Postgres for local CLI inspection.
api command Package main runs the eshu-api binary, which serves the Eshu HTTP query and admin surface backed by the configured graph backend and Postgres content store.	Package main runs the eshu-api binary, which serves the Eshu HTTP query and admin surface backed by the configured graph backend and Postgres content store.
audit-preflight command Command audit-preflight validates a competitive-audit issue body against the Eshu preflight contract.	Command audit-preflight validates a competitive-audit issue body against the Eshu preflight contract.
bootstrap-data-plane command Package main runs the eshu-bootstrap-data-plane binary, which applies the Eshu Postgres and graph-backend schema DDL and exits.	Package main runs the eshu-bootstrap-data-plane binary, which applies the Eshu Postgres and graph-backend schema DDL and exits.
bootstrap-index command Package main runs the eshu-bootstrap-index binary, which performs a one-shot end-to-end indexing pass: collection, source-local projection, relationship-evidence backfill, IaC reachability materialization, deployment-mapping reopen, and config_state_drift intent enqueue (Phase 3.5 trigger for the reducer's Terraform drift handler).	Package main runs the eshu-bootstrap-index binary, which performs a one-shot end-to-end indexing pass: collection, source-local projection, relationship-evidence backfill, IaC reachability materialization, deployment-mapping reopen, and config_state_drift intent enqueue (Phase 3.5 trigger for the reducer's Terraform drift handler).
capability-inventory command Command capability-inventory generates and verifies the reconciled Eshu capability catalog artifact.	Command capability-inventory generates and verifies the reconciled Eshu capability catalog artifact.
ci-gates command Command ci-gates is the CLI for the CI gate registry (#4213).	Command ci-gates is the CLI for the CI gate registry (#4213).
collector-aws-cloud command Command collector-aws-cloud runs the AWS cloud collector.	Command collector-aws-cloud runs the AWS cloud collector.
collector-azure-cloud command Command collector-azure-cloud runs the Azure cloud collector runtime in either fixture or claimed-live mode.	Command collector-azure-cloud runs the Azure cloud collector runtime in either fixture or claimed-live mode.
collector-cicd-run command Package main provides the hosted CI/CD run collector command.	Package main provides the hosted CI/CD run collector command.
collector-component-extension command Package main wires the component extension collector worker.	Package main wires the component extension collector worker.
collector-confluence command Package main wires the Confluence documentation collector binary.	Package main wires the Confluence documentation collector binary.
collector-gcp-cloud command Command collector-gcp-cloud runs the GCP Cloud Asset Inventory collector.	Command collector-gcp-cloud runs the GCP Cloud Asset Inventory collector.
collector-git command Package main runs the collector-git binary, the local verification runtime for native Go repository selection, sync, snapshot collection, content shaping, and fact commit into Postgres.	Package main runs the collector-git binary, the local verification runtime for native Go repository selection, sync, snapshot collection, content shaping, and fact commit into Postgres.
collector-grafana command Command collector-grafana runs the claim-driven live Grafana metadata collector.	Command collector-grafana runs the claim-driven live Grafana metadata collector.
collector-jira command Command collector-jira runs the claim-driven Jira work-item evidence collector.	Command collector-jira runs the claim-driven Jira work-item evidence collector.
collector-kubernetes-live command Package main wires the Kubernetes live collector binary.	Package main wires the Kubernetes live collector binary.
collector-loki command Command collector-loki runs the claim-driven live Loki metadata collector.	Command collector-loki runs the claim-driven live Loki metadata collector.
collector-oci-registry command Package main wires the OCI registry collector binary.	Package main wires the OCI registry collector binary.
collector-package-registry command Command collector-package-registry runs the claim-aware package-registry collector.	Command collector-package-registry runs the claim-aware package-registry collector.
collector-pagerduty command Command collector-pagerduty runs the hosted PagerDuty incident-context and optional live-configuration collector through workflow claims.	Command collector-pagerduty runs the hosted PagerDuty incident-context and optional live-configuration collector through workflow claims.
collector-prometheus-mimir command Command collector-prometheus-mimir runs the claim-driven live Prometheus and Mimir metadata collector.	Command collector-prometheus-mimir runs the claim-driven live Prometheus and Mimir metadata collector.
collector-sbom-attestation command Command collector-sbom-attestation runs the hosted SBOM and attestation collector as a claim-driven service.	Command collector-sbom-attestation runs the hosted SBOM and attestation collector as a claim-driven service.
collector-security-alerts command Command collector-security-alerts runs the hosted provider security-alert collector through workflow claims and records bounded commit-failure dead-letter evidence for operator replay status.	Command collector-security-alerts runs the hosted provider security-alert collector through workflow claims and records bounded commit-failure dead-letter evidence for operator replay status.
collector-tempo command Command collector-tempo runs the claim-driven live Tempo metadata collector.	Command collector-tempo runs the claim-driven live Tempo metadata collector.
collector-terraform-state command Package main hosts the Terraform-state collector runtime.	Package main hosts the Terraform-state collector runtime.
collector-vault-live command Command collector-vault-live runs the read-only, metadata-only Vault collector for the secrets/IAM posture lane (#25, #1356).	Command collector-vault-live runs the read-only, metadata-only Vault collector for the secrets/IAM posture lane (#25, #1356).
collector-vulnerability-intelligence command Command collector-vulnerability-intelligence runs the hosted vulnerability intelligence collector.	Command collector-vulnerability-intelligence runs the hosted vulnerability intelligence collector.
eshu command Package main runs the eshu binary, the unified Cobra-based CLI and MCP/API launcher for Eshu.	Package main runs the eshu binary, the unified Cobra-based CLI and MCP/API launcher for Eshu.
fact-envelope-adapter command Command fact-envelope-adapter generates the shared fact-envelope adapter.	Command fact-envelope-adapter generates the shared fact-envelope adapter.
fact-kind-registry command Command fact-kind-registry generates the core fact-kind registry contract.	Command fact-kind-registry generates the core fact-kind registry contract.
factschema-diff command Command factschema-diff is the contracts schema-diff breaking-change gate (Contract System v1 §6 enforcement gate 1).	Command factschema-diff is the contracts schema-diff breaking-change gate (Contract System v1 §6 enforcement gate 1).
golden-corpus-gate command Command golden-corpus-gate is the typed assertion step of the B-7 golden end-to-end corpus gate (issue #3800).	Command golden-corpus-gate is the typed assertion step of the B-7 golden end-to-end corpus gate (issue #3800).
heredoc-budget command Command heredoc-budget is a static lint gate that flags oversized shell heredoc bodies before they can deadlock a developer's `make pre-pr` run.	Command heredoc-budget is a static lint gate that flags oversized shell heredoc bodies before they can deadlock a developer's `make pre-pr` run.
ifa command Command ifa is the CLI entry point for Eshu's Ifá conformance platform.	Command ifa is the CLI entry point for Eshu's Ifá conformance platform.
ingester command Package main runs the eshu-ingester binary, the long-running runtime that owns repository sync, parsing, fact emission, and source-local projection into the configured graph backend.	Package main runs the eshu-ingester binary, the long-running runtime that owns repository sync, parsing, fact emission, and source-local projection into the configured graph backend.
mcp-server command Package main runs the eshu-mcp-server binary, which serves the Eshu MCP tool transport over stdio or HTTP backed by the same query and content stores as the HTTP API.	Package main runs the eshu-mcp-server binary, which serves the Eshu MCP tool transport over stdio or HTTP backed by the same query and content stores as the HTTP API.
mock-github command Package main runs the mock-github binary, a minimal, self-contained stand-in for github.com's OAuth2 web-application-flow and REST identity endpoints, used only by the F-9 (issue #5170) auth-mcp E2E stack to prove Eshu's go/internal/githublogin connector end-to-end without depending on a live GitHub App or GitHub Enterprise Server instance.	Package main runs the mock-github binary, a minimal, self-contained stand-in for github.com's OAuth2 web-application-flow and REST identity endpoints, used only by the F-9 (issue #5170) auth-mcp E2E stack to prove Eshu's go/internal/githublogin connector end-to-end without depending on a live GitHub App or GitHub Enterprise Server instance.
mock-oidc-idp command Package main runs the mock-oidc-idp binary, a minimal, self-contained OpenID Connect Authorization Code identity provider used only by local and CI browser-auth E2E suites (issue #4971, epic #4962) to prove Eshu's SSO login flow against a real OIDC counterparty without depending on a live third-party IdP.	Package main runs the mock-oidc-idp binary, a minimal, self-contained OpenID Connect Authorization Code identity provider used only by local and CI browser-auth E2E suites (issue #4971, epic #4962) to prove Eshu's SSO login flow against a real OIDC counterparty without depending on a live third-party IdP.