diff --git a/docs/artifact-preview-task.md b/docs/artifact-preview-task.md new file mode 100644 index 0000000..fc55c3a --- /dev/null +++ b/docs/artifact-preview-task.md @@ -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 `` 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/`. diff --git a/docs/user-space-task.md b/docs/user-space-task.md new file mode 100644 index 0000000..cf870ea --- /dev/null +++ b/docs/user-space-task.md @@ -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/`.