generated from coulomb/repo-seed
tegwick
270065ff58
Some checks failed
ci / validate-registry (push) Has been cancelled
Add hub sync and report cohorts CLI commands with pytest coverage, document sibling index publish contract and hub hardening path, align INTENT layout, raise external evidence on three registry entries, and close gap priorities 19-23 (priority 18 deferred on sibling index blocks).
150 lines
3.8 KiB
Markdown
150 lines
3.8 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
|
|
reuse-surface hub sync --merge
|
|
reuse-surface hub sync --dry-run
|
|
```
|
|
|
|
Run the service locally: `REUSE_SURFACE_TOKEN=dev-token reuse-surface serve`
|
|
|
|
### report cohorts
|
|
|
|
Export capability cohorts for planning or implementation reuse decisions.
|
|
|
|
```bash
|
|
reuse-surface report cohorts
|
|
reuse-surface report cohorts --planning-min D5 --availability-max A1
|
|
reuse-surface report cohorts --implementation-min A4
|
|
reuse-surface report cohorts --format json
|
|
```
|
|
|
|
Planning preset (`--planning-min`) sets discovery minimum and defaults
|
|
`availability-max` to `A1`. Implementation preset (`--implementation-min`) sets
|
|
availability minimum. Output is Markdown (default) or JSON.
|
|
|
|
## 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` |
|
|
| Sync federation manifest from hub | `reuse-surface hub sync` |
|
|
| Planning cohort export | `reuse-surface report cohorts` |
|
|
| 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 |