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:

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, claim, and release issue assignments, set or clear due dates on assigned 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. Issue capture and authored mobile actions (issue comments, pull-request comments, notification replies, and reviews) persist per-draft idempotency keys, so retrying after a timeout or reload replays a confirmed result instead of posting duplicate content. Direct API callers should preserve the Idempotency-Key header with the unchanged route and payload until a 201 response is confirmed. 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:

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. Press Ctrl/Cmd+K in the dashboard to search commands plus issues and pull requests across every repository visible to the configured Gitea token. Remote search starts after two characters, is debounced, and keeps local commands usable if Gitea search is unavailable. The bounded API is also available at GET /api/v1/search?q=<query>&limit=<1-25>. 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:

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:

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:

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.