Add UI development task briefs
This commit is contained in:
Emil
@@ -0,0 +1,81 @@
|
||||
# Task: safely preview partial CSV artifacts in the UI
|
||||
|
||||
## Assignment
|
||||
|
||||
You are the junior developer implementing one contained UI feature: an
|
||||
authenticated operator can preview a small portion of a CSV artifact belonging
|
||||
to the job they are viewing. This is a diagnostic aid, not a final-results
|
||||
page.
|
||||
|
||||
## Read first
|
||||
|
||||
1. `AGENTS.md`
|
||||
2. `.agents/coordinator.md`
|
||||
3. `docs/web-interface-plan.md`
|
||||
4. `docs/api-contract.md`
|
||||
5. `coordinator/internal/transport/http/ui.go` and its tests
|
||||
|
||||
## Current baseline
|
||||
|
||||
The coordinator serves an authenticated local web UI. Job detail pages already
|
||||
list partial result artifacts and provide job-scoped downloads. The browser has
|
||||
no worker token and must not learn storage paths. A partial shard CSV is never
|
||||
a global or final molecular-search result.
|
||||
|
||||
## Scope
|
||||
|
||||
Add a **Preview** action next to eligible CSV artifacts on a job detail page.
|
||||
|
||||
- Preview only artifacts that belong to the requested job.
|
||||
- Show at most the first **30 rows** and read at most **64 KiB** from storage.
|
||||
- State clearly when content was truncated.
|
||||
- Preserve the existing download action.
|
||||
- For a non-CSV artifact, return a friendly, sanitized explanation rather than
|
||||
attempting to render bytes as text.
|
||||
- Use an existing UI route pattern or add a small UI-authenticated endpoint;
|
||||
keep it separate from worker API routes.
|
||||
|
||||
## Security rules
|
||||
|
||||
- Require UI Basic Auth for every preview request.
|
||||
- Verify job ownership in the coordinator before opening the artifact; an
|
||||
artifact ID from another job must not be previewable.
|
||||
- Never expose `storage_key`, filesystem paths, database errors, bearer tokens,
|
||||
or worker-local information.
|
||||
- Do not use `innerHTML` for CSV fields. Use `html/template` escaping or
|
||||
`textContent` so strings such as `<script>alert(1)</script>` are displayed as
|
||||
data, not executed.
|
||||
- Do not load the complete artifact into memory.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Charts, molecule imagery, RDKit rendering, client-side CSV libraries, React,
|
||||
and a new frontend service.
|
||||
- Changing job/task state, retrying tasks, or implementing reducer output.
|
||||
- Redesigning the broader dashboard or job-creation workflow; that belongs to
|
||||
`docs/user-space-task.md`.
|
||||
|
||||
## Suggested implementation shape
|
||||
|
||||
Keep UI transport, use case, and storage responsibilities separate. Return a
|
||||
small view model containing artifact metadata, column headers, rows, and a
|
||||
`truncated` flag. Reuse existing coordinator-owned artifact access rather than
|
||||
reading a path supplied by the browser. Keep the handler streaming/limited.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- A valid partial CSV can be previewed from its own job detail page.
|
||||
- The result shows no more than 30 data rows and marks 64 KiB/row truncation.
|
||||
- Empty and malformed CSV content fail safely with a clear message.
|
||||
- A non-CSV artifact is rejected safely.
|
||||
- Unauthenticated access is rejected; a cross-job artifact request is not
|
||||
disclosed or served.
|
||||
- HTML-like values are escaped in the rendered preview.
|
||||
- Existing artifact downloads still work.
|
||||
- Add Go tests for all cases above and run `go test ./...` and `go vet ./...`.
|
||||
|
||||
## Handoff
|
||||
|
||||
Work in one focused branch and one PR. Report files changed, any API impact,
|
||||
test commands/results, and known limitations. Do not commit datasets, generated
|
||||
CSV files, Docker volumes, `.venv`, or `worker-data/`.
|
||||
@@ -0,0 +1,83 @@
|
||||
# Task: improve the operator user space
|
||||
|
||||
## Assignment
|
||||
|
||||
You are the senior developer responsible for the **user space**: the
|
||||
human-facing local operator interface served by the Go coordinator. In this
|
||||
task, “user space” means a clear UI and workflow for a trusted local operator;
|
||||
it does **not** mean public accounts, registration, roles, multi-tenancy, or
|
||||
remote deployment.
|
||||
|
||||
Create a small, coherent improvement to the existing UI so a person can
|
||||
understand and operate a SciMesh pipeline without reading API payloads or
|
||||
coordinator logs. Keep all interface copy in English.
|
||||
|
||||
## Read first
|
||||
|
||||
1. `AGENTS.md`
|
||||
2. `.agents/coordinator.md` and `.agents/integration.md`
|
||||
3. `docs/web-interface-plan.md`
|
||||
4. `docs/api-contract.md`
|
||||
5. `STATUS.md` and the current `coordinator/internal/transport/http/ui.go`
|
||||
|
||||
## Current baseline
|
||||
|
||||
`main` already provides local Basic Auth (`UI_AUTH_TOKEN`), a dashboard, job
|
||||
submission for diagnostic similarity-search runs, task progress, partial CSV
|
||||
downloads, a stop-job action, and an optional dataset row limit. A job is a
|
||||
**pipeline check** until CTX-09 adds a reducer; individual shard CSVs are not a
|
||||
final scientific result.
|
||||
|
||||
## Scope
|
||||
|
||||
Improve the end-to-end operator journey:
|
||||
|
||||
- make the dashboard explain service readiness, workers, jobs, and the next
|
||||
safe action in plain English;
|
||||
- make job creation validation and success/failure feedback understandable;
|
||||
- make job detail clearly distinguish queued, running, failed, stopped, and
|
||||
completed pipeline checks;
|
||||
- keep polling and all user-visible states reliable after a page refresh;
|
||||
- expose actionable, sanitized failure guidance without leaking paths, tokens,
|
||||
SQL errors, or tracebacks;
|
||||
- document the workflow in `coordinator/README.md` or `README.md`.
|
||||
|
||||
Use server-rendered Go templates, embedded assets, and small vanilla
|
||||
JavaScript only. Preserve the existing worker API and Basic Auth boundary.
|
||||
|
||||
## Explicitly out of scope
|
||||
|
||||
- user accounts, sign-up, roles, sessions, OAuth, or multi-tenancy;
|
||||
- executing or controlling workers from the browser;
|
||||
- direct browser access to PostgreSQL or worker endpoints;
|
||||
- final-result reduction, distributed workload planning, or graph execution;
|
||||
- artifact CSV preview/visualisation. That is assigned independently in
|
||||
`docs/artifact-preview-task.md`.
|
||||
|
||||
## Security and protocol rules
|
||||
|
||||
- `UI_AUTH_TOKEN` is never sent to HTML, JavaScript, URLs, logs, or storage.
|
||||
- Use `html/template`; JavaScript must use `textContent`, never `innerHTML` for
|
||||
received data.
|
||||
- UI artifact operations must be job-scoped and coordinator-owned.
|
||||
- Do not disclose raw worker commands, local paths, bearer tokens, or database
|
||||
errors.
|
||||
- Do not change worker/coordinator API contracts silently. Document any
|
||||
intentional API change in `docs/api-contract.md` and `docs/openapi.yaml`.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- A new operator can start the stack, authenticate, submit a small run, start
|
||||
workers, understand live progress, and safely stop a job from the UI.
|
||||
- The UI never calls or displays worker bearer-token endpoints.
|
||||
- All partial output is visibly labelled as diagnostic until a reducer exists.
|
||||
- Disabled UI remains `404`; unauthenticated UI requests remain rejected.
|
||||
- Go tests cover changed routes and states, including auth and a sanitized
|
||||
error case.
|
||||
- `go test ./...`, `go vet ./...`, and the relevant real-PostgreSQL tests pass.
|
||||
|
||||
## Handoff
|
||||
|
||||
Use one branch and one PR. In the PR description state the user journey that
|
||||
changed, screenshots if visual layout changed, API impact (`none` if none),
|
||||
and exact test commands/results. Do not stage local datasets or `worker-data/`.
|
||||
Reference in New Issue
Block a user