generated from coulomb/repo-seed
152 lines
4.1 KiB
Markdown
152 lines
4.1 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,
|
|
submission package JSON, export manifest JSON when present, and their filesystem
|
|
paths after a job has succeeded.
|
|
|
|
### `GET /retained-runs`
|
|
|
|
Lists durable retained run summaries by scanning a runs directory. Without a
|
|
query parameter, the service scans `<root>/runs`.
|
|
|
|
```text
|
|
GET /retained-runs?runs_dir=/runs
|
|
```
|
|
|
|
### `GET /retained-runs/latest`
|
|
|
|
Selects the latest retained run, optionally filtered by target and assessment
|
|
profile refs.
|
|
|
|
```text
|
|
GET /retained-runs/latest?runs_dir=/runs&target=sample-repository&assessment=sample-noop-assessment
|
|
```
|
|
|
|
### `GET /retained-runs/{run_id}/reports`
|
|
|
|
Returns the retained summary plus safe report paths for a durable run. This
|
|
works after a service restart because it reads `retention-summary.json` from
|
|
disk instead of in-memory job records.
|
|
|
|
### `GET /retained-runs/{run_id}/artifact-manifest`
|
|
|
|
Returns the assessment package `artifact_manifest` for a retained run. If the
|
|
run predates assessment packages, the response is compatible and returns an
|
|
empty manifest with `compatibility: "assessment-package-missing"`.
|
|
|
|
Retained-run endpoints validate report and artifact paths before returning
|
|
them. A path that escapes the selected run directory is rejected.
|
|
|
|
## 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 and can be discovered through `GET /retained-runs`
|
|
after restart. See `docs/SERVICE-JOB-DURABILITY.md` for the explicit recovery
|
|
contract.
|