generated from coulomb/repo-seed
117 lines
3.0 KiB
Markdown
117 lines
3.0 KiB
Markdown
# Guide Board Local Service API
|
|
|
|
Status: draft
|
|
Created: 2026-05-07
|
|
|
|
## Purpose
|
|
|
|
The local service API is a thin HTTP facade over the same discovery, validation,
|
|
planning, execution, and report contracts used by the CLI. It is intended for
|
|
local development, containerized operation, and future UI integration.
|
|
|
|
It does not change certification boundaries: guide-board prepares structured
|
|
evidence and assessment packages, but it does not issue certifications or audit
|
|
assurance.
|
|
|
|
## Start
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 -m guide_board serve --host 127.0.0.1 --port 8080
|
|
```
|
|
|
|
External extension repositories use the same top-level option as the CLI:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 -m guide_board \
|
|
--extension-dir ../open-cmis-tck \
|
|
serve --host 127.0.0.1 --port 8080
|
|
```
|
|
|
|
Paths supplied to request bodies are resolved relative to the configured
|
|
`--root` unless they are absolute paths.
|
|
|
|
## Endpoints
|
|
|
|
### `GET /health`
|
|
|
|
Returns service status, configured root, and in-memory job counts.
|
|
|
|
### `GET /extensions`
|
|
|
|
Lists bundled and configured external extensions using the same discovery logic
|
|
as `guide-board extensions list`.
|
|
|
|
### `POST /profiles/validate`
|
|
|
|
Validates a target or assessment profile.
|
|
|
|
```json
|
|
{
|
|
"kind": "target",
|
|
"path": "profiles/targets/sample-repository.json"
|
|
}
|
|
```
|
|
|
|
Use `"kind": "assessment"` for assessment profiles.
|
|
|
|
### `POST /assessments/plan`
|
|
|
|
Builds a run plan without starting a run.
|
|
|
|
```json
|
|
{
|
|
"target": "profiles/targets/sample-repository.json",
|
|
"assessment": "profiles/assessments/sample-noop.json"
|
|
}
|
|
```
|
|
|
|
An optional `extension_dirs` array can add request-specific external extension
|
|
locations.
|
|
|
|
### `POST /runs`
|
|
|
|
Starts an assessment run in a background thread and returns a job record.
|
|
|
|
```json
|
|
{
|
|
"target": "profiles/targets/sample-repository.json",
|
|
"assessment": "profiles/assessments/sample-noop.json",
|
|
"output_dir": "runs/sample-noop"
|
|
}
|
|
```
|
|
|
|
The HTTP job status is `queued`, `running`, `succeeded`, or `failed`. A
|
|
`succeeded` job means the guide-board executor completed and wrote its normal
|
|
run directory; the assessment result itself is still reported separately as
|
|
`completed`, `failed`, `blocked`, or `infrastructure_error`.
|
|
|
|
### `GET /runs`
|
|
|
|
Lists known in-memory jobs for the current service process. Job records are not
|
|
durable across service restarts.
|
|
|
|
### `GET /runs/{job_id}`
|
|
|
|
Returns a single job record with request metadata, result paths, or execution
|
|
errors.
|
|
|
|
### `GET /runs/{job_id}/reports`
|
|
|
|
Returns the Markdown report content, assessment package JSON, retention summary,
|
|
and their filesystem paths after a job has succeeded.
|
|
|
|
## Container Mode
|
|
|
|
The core container can run the service through the existing entrypoint:
|
|
|
|
```sh
|
|
podman run --rm -p 8080:8080 \
|
|
-v "$PWD/runs:/runs" \
|
|
guide-board-core:local \
|
|
--root /opt/guide-board serve --host 0.0.0.0 --port 8080
|
|
```
|
|
|
|
The service keeps job state in memory. Durable run evidence remains in the
|
|
mounted output directory. See `docs/SERVICE-JOB-DURABILITY.md` for the explicit
|
|
restart and recovery contract.
|