Story: Show the environment inside DSH

Table of Contents

This page documents a story in Sprint 26. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

1. Goal

A DSH plugin that shows the session's own checkout as a live environment: the environment name, when the database was last restored and how long ago, the schema drift against HEAD, and the state of every service unit. The plugin starts and stops services and restores the database, with the destructive path guarded. It reads its data from compass, so the readiness and drift rules have one home rather than two.

2. Status

Field Value
State DONE
Parent sprint Sprint 26
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-09-30

3. Acceptance

  • The session header names this session's environment with a health dot, and the dot is red when the database is unreachable or a service is failed or missing.
  • The Environment view shows the environment name, the database restore time and its age, the schema drift, and every service unit with its state.
  • A service systemd reports as failed shows as failed and coloured red, and is not folded into stopped.
  • One service starts and stops from its own row, and the whole fleet starts and stops from the panel header, each in one click.
  • Restoring the database is guarded by a confirmation that names the database, and the default flow stops services, rebuilds, then starts them.
  • The plugin reads only the session's own work tree, and it never inherits the DSH server's environment.
  • compass env status emits the same data as JSON, and compass bearings reads it instead of recomputing it.

4. Tasks

Task State Start End Description
Scaffold story: Show the environment inside DSH DONE 2026-09-30 2026-09-30 Story scaffolding rides this task: documents, sprint wiring, and the scaffold PR. Close it before merging that PR.
Add compass env status and the JSON contract the plugin reads DONE 2026-09-30 2026-09-30 One verb that gathers the environment and emits it as JSON, so the plugin reads compass and bearings stops recomputing the same block.
Build the environment plugin for DSH DONE 2026-09-30 2026-09-30 A DSH plugin that shows the session's own checkout as a live environment and can start, stop, and restore it.

5. Decisions

  • Both tasks ride one pull request. The plugin cannot be verified without the verb, and a work tree carrying one without the other is the broken state, so they are reviewed and merged together.
  • The plugin reads compass and not the raw sources. Readiness (a unit is active and its log carries Service ready), the drift comparison, and the rule that an unknown unit is missing are policy. One home for that policy means the plugin and the CLI cannot disagree about whether the environment is up. The cost is that a work tree whose compass predates env status says so plainly instead of rendering a wrong environment.
  • The plugin takes its environment from its session's work tree, never from the DSH server. dsh-web.service starts from the home directory with no ORES_* variables, because a checkout's database name once leaked into another checkout through the harness. The server's environment is therefore not evidence about any work tree.
  • failed becomes its own service state. compass folded it into stopped, so a crashed unit and a deliberately stopped one read the same in the summary line. The plugin colours failed red, and compass counts it apart from stopped.
  • Starting and stopping are one click each, with no confirmation. Both are cheap and fully reversible, and compass's own verbs do not ask. The database restore is the one guarded action, because it destroys data.
  • The restore offers two flows and defaults to the full one: stop services, recreate, then start services. A rebuild leaves running services holding connections to tables that no longer exist, and compass's own connection check says to stop the services first. The rebuild-only flow remains for when the fleet is already down.
  • The action strip shows compass's own output and the elapsed time, with no progress bar. compass prints its phases, and a percentage computed from nothing would be a guess.
  • The browser half is one hand-written file with no build step, and the plugin installs into a profile as a versioned tarball, following ores.dsh_kanban.

6. Out of scope

  • Editing .env from the view, and every compass write other than the services and the database.
  • Per-service ordering. compass starts the fleet and the units carry their own dependencies.
  • Resource usage (compass services top) and the process tree (compass services tree).
  • Remote environments. The view reads the work tree its session runs in.

7. Result

compass env status reports one checkout's environment as text, and as one JSON object for the plugin to read, and compass bearings prints its environment section from the same gather. The service vocabulary gained failed as a fifth state, so a crashed unit no longer reads as a deliberate shutdown.

projects/ores.dsh_environment is a DSH web plugin with one host entry, two routes, and one hand-written browser file. A readout arrives with the session and names the environment, its database age and its running count. The view carries three health tiles, the reasons behind the level, the database panel with its guarded Restore control, and every service row with its state, its detail, and its start and stop button. A failed unit and a unit the manager has never heard of are both red; stopped stays grey.

Starting and stopping cost one click each, because both are reversible. The database restore is the one guarded action, refused by the host unless the browser was shown that database and blocked by the browser until the environment name is typed.

A scratch DSH instance was the check no unit test could replace. It found that both routes answered an anonymous caller, because a plugin route is registered outside the harness's /api fence, and that the action route could therefore stop the fleet from a page that rebinds its own hostname to loopback. Both routes now require the cookie dsh web issues.

Emacs 29.3 (Org mode 9.6.15)