Skip to content

Dev-only design book and host dev environment for front - #1178

Draft
skipi wants to merge 2 commits into
mainfrom
mk/front/design-book
Draft

skipi wants to merge 2 commits into
mainfrom
mk/front/design-book

Conversation

@skipi

@skipi skipi commented Aug 13, 2026

Copy link
Copy Markdown
Collaborator

What

A /design-book page compiled only in dev and test — a playground for iterating on front UI with the app's real CSS, components and build pipeline, following the pattern of an in-app component reference book. Ships with a small library of workspace components (block cards, job rows, attempt rail, outcome and promotion cards, SVG wire drawing, dependency tiering) and one reference study rendering a canned workflow fixture served by the page's own dev-only JSON endpoint.

Alongside it, a host-side dev environment so the server can run natively: a flake.nix pinned to the exact toolchain from the Dockerfile (Elixir 1.14.5 / OTP 25.3.2.21, node 20), a headless-Chrome screenshot helper (scripts/screenshot.sh, make design.shot), and docker-compose.host.yml — an explicit, not auto-loaded override that publishes rabbitmq/redis on 127.0.0.1 for make dev.services. The base docker-compose.yml is untouched, so existing docker workflows are unaffected.

Not in prod, by construction

The route scope sits inside the same compile-time environment guard the router already uses elsewhere, so the routes do not exist in prod builds. assets/build.js only adds the design_book.js entry point when not building for prod, and mix assets.deploy hardcodes MIX_ENV=prod, so the bundle cannot land in a release. The controller, view and layout compile everywhere but are unreachable without the routes.

Verification

473 mocha specs (including new ones for the study registry and dependency tiering), 5 controller tests, tsc --noEmit, eslint, mix format --check-formatted and credo all green. A prod asset build was run to confirm no design_book.js is emitted while app.js builds unchanged — byte-identical app.js before and after this change.

How to try it

cd front
make dev.services
make dev.nix.server   # or the existing docker flow: make dev.server
open http://localhost:4000/design-book

🤖 Generated with Claude Code

@github-project-automation github-project-automation Bot moved this to Backlog in Roadmap Aug 13, 2026
skipi added a commit that referenced this pull request Aug 14, 2026
## What

The two rerun controls on the workflow page describe themselves in ways
that invert their actual scope. The header button reads **Rerun** but
starts a completely new workflow from the same commit. The button on a
failed pipeline row reads **Rebuild Pipeline** but is the narrow one —
it re-runs only what did not pass inside that single pipeline. Reading
the labels, "Rebuild Pipeline" is the one that sounds like a full
restart, so people reach for whichever button is nearest and get the
scope they did not want. That is the confusion reported in
#686.

This renames both controls after what they rerun and makes the
difference legible without a click:

- Header: `Rerun` → **Rerun Workflow**, tooltip "Starts a fresh run of
the whole workflow from this commit". Same on the job page header, where
the tooltip also keeps the "including this job" note.
- Pipeline row: `Rebuild Pipeline` → **Rerun Failed Jobs**, tooltip
"Reruns only the jobs in this pipeline that did not pass, keeping the
ones that did. Use Rerun Workflow above for a fresh run of everything."

That row tooltip previously existed as a plain `title` attribute and did
not surface in the tree. It now uses `data-tippy-content`, the mechanism
the rest of the app uses: `app.js` binds those on page load, and Pollman
already destroys and rebinds tooltips around each partial refresh, so
the tooltip survives the tree's polling. Button sizes are unchanged —
the row keeps `btn-tiny`, matching `Stop Pipeline` next to it.

Follow-through so the rename does not leave stale copy behind: the tree
JS in-flight label (`Rebuilding...` → `Rerunning...`) and its
error-restore label, the workflow editor's rerun-granularity section
(which named the button in its explanatory line), and the docs passage
describing both buttons — that passage additionally claimed the header
button "restarts the whole pipeline from the beginning", which is wrong;
it restarts the workflow.

Routes, permissions, feature gating and behaviour are untouched. The row
button still renders only behind `ui_partial_ppl_rebuild`, so
organizations without that feature see a single unambiguous **Rerun
Workflow**.

## Scope

This is a deliberate low-effort interim step: it fixes the vocabulary,
not the layout. The larger piece of work — collapsing both controls into
one pipeline-scoped `Rerun` menu that enumerates the pipelines with
failures — is being explored separately (#1178
carries the playground it is designed in). The vocabulary picked here is
the vocabulary that design lands on, so this rename is not thrown away
when the menu ships.

## Verification

Copy-only change; no spec asserts any of the renamed strings. The
guest-path assertion in `workflow_controller_test.exs` that refutes the
presence of a rerun button is unaffected — anonymous and guest viewers
render `workflow/_workflow.html.eex`, which has no rerun control at all.
Relying on CI for compile, format, lint and the front suites.

## Left for a follow-up

`docs/docs/using-semaphore/pipelines.md` embeds
`img/rerun-pipeline.jpg`, a screenshot showing the old labels. It needs
to be retaken once this is deployed. The versioned CE/EE docs are
intentionally not touched — released versions still ship the old labels.

`Stop Pipeline`, in the same row, still has no tooltip at all.

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

1 participant