workspaces 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d9d7e03d386bd8949baf124281f3ac26eb2b49f7fb109a97a8f0a4fb16263fa
-  data.tar.gz: 76ab8e2adfeb5a5daea4526a41d6d33991076000bd4bed0f621df6355511341a
+  metadata.gz: a0102752fa27b9aa9b5fd40ab163411bc9d0411cdfaa00d8a82f6a04088e0099
+  data.tar.gz: 63704204815a6e183e1e244da898defcf67ff3e55b45e69400e19e9f275abaec
 SHA512:
-  metadata.gz: 7d5c69e3d6c6201d08b3bd70d100b8adaf1eb53f3aba93ab91ae3656ab67d6350239dff291fa706f67b7350e7296656ddb4f82b57b6fb9aa4469b5d3a45fdbb9
-  data.tar.gz: aba50059b56131d6f949f9badc2327fe5a3f4d05e384452299e2e2afc45b7c24be7a93cf7d76a9c2bf5b96d1bb3a71938a3cbe3d74451a28e718430ba1784a20
+  metadata.gz: a6e7e66264833d0b55493fc42203af62be3726ee6d8422d913e00f11afc2b9cf65aaef078e0ac06ecdedbced9c1cd1ff62d37759e1eb7a28295b01908d8bb976
+  data.tar.gz: 2bac52fea92eee837b049d2ce5b24946c0d4f3e306530dd6f4a8aef3e772495725dcdb1d7eec9c4b0b339f54d12948202d725ef609e6c1a2237c470c474276c8

data/DESIGN.md

@@ -48,10 +48,16 @@ Restrained tooling UI: dark elevated panels, compact spacing rhythm, clear statu
 - **PR source update**: a secondary Update from PR form only for PR-sourced workspaces; it fetches the latest PR head, fast-forwards the checkout, and preserves local edits without rebuilding or restarting. A persistent result message explains when rebuild is needed or when a retained stash needs manual recovery.
 - **Failure panel**: prominently above the log, with escaped error details and a matching retry action.
 - **PR page**: existing workspaces are primary; creating another is a collapsed secondary disclosure. Creation is primary only when none exist.
+- **Lifecycle state machine**: the workspace detail page is driven by `Presentation::STATES`. Each state (`idle`, `busy`, `ready`, `stopped`, `error`/`interrupted`, `unknown`) declares which sections exist (progress, actions, environment, log, details, danger zone) and the label of the single environment-form button. Sections that are not usable or meaningful in a state are hidden, never shown disabled. The server renders the initial state and the polling script re-applies it from `presentation.sections`, so the page transitions without a reload.
+  - `idle` (brand new): only the environment editor plus a **Start workspace** button, with a one-line hint. No log, actions, details, or delete.
+  - `busy` (setup/restart running): only progress and the live log.
+  - `ready`: everything, with **Save & restart**.
+  - `stopped`: no progress from the previous run; **Save & start**.
+  - `error`/`interrupted`: retry action, environment editor, progress, and logs; **Save & retry**.
 - **Action buttons**: start, prepare/rebuild, restart server, stop server, and refresh
 - **Actions & settings panel**: status-adjacent panel that combines routine lifecycle controls, Open workspace, Refresh status, PR update messaging, and editable environment settings so routine operations stay in one keyboard-reachable region.
 - **Open workspace**: success-styled link available when the server is ready
-- **Lifecycle controls**: disabled while busy; helper text distinguishes rebuilding from server-only restart
+- **Lifecycle controls**: hidden while busy (see state machine); helper text distinguishes rebuilding from server-only restart
 - **Bounded log panel**: monospace text, fixed max height, manual-scroll-safe updates
 - **Log source switcher**: two native links inside one log panel, with current selection announced through `aria-current`; only the selected bounded log is loaded and refreshed. Setup is the default.
 - **Preview destination**: a small muted URL in Workspace details, visible before readiness; the primary Open workspace action remains reserved for ready servers.

data/lib/workspaces/dashboard/app.js

@@ -94,6 +94,7 @@
     started = Date.parse(data.prepare_started_at);
     completed = Date.parse(data.completed_at);
     renderStatus(view);
+    renderSections(view);
     node('message').textContent = data.message || '';
     node('source-update-message').textContent = data.source_update_message || '';
     node('progress').replaceChildren(...view.steps.map(renderStep));
@@ -103,6 +104,27 @@
     updateLog(data);
   }
 
+  function renderSections(view) {
+    const sections = view.sections || {};
+    root.querySelectorAll('[data-section]').forEach((element) => {
+      element.hidden = !sections[element.dataset.section];
+    });
+    const controls = node('controls');
+    if (controls) {
+      controls.hidden = !sections.actions && !sections.environment;
+      const title = node('actions-settings-title');
+      if (title && view.controls_title) title.textContent = view.controls_title;
+    }
+    const hint = node('hint');
+    if (hint) {
+      hint.textContent = view.hint || '';
+      hint.hidden = !view.hint;
+    }
+    node('message').hidden = view.state === 'idle';
+    if (window.WorkspaceEnvironment)
+      window.WorkspaceEnvironment.setSubmitLabel(view.environment_submit);
+  }
+
   function renderStatus(view) {
     node('status').textContent = view.title;
     node('activity').hidden = !view.busy;

data/lib/workspaces/dashboard/environment.js

@@ -45,6 +45,18 @@
     });
   }
 
+  function submitLabel() {
+    return (submit && submit.textContent.trim()) || 'Save & restart';
+  }
+
+  function setSubmitLabel(label) {
+    if (!label) return;
+    if (submit) submit.textContent = label;
+    form.querySelectorAll('[data-submit-label]').forEach((element) => {
+      element.textContent = label;
+    });
+  }
+
   function setStatus(message) {
     if (!message) return;
     if (lastAnnounced === message) return;
@@ -74,7 +86,7 @@
 
   function announceUnsaved(message) {
     if (activeBusy) return;
-    const nextMessage = message || 'Draft updated locally and not saved yet. Use Save & restart to apply changes.';
+    const nextMessage = message || 'Draft updated locally and not saved yet. Use ' + submitLabel() + ' to apply changes.';
     status.textContent = nextMessage;
     lastAnnounced = nextMessage;
   }
@@ -115,7 +127,7 @@
       if (!Object.prototype.hasOwnProperty.call(presets, nextValue)) return;
       replaceDraft(
         presets[nextValue],
-        'Preset loaded into draft only. Use Save & restart to apply changes.'
+        'Preset loaded into draft only. Use ' + submitLabel() + ' to apply changes.'
       );
     });
   });
@@ -124,6 +136,7 @@
     toggleBusy,
     updateStatus,
     setStatus,
+    setSubmitLabel,
     syncFromSnapshot(snapshot) {
       if (!snapshot || presetButtons.length === 0 || !editor) return;
       const rendered = snapshot.editable_environment;

data/lib/workspaces/dashboard/template.html.erb

@@ -8,8 +8,9 @@
       <h2 id="status" role="status"><%= escape(@presentation['title']) %></h2>
       <span id="activity" <%= 'hidden' unless @presentation['busy'] %>><span class="activity-dot" aria-hidden="true"></span> In progress · <span id="elapsed">—</span></span>
     </div>
-    <p id="message"><%= field('message') %></p>
-    <ol class="stepper" id="progress" aria-label="Setup progress">
+    <p id="hint" <%= 'hidden' unless @presentation['hint'] %>><%= escape(@presentation['hint']) %></p>
+    <p id="message" <%= 'hidden' if @presentation['state'] == 'idle' %>><%= field('message') %></p>
+    <ol class="stepper" id="progress" data-section="progress" aria-label="Setup progress" <%= 'hidden' unless section?('progress') %>>
       <% @presentation['steps'].each do |step| %>
         <li class="step" data-step-state="<%= step['state'] %>" <%= 'aria-current="step"' if step['state'] == 'active' %>><span class="step-bullet" aria-hidden="true"></span><span><%= escape(step['label']) %></span><span class="step-outcome"><%= escape(step_outcome(step)) %></span></li>
       <% end %>
@@ -19,19 +20,18 @@
     </section>
     <p id="connection" role="status"></p>
   </section>
-  <section class="status-panel controls-panel" aria-labelledby="actions-settings-title">
-    <h2 id="actions-settings-title">Actions &amp; settings</h2>
-    <div class="workspace-actions-group" aria-labelledby="actions-heading">
+  <section class="status-panel controls-panel" id="controls" data-section-group aria-labelledby="actions-settings-title" <%= 'hidden' unless section?('actions') || section?('environment') %>>
+    <h2 id="actions-settings-title"><%= escape(@presentation['controls_title']) %></h2>
+    <div class="workspace-actions-group" data-section="actions" aria-labelledby="actions-heading" <%= 'hidden' unless section?('actions') %>>
       <h3 id="actions-heading">Workspace actions</h3>
       <div class="workspace-actions">
         <a id="preview" class="button button--primary" href="<%= escape(Config.preview_url(@id)) %>" <%= 'hidden' unless @presentation['ready'] %> target="_blank" rel="noopener noreferrer">Open workspace</a>
         <div id="actions" class="workspace-actions"><% @presentation['actions'].each do |action| %><%= action_form(action) %><% end %></div>
-        <a class="button button--subtle" href="/workspaces/<%= @id %><%= @snapshot['log_source'] == 'backend' ? '?log=backend' : '' %>">Refresh status</a>
       </div>
       <p id="source-update-message" role="status"><%= field('source_update_message') %></p>
     </div>
-    <div class="workspace-settings" aria-labelledby="environment-overrides">
-      <h3 id="environment-overrides">Editable environment</h3>
+    <div class="workspace-settings" data-section="environment" aria-labelledby="environment-overrides" <%= 'hidden' unless section?('environment') %>>
+      <h3 id="environment-overrides">Environment</h3>
       <form method="post" action="/workspaces/<%= @id %>/environment" id="environment-form" data-environment-form data-environment-presets="<%= escape(environment_presets_json) %>">
         <fieldset class="env-fieldset" data-environment-fieldset <%= 'disabled' if @presentation['busy'] %>>
           <legend class="env-legend">Workspace settings</legend>
@@ -43,20 +43,20 @@
                   <button type="button" class="button button--subtle env-preset-button" data-environment-preset="<%= escape(name) %>" aria-pressed="false"><%= escape(name) %></button>
                 <% end %>
               </div>
-              <p class="muted" id="environment-preset-help">Select a preset, then Save &amp; restart to apply.</p>
+              <p class="muted" id="environment-preset-help">Presets decide which app this workspace runs. Select one, then use <strong data-submit-label><%= escape(@presentation['environment_submit']) %></strong> to apply it.</p>
             </div>
           <% end %>
           <label class="env-input-label" for="editable-env">Environment variables</label>
           <textarea id="editable-env" name="editable_env" rows="8" spellcheck="false" autocomplete="off" autocapitalize="off"><%= escape(editable_environment_text) %></textarea>
         </fieldset>
         <div class="env-actions">
-          <button class="button button--primary" data-env-submit <%= 'disabled' if @presentation['busy'] %>>Save &amp; restart</button>
+          <button class="button button--primary" data-env-submit <%= 'disabled' if @presentation['busy'] %>><%= escape(@presentation['environment_submit']) %></button>
         </div>
         <p class="muted" id="environment-status" role="status" aria-live="polite"></p>
       </form>
     </div>
   </section>
-  <section class="log-panel" aria-labelledby="log-title">
+  <section class="log-panel" data-section="log" aria-labelledby="log-title" <%= 'hidden' unless section?('log') %>>
     <div class="log-header"><h2 id="log-title">Live <%= field('log_source') == 'backend' ? 'backend' : 'setup' %> log</h2><time id="updated"><%= field('updated_at') %></time></div>
     <nav class="log-switch" aria-label="Log source">
       <a href="?log=setup" data-log-source="setup" <%= 'aria-current="page"' if @snapshot['log_source'] != 'backend' %>>Setup log</a>
@@ -64,8 +64,8 @@
     </nav>
     <pre id="log" tabindex="0" aria-label="<%= field('log_source') == 'backend' ? 'Backend' : 'Setup' %> log"><%= field('log_tail') %></pre>
   </section>
-  <details class="status-panel"><summary>Workspace details</summary><dl><dt>Preview URL</dt><dd><a class="detail-link" href="<%= escape(Config.preview_url(@id)) %>" target="_blank" rel="noopener noreferrer"><%= escape(Config.preview_url(@id)) %></a> <span class="muted">Available when ready</span></dd><dt>Branch</dt><dd><%= field('branch') %></dd><dt>Path</dt><dd><code><%= field('path') %></code></dd><dt>Related PR</dt><dd><%= escape(@snapshot.dig('related_pr', 'number') || 'None') %></dd><dt>Created</dt><dd><%= escape(@snapshot['created_at'] || 'Unavailable') %></dd><dt>Last startup</dt><dd><%= escape(@snapshot['started_at'] || 'Never') %></dd></dl></details>
-  <section class="status-panel danger-zone" aria-labelledby="danger-heading">
+  <details class="status-panel" data-section="details" <%= 'hidden' unless section?('details') %>><summary>Workspace details</summary><dl><dt>Preview URL</dt><dd><a class="detail-link" href="<%= escape(Config.preview_url(@id)) %>" target="_blank" rel="noopener noreferrer"><%= escape(Config.preview_url(@id)) %></a> <span class="muted">Available when ready</span></dd><dt>Branch</dt><dd><%= field('branch') %></dd><dt>Path</dt><dd><code><%= field('path') %></code></dd><dt>Related PR</dt><dd><%= escape(@snapshot.dig('related_pr', 'number') || 'None') %></dd><dt>Created</dt><dd><%= escape(@snapshot['created_at'] || 'Unavailable') %></dd><dt>Last startup</dt><dd><%= escape(@snapshot['started_at'] || 'Never') %></dd></dl></details>
+  <section class="status-panel danger-zone" data-section="danger" aria-labelledby="danger-heading" <%= 'hidden' unless section?('danger') %>>
     <h2 id="danger-heading">Danger Zone</h2>
     <p>Deleting this workspace stops its server and removes its worktree. <strong>Discard uncommitted and untracked changes</strong> permanently. The branch and committed work are preserved.</p>
     <form method="post" action="/workspaces/<%= @id %>/remove" id="remove-form">

data/lib/workspaces/dashboard_view.rb

@@ -106,6 +106,10 @@ module Workspaces
 
     private
 
+    def section?(name)
+      @presentation.fetch('sections', {})[name]
+    end
+
     def field(name)
       escape(@snapshot[name])
     end

data/lib/workspaces/presentation.rb

@@ -6,13 +6,45 @@ module Workspaces
     ACTIONS = { 'start' => 'Start workspace', 'prepare' => 'Rebuild & restart',
                 'restart' => 'Restart server', 'stop' => 'Stop server' }.freeze
 
+    SECTIONS = %w(progress actions environment log details danger).freeze
+    MANAGEABLE = SECTIONS
+
+    # Workspace lifecycle state machine. Each state declares only what is usable and
+    # meaningful there; everything else is hidden rather than shown disabled.
+    #
+    #   idle ──start──▶ busy ──▶ ready ◀──▶ busy
+    #                     │        │
+    #                     ▼        ▼
+    #                   error   stopped ──start──▶ busy
+    #                (interrupted)
+    #
+    # `environment_submit` labels the single environment-form button, which saves the
+    # settings and (re)starts the workspace, so a brand new workspace needs only that.
+    STATES = {
+      'idle' => {
+        sections: %w(environment),
+        environment_submit: 'Start workspace', controls_title: 'Set up your workspace',
+        hint: 'Choose the environment you want to preview below, then start the workspace. ' \
+              'Setup usually takes a few minutes.'
+      },
+      'busy' => { sections: %w(progress log), environment_submit: 'Save & restart' },
+      'ready' => { sections: MANAGEABLE, environment_submit: 'Save & restart' },
+      'stopped' => { sections: %w(actions environment log details danger), environment_submit: 'Save & start' },
+      'error' => { sections: MANAGEABLE, environment_submit: 'Save & retry' },
+      'interrupted' => { sections: MANAGEABLE, environment_submit: 'Save & retry' },
+      'unknown' => { sections: %w(log details), environment_submit: 'Save & restart' }
+    }.freeze
+
     def initialize(snapshot)
       @snapshot = snapshot
     end
 
     def to_h
       { 'title' => title, 'busy' => busy?, 'error' => error, 'steps' => steps,
-        'actions' => actions, 'ready' => status == 'ready' && !busy? }
+        'actions' => actions, 'ready' => status == 'ready' && !busy?,
+        'state' => state, 'sections' => sections, 'hint' => definition[:hint],
+        'controls_title' => definition.fetch(:controls_title, 'Actions & settings'),
+        'environment_submit' => definition[:environment_submit] }
     end
 
     private
@@ -25,6 +57,22 @@ module Workspaces
       @snapshot['active'] || status == 'preparing'
     end
 
+    def state
+      return 'busy' if busy?
+
+      STATES.key?(status) ? status : 'unknown'
+    end
+
+    def definition
+      STATES.fetch(state)
+    end
+
+    def sections
+      visible = definition[:sections].dup
+      visible.delete('progress') if steps.empty? || %w(idle stopped).include?(state)
+      SECTIONS.to_h { |name| [name, visible.include?(name)] }
+    end
+
     def title
       return 'Workspace busy' if @snapshot['active'] && !busy_status?
       return @snapshot['message'] || 'Running setup' if status == 'preparing'

data/lib/workspaces/version.rb

@@ -1,3 +1,3 @@
 module Workspaces
-  VERSION = '0.1.7'
+  VERSION = '0.1.8'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-07 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack