Design admin Web UI for cache, sync, service, and RAG operations-gitcode-mcp-AtomGit

已关闭

Design admin Web UI for cache, sync, service, and RAG operations #52

urandon创建于 7月3日关闭于 15 天前

urandon成员

7月3日创建

Why

As gitcode-mcp grows beyond a small CLI/MCP bridge, operators need an easier way to observe and control local state:

shared cache health and repository bindings;
long-running sync/backfill jobs;
GitCode rate limits and retry/backoff state;
deferred comments and incomplete collection coverage;
service coordinator liveness;
RAG provider/model readiness;
RAG indexing progress and semantic search coverage.

The CLI remains the source of truth, but a local admin Web UI could make dogfood, debugging, and everyday operation much easier.

Scope

Design a local-only admin UI for one machine/user. This is not a hosted multi-tenant product.

Initial surfaces to explore:

Overview

service coordinator status;
selected shared cache path;
schema version/migration status;
configured repositories;
token/auth readiness without exposing secrets;
provider/model readiness for RAG.

Repository Detail

record counts by type;
sync frontier status;
latest sync events;
cache coverage and known gaps;
comment coverage/deferred comment state;
RAG namespace and embedding coverage.

Sync / Backfill Control

start bounded or full sync;
choose surfaces: issues, comments, pulls, wiki;
configure page/record bounds;
rate-limit mode and backoff visibility;
pause/cancel/resume where supported;
progress timeline/log view.

RAG Control

provider setup/doctor status;
model/profile selection;
index start/cancel/resume;
coverage and stale/missing/failed chunks;
sample semantic search smoke test.

Diagnostics

recent failures grouped by endpoint/failure class;
cache locks/service socket state;
useful remediation actions;
links/commands to reproduce in CLI.

Safety Requirements

Bind to localhost only by default.
Do not expose raw credentials, tokens, cookies, or unsanitized API payloads.
Destructive operations must require explicit confirmation and should remain CLI-only unless a later capability entry defines a stricter UI contract.
The UI should be optional and should not be required for MCP/CLI operation.
Prefer using existing service coordinator APIs and capability registry metadata instead of adding a second control plane.

Design Questions

Should the admin UI be served by gitcode-mcp service run, or should it be a separate gitcode-mcp admin serve mode in the same binary?
Should the transport reuse the existing local JSON-RPC/IPC coordinator path with a small HTTP adapter?
How much should be read-only in MVP?
Which write actions are safe enough for Web UI: sync start/cancel, RAG index start/cancel, service doctor, repo binding add/update?
How should job logs/progress be retained and paginated?
Should the UI use server-rendered HTML, a small embedded SPA, or generated static assets?

Acceptance Criteria

Produce a design comment/spec for the admin Web UI MVP.
Define the process/runtime shape and how it relates to gitcode-mcp service run.
Define read-only versus write/control surfaces.
Define safety boundaries and local-only defaults.
Define the API/control-plane reuse strategy.
Decompose implementation into follow-up tasks if the design looks viable.

Dogfood Context

This came from runtime-core RAG dogfood where:

shared cache migration and binding state needed to be inspected;
long-running sync/backfill was hard to supervise from the CLI alone;
comment endpoint rate limits dominated the sync run;
RAG indexing progress worked well, but required service coordinator visibility;
a compact local UI would have made it much easier to see what was running, what was blocked, and what was safe to do next.

urandon成员

7月3日添加了label：documentationenhancementepic

urandon成员

16 天前评论：

Design and implementation plan published:

Design doc: https://gitcode.com/urandon/gitcode-mcp/wiki/Admin-Web-UI-Design-2026-08-25.md

Decisions

Use Svelte 5 + SvelteKit + TypeScript + Vite + @sveltejs/adapter-static.
Embed deterministic generated assets in the existing Go binary with //go:embed all:assets; Node is not required at runtime or for an unchanged go install ./....
Keep gitcode-mcp service run as the only daemon/job owner. Add an optional loopback admin listener plus gitcode-mcp admin open/status; do not introduce a second long-lived UI control plane.
Add a thin versioned HTTP/SSE adapter over the same coordinator/use-case/capability layers used by CLI/MCP. The browser does not invoke CLI/MCP or talk directly to the Unix JSON-RPC socket.
Start with observation, then add bounded/idempotent job controls and plan/apply policy controls. Destructive cache/RAG operations, credential management, raw logs/payloads, and remote destructive writes remain CLI-only.
Treat loopback as insufficient by itself: exact Host/Origin, no CORS, one-time launch exchange, SameSite/HttpOnly session, CSRF, CSP, and public-safe DTOs are part of the foundation.

Temporal was used as a packaging reference. Its UI is a SvelteKit static SPA built into Go UI-server assets and embedded with go:embed; its production deployment uses a separate UI-server, while Temporal CLI imports that Go UI-server for server start-dev. We copy the static-build/embed technique, not the extra production process.

Product model

The UI is organized into six semantic cohorts rather than CLI command groups:

identity/topology — service, caches, bindings, registrations, namespaces;
readiness — daemon, cache/schema/WAL, GitCode auth, provider/model, capabilities;
corpus freshness/completeness — head, tail, secondary queues, projection, RAG;
execution/scheduling — jobs, progress, rate limits, contention, retry;
policy/control — maintenance bounds, collections, intervals, profiles;
governance/recovery — plans, receipts, typed diagnostics, remediation.

The design deliberately keeps current coverage separate from active contention, scheduled retry, and last stage error. That incorporates the dogfood finding in #91: a current/searchable namespace must not be hidden by a transient stale degraded stage result.

Follow-up issues

#92 — embedded SvelteKit runtime and secure local listener.
#93 — versioned observation API and resumable SSE events.
#94 — overview, cache topology, repository coverage, diagnostics.
#95 — sync/RAG job supervision and safe cancel/retry.
#96 — maintenance and repository-binding plan/apply controls.
#97 — RAG Search Lab, accessibility, browser E2E, and release-quality gates.

Dependency order:

#92 foundation
  -> #93 observation API
       -> #94 read-only product views
            -> #95 job supervision
                 -> #96 maintenance/binding controls
            -> #97 Search Lab + release hardening

#96 and #97 can proceed in parallel once their dependencies are satisfied. #91 is a correctness input to #93/#94 and should be reflected in their DTO/state derivation even if its scheduler fix lands independently.

Recommended first implementation slice: #92. It establishes the packaging/security/process boundary while keeping the initial UI intentionally read-only.

urandon成员

15 天前评论：

Admin Web UI epic delivered.

All implementation follow-ups are closed:

#92 embedded SvelteKit runtime and secure loopback listener;
#93 versioned observation API and resumable SSE;
#94 overview, cache topology, repository coverage, and diagnostics;
#95 daemon-owned job supervision with safe cancel/retry;
#96 maintenance and repository-binding plan/apply controls;
#97 RAG Search Lab and release-quality gates.

The final product keeps service run as the only coordinator, embeds deterministic static assets in the Go binary, defaults the listener off and loopback-only, uses one-time launch/session/CSRF/CSP boundaries, exposes public-safe DTOs, and keeps destructive/cache-path/credential/provider-setup operations outside browser authority.

Dogfood feedback about cross-tab visual inconsistency was resolved before closing: all views now share documented Light/Dark/System tokens, System default, one typography/control scale, and Lucide icon semantics. The durable contract is docs/admin-ui-design-system.md; runtime/API ownership is docs/admin-ui.md; release budgets and checks are docs/admin-ui-release-gates.md.

Final implementation merged in !101. Full Go/frontend/browser/deterministic-asset gates passed. The remaining open #90 and #91 are bounded repair/scheduler correctness follow-ups, not incomplete UI-epic acceptance criteria.

urandon成员

15 天前关闭了 issue

urandon成员

15 天前关联了里程碑：Admin Web UI

urandon成员

15 天前添加了label：admin-ui