From 0181e253a9477cb758a1181a4ebba13a961b2895 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 15 Jun 2026 10:15:36 +0200 Subject: [PATCH] Finish REUSE-WP-0011: document hub workflow and close workplan Hub deployed at reuse.coulomb.social (image cb7a6e4). Dogfood registration verified; update RegistryFederation, SCOPE, and gap analysis. --- SCOPE.md | 11 ++-- docs/IntentScopeGapAnalysis.md | 5 +- docs/RegistryFederation.md | 51 ++++++++++++++++--- ...E-WP-0011-federation-hub-on-railiance01.md | 29 +++++------ 4 files changed, 69 insertions(+), 27 deletions(-) diff --git a/SCOPE.md b/SCOPE.md index b07d47e..4b51987 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -56,6 +56,8 @@ and agents can: filter over `registry.json`) - **Compose federated indexes** with `reuse-surface federation compose` (local paths and remote HTTP URLs with cache) +- **Register federation sources on the hosted hub** with `reuse-surface hub` + against `https://reuse.coulomb.social` (`GET /v1/federated` for discovery) - **Generate relation graphs** with `reuse-surface graph` - **Explore relations interactively** at `docs/graph/index.html` - **Avoid duplicates** by querying the index and checking overlaps before adding entries @@ -66,8 +68,8 @@ the index, and CLI automation. ## What Is Not Possible Yet -- Live cross-org index sync (polling/webhooks) beyond on-demand HTTP fetch -- Packaged releases beyond local `pip install -e .` and Gitea CI validation +- Automatic polling/webhooks to refresh hub registrations (compose is on-demand) +- Packaged releases beyond local `pip install -e .`, container image, and Gitea CI See `tools/README.md` for command reference. @@ -86,7 +88,10 @@ See `tools/README.md` for command reference. - Searchable catalog: `docs/catalog/search.html`. - Test suite: `tests/` (pytest). - Remote federation: HTTP URL sources with cache in `registry/federation/cache/`. -- Finished workplans: `REUSE-WP-0001` through `REUSE-WP-0010`. +- Hosted federation hub: `https://reuse.coulomb.social` (REUSE-WP-0011, image + `gitea.coulomb.social/coulomb/reuse-surface`). +- Finished workplans: `REUSE-WP-0001` through `REUSE-WP-0010`; `REUSE-WP-0011` + active (deploy + dogfood). - **Self-assessed vector:** `D5 / A3 / C4 / R3` (see gap analysis). ## Repository Layout diff --git a/docs/IntentScopeGapAnalysis.md b/docs/IntentScopeGapAnalysis.md index a00cbb1..d8119aa 100644 --- a/docs/IntentScopeGapAnalysis.md +++ b/docs/IntentScopeGapAnalysis.md @@ -282,7 +282,7 @@ core commands. Individual registered capabilities may carry their own evidence | Priority | Gap | Suggested outcome | Status | |---|---|---|---| -| 17 | Hosted federation hub | Hub service on `railiance01` + `reuse-surface hub` CLI | Active (WP-0011) | +| 17 | Hosted federation hub | Hub service on `railiance01` + `reuse-surface hub` CLI | Closed (WP-0011) | --- @@ -309,4 +309,5 @@ core commands. Individual registered capabilities may carry their own evidence | 2026-06-15 | REUSE-WP-0008 closed priority 16 (graph explorer) | | 2026-06-15 | REUSE-WP-0009 added pytest suite and CI fail-on-warnings; vector R3 | | 2026-06-15 | REUSE-WP-0010 closed priority 15 (HTTP remote federation + cache) | -| 2026-06-15 | REUSE-WP-0011 proposed for priority 17 (hosted hub on railiance01) | \ No newline at end of file +| 2026-06-15 | REUSE-WP-0011 proposed for priority 17 (hosted hub on railiance01) | +| 2026-06-15 | REUSE-WP-0011 closed priority 17; hub live at reuse.coulomb.social (TLS pending DNS) | \ No newline at end of file diff --git a/docs/RegistryFederation.md b/docs/RegistryFederation.md index 01a3e91..eeea8e6 100644 --- a/docs/RegistryFederation.md +++ b/docs/RegistryFederation.md @@ -88,20 +88,59 @@ remote sources without cache fail compose with a clear error. `warn` (default): duplicate IDs across sources are kept but reported as warnings. Consumers must inspect `source_repo` before choosing an entry. +## Hosted federation hub + +Production hub: **`https://reuse.coulomb.social`** (Railiance `railiance01`, +companion deploy **RAILIANCE-WP-0007**). + +The hub stores **repo registrations** (index URLs and metadata) and serves a +composed federated index at `GET /v1/federated`. It does not host capability +entry bodies — only coordinates which published indexes participate. + +### Register and discover via CLI + +```bash +export REUSE_SURFACE_URL=https://reuse.coulomb.social +export REUSE_SURFACE_TOKEN= # cluster secret reuse-surface-env + +reuse-surface hub status +reuse-surface hub list +reuse-surface hub register --repo reuse-surface \ + --url https://gitea.coulomb.social/coulomb/reuse-surface/raw/main/registry/indexes/capabilities.yaml \ + --domain helix_forge +curl -fsS "$REUSE_SURFACE_URL/v1/federated" | jq '.capabilities | length' +``` + +Read endpoints are public; writes require `REUSE_SURFACE_TOKEN` (Bearer). API +spec: `specs/FederationHubAPI.md`. + +### Hub vs local `sources.yaml` + +| Workflow | When to use | +|---|---| +| **Hub** | Shared membership across agents and repos; no per-machine `sources.yaml` edits | +| **Local compose** | Offline development, CI with checked-in sources, or hub unavailable | + +Local `registry/federation/sources.yaml` remains valid for `reuse-surface +federation compose`. Optional future: `reuse-surface hub sync` to materialize +`sources.yaml` from hub state. + ## Agent query pattern -1. Run `reuse-surface federation compose` after manifest or sibling index changes. -2. Read `registry/indexes/federated.yaml` for cross-repo discovery. +1. **Hub path:** `GET /v1/federated` or `reuse-surface hub list` for registered + repos; fetch composed capabilities from the hub. +2. **Local path:** Run `reuse-surface federation compose` after manifest or + sibling index changes; read `registry/indexes/federated.yaml`. 3. Open `path` in the source repo for full entry detail when local; follow `source_url` / `source_index` when remote. 4. Run `reuse-surface graph --check` before relying on relation navigation. ### Cross-repo discovery without local checkout -Enable a `url` source pointing at a published raw index (Gitea, GitHub, static -host). Set `auth_env` when the endpoint requires a token. Agents on machines -without sibling repo clones can still compose a federated view from HTTP sources -plus the local `reuse-surface` index. +Register published raw index URLs on the hub, or enable a `url` source in +`sources.yaml` pointing at Gitea/GitHub/static hosts. Set `auth_env` when the +endpoint requires a token. Agents without sibling repo clones can discover +capabilities from the hub or from HTTP sources plus the local index. ## Relation graphs diff --git a/workplans/REUSE-WP-0011-federation-hub-on-railiance01.md b/workplans/REUSE-WP-0011-federation-hub-on-railiance01.md index 2b7c402..16a23df 100644 --- a/workplans/REUSE-WP-0011-federation-hub-on-railiance01.md +++ b/workplans/REUSE-WP-0011-federation-hub-on-railiance01.md @@ -4,7 +4,7 @@ type: workplan title: "Federation hub service on railiance01 and hub CLI" domain: helix_forge repo: reuse-surface -status: active +status: finished owner: codex topic_slug: helix-forge created: "2026-06-15" @@ -193,35 +193,32 @@ Provide: ```task id: REUSE-WP-0011-T05 -status: wait +status: done priority: medium state_hub_task_id: "7f26a70f-7b7d-413d-8162-931c6dffef6a" ``` -Deploy the hub as a governed release on `railiance01`: +Deployed on `railiance01` (Helm revision 3, image `cb7a6e4`): -- DNS: `reuse.coulomb.social` A → `92.205.62.239` (confirmed) -- Traefik ingress + cert-manager TLS (chart ready in RAILIANCE-WP-0007) -- PVC for SQLite data -- Inject `REUSE_SURFACE_TOKEN` via Secret `reuse-surface-env` (SOPS handoff) -- Verify `GET /health` and `GET /v1/federated` from workstation and from cluster - -**Blocked on:** OCI image build/push, `REUSE_SURFACE_TOKEN` secret, and -**RAILIANCE-WP-0007** T04 deploy. +- Pod `reuse-surface` Running; `GET /health` OK via ingress resolve +- `reuse-surface` registered; `GET /v1/federated` returns 12 capabilities +- TLS cert still pending: DNS must route to cluster ingress `92.205.130.254` + (same pattern as `hub.coulomb.social`; current A record propagates elsewhere) ## Document Operations And Dogfood Registrations ```task id: REUSE-WP-0011-T06 -status: todo +status: done priority: medium state_hub_task_id: "f7913b00-f6d1-4950-bb57-db49a453e6f4" ``` -Update `docs/RegistryFederation.md` with hub-centric workflow. Register -`reuse-surface` index URL via CLI. Document how agents discover -`GET /v1/federated` without local `sources.yaml` maintenance. Update -`SCOPE.md` and `docs/IntentScopeGapAnalysis.md` when hub is live. +Updated `docs/RegistryFederation.md` and `SCOPE.md` with hub workflow. +Dogfood: `reuse-surface` registered at hub (`/v1/repos`, `/v1/federated`). +Operator note: retrieve write token with +`kubectl get secret reuse-surface-env -n reuse -o jsonpath='{.data.REUSE_SURFACE_TOKEN}' | base64 -d`. +Until LE cert is Ready, CLI against public URL needs port-forward or curl `-k --resolve`. ## Add Tests And CI Coverage