# stackchain-dashboard

Live AI-driven adaptive UI for the Stackchain AI Lab Gitea experience.

## Local quickstart

Python 3.11 or newer is recommended. Create an isolated environment and install
the pinned dependencies:

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
```

Point the dashboard at the Gitea server root (without `/api/v1`) and provide a
token that can read dashboard data, update the authenticated user's notification
threads, create and self-assign issues, discover and claim open unassigned issues,
create issue comments, close assigned issues, inspect/comment on assigned pull
requests, merge assigned pull requests, and submit pull-request reviews.
Pull-request replies and mobile My Work issue and PR comments use Gitea's
issue-comment API; mobile issue capture requires issue
creation and assignment permission. Closing an assigned issue, native Comment,
Approve, and Request changes reviews, and assigned-PR merge require repository
write permission. Native Comment, Approve, and Request changes reviews support
head-scoped draft comments anchored to changed lines; the dashboard validates each
comment path and submits the summary, decision, and inline comments in one review
request. The dashboard rechecks the current pull-request head, CI success, draft
state, and mergeability immediately before every merge.
Serve the dashboard
only to trusted users on its own origin; cross-origin API
access is intentionally disabled. Then start the API and bundled frontend:

```bash
export GITEA_URL='https://forge.example.com'
export GITEA_TOKEN='<read-notification-and-issue-write-token>'
uvicorn src.main:app --host 127.0.0.1 --port 8000
```

Open `http://127.0.0.1:8000/` for the dashboard. To verify the backend and its
Gitea connection directly, request
`http://127.0.0.1:8000/api/v1/context`; a successful response is JSON containing
`user`, `repos`, `issues`, and `pull_requests`. Never commit the token or place
it in a tracked configuration file.

For service monitoring, GET `/healthz` is a liveness check that confirms the
API process is running and does not contact Gitea. GET `/readyz` is the
readiness check: it validates the configured Gitea credentials and returns
HTTP 503 with an error when Gitea is unavailable or authentication fails.

Run the test suite with:

```bash
python3 -m pytest tests/ -q
```

## Autonomous release worker

The deterministic issue-to-release engine lives at `src/release_engine.py`.
It discovers or targets one Gitea issue, verifies its claim, creates an issue
branch, invokes a configured coding agent, runs tests, pushes, and opens a
linked pull request. Merge remains gated by CI/review; the existing release
workflow drafts the release candidate after merge.

Plan against live Gitea without mutating anything:

```bash
python3 -m src.release_engine \
  --repo stackchain/stackchain-dashboard \
  --agent timmy \
  --issue 14 \
  --dry-run
```

Execute one ticket after implementing and committing its change directly on
the deterministic branch printed by `--dry-run`:

```bash
export GITEA_TOKEN='<scoped-token>'
export RELEASE_AGENT_COMMAND=true
python3 -m src.release_engine \
  --repo stackchain/stackchain-dashboard \
  --agent timmy \
  --issue 19 \
  --test-command 'python3 -m pytest tests/ -q'
```

`GITEA_TOKEN` needs issue and repository write scopes. The engine verifies the
claim, reruns the test command, pushes the branch, and opens a PR containing
`Closes #19` plus test evidence. Replace `19` with the selected issue number;
do not run without `--issue` when processing a preselected ticket.

Durable state defaults to `.release-engine/state.json`. Full behavior and
safety gates are documented in
[`docs/release-engine-spec.md`](docs/release-engine-spec.md).