generated from coulomb/repo-seed
136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
# Repository Ability Registry
|
|
|
|
The Repository Ability Registry maps repositories from usefulness to implementation:
|
|
|
|
```text
|
|
Ability -> Capability -> Feature -> Evidence -> Code location
|
|
```
|
|
|
|
The first implementation slice is a Python registry core plus FastAPI HTTP API and a small curator UI. Repository registration imports basic metadata from the repository itself, then analysis builds observed facts and candidate review entries.
|
|
|
|
## Local Development
|
|
|
|
Create an environment and install dependencies:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
. .venv/bin/activate
|
|
python -m pip install -e ".[dev]"
|
|
```
|
|
|
|
Run tests:
|
|
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
Run the API:
|
|
|
|
```bash
|
|
uvicorn repo_registry.web_api.app:app --reload
|
|
```
|
|
|
|
The API creates a local SQLite database at `var/repo-registry.sqlite3` by default.
|
|
|
|
## First API Loop
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8000/repos \
|
|
-H 'content-type: application/json' \
|
|
-d '{"url":"https://example.com/mail-router.git"}'
|
|
```
|
|
|
|
The registry imports name and description from `pyproject.toml`, `package.json`, or README where possible. Then add abilities, capabilities, features, and evidence under that repository and inspect:
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8000/repos/1/ability-map
|
|
curl 'http://127.0.0.1:8000/search?q=classify'
|
|
```
|
|
|
|
## Deterministic Analysis
|
|
|
|
For local development, repository URLs may be local filesystem paths. Git URLs, including `file://` URLs, are cloned into `var/checkouts` before scanning. Trigger a deterministic scan:
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8000/repos/1/analysis-runs \
|
|
-H 'content-type: application/json' \
|
|
-d '{}'
|
|
```
|
|
|
|
Or override the scan source path explicitly:
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8000/repos/1/analysis-runs \
|
|
-H 'content-type: application/json' \
|
|
-d '{"source_path":"/path/to/repository"}'
|
|
```
|
|
|
|
Inspect recorded facts:
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8000/repos/1/analysis-runs
|
|
curl http://127.0.0.1:8000/repos/1/analysis-runs/1
|
|
curl http://127.0.0.1:8000/repos/1/observed-facts
|
|
```
|
|
|
|
The deterministic scanner records observed facts only: languages, documentation files, examples, tests, package manifests, configuration files, framework hints, and likely API/CLI interfaces.
|
|
|
|
Each completed analysis run also creates a conservative candidate graph for review:
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8000/repos/1/analysis-runs/1/candidate-graph
|
|
```
|
|
|
|
Candidate entries are source-linked review seeds. They are not canonical registry truth until a review workflow approves them.
|
|
|
|
Approve a candidate graph into the canonical registry:
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8000/repos/1/analysis-runs/1/candidate-graph/approve \
|
|
-H 'content-type: application/json' \
|
|
-d '{"notes":"Approved first review package"}'
|
|
```
|
|
|
|
Approval copies candidate abilities, capabilities, features, and evidence into the approved registry tables, marks candidates approved, and moves the repository status to `indexed`.
|
|
|
|
## Review Workflow
|
|
|
|
Candidate graphs are meant to be corrected before publication. The API supports:
|
|
|
|
- edit candidate abilities and capabilities with `PATCH`
|
|
- reject candidate abilities, capabilities, features, and evidence
|
|
- relink capabilities under another ability
|
|
- relink features or evidence under another capability
|
|
- merge duplicate abilities, capabilities, features, or evidence
|
|
|
|
Examples are available in the generated OpenAPI docs at `/docs`.
|
|
|
|
## Agent-Facing Endpoints
|
|
|
|
The v0.1 API covers the main registration, analysis, review, search, and inspection loop:
|
|
|
|
```text
|
|
GET /repos
|
|
POST /repos
|
|
GET /repos/{id}
|
|
PATCH /repos/{id}
|
|
DELETE /repos/{id}
|
|
POST /repos/{id}/analysis-runs
|
|
GET /repos/{id}/analysis-runs
|
|
GET /repos/{id}/analysis-runs/{run_id}
|
|
GET /repos/{id}/analysis-runs/{run_id}/candidate-graph
|
|
POST /repos/{id}/analysis-runs/{run_id}/candidate-graph/approve
|
|
GET /repos/{id}/ability-map
|
|
PATCH /repos/{id}/abilities/{ability_id}
|
|
DELETE /repos/{id}/abilities/{ability_id}
|
|
PATCH /repos/{id}/capabilities/{capability_id}
|
|
DELETE /repos/{id}/capabilities/{capability_id}
|
|
PATCH /repos/{id}/features/{feature_id}
|
|
DELETE /repos/{id}/features/{feature_id}
|
|
PATCH /repos/{id}/evidence/{evidence_id}
|
|
DELETE /repos/{id}/evidence/{evidence_id}
|
|
GET /abilities
|
|
GET /capabilities
|
|
GET /search?q=...
|
|
```
|