generated from coulomb/repo-seed
tegwick
cbcd097214
Some checks failed
ci / validate-registry (push) Has been cancelled
Use reuse.coulomb.social, REUSE_SURFACE_URL/TOKEN env vars, reuse-surface image and reuse-surface-env secret. Replace reuse-surface-hub entrypoint with reuse-surface serve; CLI uses --base-url.
131 lines
3.2 KiB
Markdown
131 lines
3.2 KiB
Markdown
# Registry Tools
|
|
|
|
CLI tooling for the capability registry, implemented in `reuse_surface/`.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
.venv/bin/pip install -e .
|
|
```
|
|
|
|
## Commands
|
|
|
|
### validate
|
|
|
|
Validate one entry or the full registry against `schemas/capability.schema.yaml`
|
|
and warn on index drift.
|
|
|
|
```bash
|
|
reuse-surface validate
|
|
reuse-surface validate registry/capabilities/capability.registry.register.md
|
|
```
|
|
|
|
### query
|
|
|
|
Filter the capability index by maturity, tags, domain, consumption mode, or keyword.
|
|
|
|
```bash
|
|
reuse-surface query --discovery-min D4
|
|
reuse-surface query --availability-min A3
|
|
reuse-surface query --tag identity
|
|
reuse-surface query --consumption-mode cli
|
|
reuse-surface query --keyword rollout
|
|
```
|
|
|
|
### export
|
|
|
|
Export a machine-readable bundle combining index rows and parsed entry front matter.
|
|
|
|
```bash
|
|
reuse-surface export
|
|
reuse-surface export --format json
|
|
```
|
|
|
|
### overlaps
|
|
|
|
Detect potential duplicate or overlapping capabilities (UC-RS-015).
|
|
|
|
```bash
|
|
reuse-surface overlaps
|
|
reuse-surface overlaps --threshold 0.35
|
|
```
|
|
|
|
### catalog
|
|
|
|
Generate human-readable catalog artifacts (UC-RS-018).
|
|
|
|
```bash
|
|
reuse-surface catalog
|
|
```
|
|
|
|
Writes `docs/CapabilityCatalog.md`, `docs/catalog/index.html`,
|
|
`docs/catalog/registry.json`, and `docs/catalog/search.html`.
|
|
|
|
### federation compose
|
|
|
|
Compose a federated index from `registry/federation/sources.yaml`.
|
|
|
|
```bash
|
|
reuse-surface federation compose
|
|
reuse-surface federation compose --refresh
|
|
```
|
|
|
|
Composes local and remote HTTP index sources. Writes
|
|
`registry/indexes/federated.yaml` with `source_repo` attribution. Remote indexes
|
|
cache under `registry/federation/cache/`.
|
|
|
|
### graph
|
|
|
|
Generate a Mermaid relation graph from capability entry relations.
|
|
|
|
```bash
|
|
reuse-surface graph
|
|
reuse-surface graph --check
|
|
reuse-surface graph --stdout
|
|
```
|
|
|
|
Writes `docs/graph/capability-graph.mmd` and `docs/graph/index.html`.
|
|
|
|
### hub
|
|
|
|
Client for the federation hub service (REUSE-WP-0011).
|
|
|
|
```bash
|
|
export REUSE_SURFACE_URL=https://reuse.coulomb.social
|
|
export REUSE_SURFACE_TOKEN=<write-token>
|
|
reuse-surface hub status
|
|
reuse-surface hub list
|
|
reuse-surface hub register --repo state-hub --url https://.../capabilities.yaml
|
|
reuse-surface hub update --repo state-hub --enabled true
|
|
```
|
|
|
|
Run the service locally: `REUSE_SURFACE_TOKEN=dev-token reuse-surface serve`
|
|
|
|
## Export format
|
|
|
|
The export bundle includes:
|
|
|
|
- `version`, `domain`, `updated` from the index
|
|
- `capabilities[]` with `{ index, entry }` pairs
|
|
|
|
Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019).
|
|
|
|
## Workflows
|
|
|
|
| Workflow | Command |
|
|
|---|---|
|
|
| Add capability | template + index update + `reuse-surface validate` |
|
|
| Discover capabilities | `reuse-surface query` or read the index |
|
|
| Validate entry shape | `reuse-surface validate` |
|
|
| Export for agents | `reuse-surface export --format json` |
|
|
| Detect overlap | `reuse-surface overlaps` |
|
|
| Publish catalog | `reuse-surface catalog` |
|
|
| Compose federation | `reuse-surface federation compose` |
|
|
| Relation graph | `reuse-surface graph` |
|
|
|
|
## Related use cases
|
|
|
|
- UC-RS-013 — Use registry metadata in agentic coding
|
|
- UC-RS-019 — Publish a machine-readable registry export
|
|
- UC-RS-023 — Validate registry entries against schema |