workspaces 0.1.10 → 0.1.12

data/lib/workspaces/presentation.rb

@@ -6,8 +6,14 @@ 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
+    # Three layers, from friendly to technical. `lead` is the headline, one sentence and at
+    # most one primary action. `environment` (presets and variables) is the area for
+    # deliberately changing something. `technical` is one disclosure holding setup steps,
+    # logs, workspace details, lifecycle controls and deletion; it is never the first thing
+    # a user reads, but it opens by itself when something needs attention. Setup steps are
+    # not a section of their own: each is an accordion with its own log inside `log`.
+    SECTIONS = %w(lead actions environment technical log details danger).freeze
+    TECHNICAL = %w(technical actions log details danger).freeze
 
     # Workspace lifecycle state machine. Each state declares only what is usable and
     # meaningful there; everything else is hidden rather than shown disabled.
@@ -20,19 +26,60 @@ module Workspaces
     #
     # `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.
+    #
+    # Per state: `headline` and `summary` are plain language; `open_environment` and
+    # `open_technical` say which disclosures start expanded. A failure always opens the
+    # technical section so the cause is visible without hunting for it.
     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.'
+        sections: %w(lead environment),
+        headline: "Let's get your workspace running",
+        summary: 'Pick the version of the site you want to preview, then start. Setup usually takes a few minutes.',
+        environment_submit: 'Start workspace', environment_title: 'Choose what to preview',
+        open_environment: true, open_technical: false
+      },
+      'busy' => {
+        sections: %w(lead technical log),
+        headline: 'Setting things up…',
+        summary: "This usually takes a few minutes. We'll take you to the preview when it's ready.",
+        environment_submit: 'Save & restart', environment_title: 'Change settings',
+        open_environment: false, open_technical: true
+      },
+      'ready' => {
+        sections: %w(lead environment) + TECHNICAL,
+        headline: 'Your workspace is ready',
+        summary: 'Everything is set up and running. Open it to see your changes.',
+        environment_submit: 'Save & restart', environment_title: 'Change settings',
+        open_environment: false, open_technical: false
+      },
+      'stopped' => {
+        sections: %w(lead environment) + TECHNICAL,
+        headline: 'Your workspace is paused',
+        summary: 'Start it again to pick up where you left off.',
+        environment_submit: 'Save & start', environment_title: 'Change settings',
+        open_environment: false, open_technical: false
+      },
+      'error' => {
+        sections: %w(lead environment) + TECHNICAL,
+        headline: "Something didn't go to plan",
+        summary: 'Setup stopped before it finished. You can try again, or change settings first.',
+        environment_submit: 'Save & retry', environment_title: 'Change settings',
+        open_environment: false, open_technical: true
       },
-      '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' }
+      'interrupted' => {
+        sections: %w(lead environment) + TECHNICAL,
+        headline: 'Setup was interrupted',
+        summary: 'It stopped before it finished. Try again to pick up from the start.',
+        environment_submit: 'Save & retry', environment_title: 'Change settings',
+        open_environment: false, open_technical: true
+      },
+      'unknown' => {
+        sections: %w(lead technical log details),
+        headline: 'Workspace status unknown',
+        summary: 'Open the technical details to see what the workspace is doing.',
+        environment_submit: 'Save & restart', environment_title: 'Change settings',
+        open_environment: false, open_technical: true
+      }
     }.freeze
 
     def initialize(snapshot)
@@ -42,9 +89,13 @@ module Workspaces
     def to_h
       { 'title' => title, 'busy' => busy?, 'error' => error, 'steps' => steps,
         '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] }
+        'state' => state, 'sections' => sections,
+        'headline' => definition[:headline], 'summary' => definition[:summary],
+        'subtitle' => subtitle, 'lead_action' => lead_action, 'total' => total,
+        'current_preset' => current_preset,
+        'environment_title' => definition[:environment_title],
+        'environment_submit' => definition[:environment_submit],
+        'open' => { 'environment' => definition[:open_environment], 'technical' => definition[:open_technical] } }
     end
 
     private
@@ -68,11 +119,53 @@ module Workspaces
     end
 
     def sections
-      visible = definition[:sections].dup
-      visible.delete('progress') if steps.empty? || %w(idle stopped).include?(state)
+      visible = definition[:sections]
       SECTIONS.to_h { |name| [name, visible.include?(name)] }
     end
 
+    # The single most useful thing to do next, or nil when the user should just wait.
+    # `open` links straight to the preview; the others are lifecycle form posts.
+    def lead_action
+      case state
+      when 'ready' then { 'kind' => 'open', 'label' => 'Open workspace' }
+      when 'stopped' then { 'kind' => 'post', 'key' => 'start', 'label' => 'Start workspace' }
+      when 'error', 'interrupted' then retry_action.merge('kind' => 'post')
+      end
+    end
+
+    # The preset whose values exactly equal the workspace's saved editable settings, or nil when
+    # there are no presets or the settings match none (for example after a hand edit). Presets
+    # arrive already completed with the recipe defaults, so equality is a plain comparison.
+    def current_preset
+      presets = @snapshot['environment_presets']
+      current = @snapshot['editable_environment']
+      return nil unless presets.is_a?(Hash) && current.is_a?(Hash) && !current.empty?
+
+      normalized = stringify(current)
+      presets.find { |_name, values| values.is_a?(Hash) && stringify(values) == normalized }&.first&.to_s
+    end
+
+    def stringify(values)
+      values.to_h { |name, value| [name.to_s, value.to_s] }
+    end
+
+    # How long the last run took and how it ended, or nil while one is in progress or when no
+    # total was recorded (interrupted runs, and workspaces set up before totals were persisted).
+    def total
+      seconds = @snapshot['total_seconds']
+      return nil if busy? || !seconds.is_a?(Numeric)
+
+      failed = status == 'error' || steps.any? { |step| step['state'] == 'failed' }
+      { 'state' => failed ? 'failed' : 'complete', 'seconds' => seconds }
+    end
+
+    # What is happening right now, in the quiet line under the headline.
+    def subtitle
+      return nil unless state == 'busy'
+
+      @snapshot['message']
+    end
+
     def title
       return 'Workspace busy' if @snapshot['active'] && !busy_status?
       return @snapshot['message'] || 'Running setup' if status == 'preparing'

data/lib/workspaces/step_log.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Workspaces
+  # Splits a run's output by recipe step.
+  #
+  # Wraps the combined log (a TeeLog, or anything with puts/print). Everything still goes to
+  # the combined log exactly as before; while a step is current, the same text is also written
+  # to that step's own file so the dashboard can show each step under its own heading.
+  #
+  # Text arriving through this object has already been scrubbed by the wrapped log, so we hand
+  # it the raw text and copy what it actually wrote, rather than scrubbing twice.
+  class StepLog
+    def initialize(log, workspace_id)
+      @log = log
+      @workspace_id = workspace_id
+      @file = nil
+    end
+
+    # Begins a step's file, truncating any output from an earlier run of the same step.
+    def begin_step(step_id)
+      finish_step
+      @file = File.open(Config.step_log_path(@workspace_id, step_id), 'w')
+      @file.sync = true
+    end
+
+    def finish_step
+      @file&.close
+      @file = nil
+    end
+
+    def puts(message = '')
+      text = scrubbed(message)
+      @log.puts(message)
+      @file&.puts(text)
+    end
+
+    def print(message)
+      text = scrubbed(message)
+      @log.print(message)
+      @file&.print(text)
+    end
+
+    # Clears every step file; called when a run begins so a restart never shows stale steps.
+    def self.reset(workspace_id)
+      dir = Config.step_logs_dir(workspace_id, create: false)
+      Dir.glob(dir.join('*.log')).each { |path| File.delete(path) } if dir.directory?
+    end
+
+    private
+
+    def scrubbed(message)
+      @log.respond_to?(:scrub_text) ? @log.scrub_text(message) : message.to_s
+    end
+  end
+end

data/lib/workspaces/tee_log.rb

@@ -26,10 +26,16 @@ module Workspaces
       $stdout.print(prefixed(scrubbed))
     end
 
+    # The filtering applied to everything written. Public so StepLog can copy exactly what the
+    # combined log received, instead of reimplementing the rules.
+    def scrub_text(message)
+      @overrides.scrub(message)
+    end
+
     private
 
     def scrub(message)
-      @overrides.scrub(message)
+      scrub_text(message)
     end
 
     def prefixed(message)

data/lib/workspaces/version.rb

@@ -1,3 +1,3 @@
 module Workspaces
-  VERSION = '0.1.10'
+  VERSION = '0.1.12'
 end

data/lib/workspaces/workflow.rb

@@ -3,12 +3,15 @@ require_relative 'recipe'
 require_relative 'command_runner'
 require_relative 'backend'
 require_relative 'environment_overrides'
+require_relative 'step_log'
+require_relative 'duration_format'
 
 module Workspaces
   class Workflow
     def initialize(workspace, log, state: StateStore.new(Config.state_file))
       @workspace = workspace
-      @log = log
+      @combined_log = log
+      @log = StepLog.new(log, workspace.id)
       @state = state
       @backend = Backend.new(workspace.id)
     end
@@ -18,6 +21,7 @@ module Workspaces
       overrides = EnvironmentOverrides.new(@workspace.id).load
       steps = recipe.for_operation(restart: restart)
       publish_steps(steps)
+      StepLog.reset(@workspace.id)
       @backend.stop!
       context = build_context(@backend.reserve!)
       runner = CommandRunner.new(@workspace.path, @log)
@@ -27,6 +31,8 @@ module Workspaces
     rescue StandardError
       @backend.stop!
       raise
+    ensure
+      @log.finish_step
     end
 
     private
@@ -50,6 +56,7 @@ module Workspaces
     def execute(step, recipe, context, runner, overrides)
       started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       progress(step, 'active')
+      @log.begin_step(step.fetch('id'))
       @log.puts "==> #{step.fetch('name')}"
       command = recipe.command(step, context)
       env = recipe.env(step, context, overrides: overrides)
@@ -60,7 +67,10 @@ module Workspaces
         @backend.ensure_alive! if @server_started
       end
       @server_started = true if step['background']
-    rescue StandardError
+    rescue StandardError => e
+      # The reason a step failed is not command output, so the step file would otherwise end
+      # without it. Record it where the step's own accordion can show it.
+      @log.puts "ERROR: #{e.message}"
       finish_step(step, 'failed', started_at)
       raise
     else
@@ -70,7 +80,7 @@ module Workspaces
     def finish_step(step, status, started_at)
       duration = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at).round(3)
       progress(step, status, duration_seconds: duration)
-      @log.puts format('==> %s %s (%.3fs)', step.fetch('name'), status, duration)
+      @log.puts format('==> %s %s (%s)', step.fetch('name'), status, DurationFormat.call(duration))
     end
 
     def progress(step, status, duration_seconds: nil)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.12
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-13 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -83,6 +83,7 @@ files:
 - lib/workspaces/dashboard/styles.css
 - lib/workspaces/dashboard/template.html.erb
 - lib/workspaces/dashboard_view.rb
+- lib/workspaces/duration_format.rb
 - lib/workspaces/environment_overrides.rb
 - lib/workspaces/front_door.rb
 - lib/workspaces/paths.rb
@@ -92,6 +93,7 @@ files:
 - lib/workspaces/recipe.rb
 - lib/workspaces/registry.rb
 - lib/workspaces/state_store.rb
+- lib/workspaces/step_log.rb
 - lib/workspaces/tee_log.rb
 - lib/workspaces/tls.rb
 - lib/workspaces/version.rb