workspaces 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8817ac7615085c4aef7e23b75b8034ac494ad7c2c61b9f53dd14fc79232350cd
-  data.tar.gz: f670f3dbe8ad41cbcc46e29833bd0be27dcd04fcbe48465a78e80a756fc95764
+  metadata.gz: a0102752fa27b9aa9b5fd40ab163411bc9d0411cdfaa00d8a82f6a04088e0099
+  data.tar.gz: 63704204815a6e183e1e244da898defcf67ff3e55b45e69400e19e9f275abaec
 SHA512:
-  metadata.gz: e672a1e9ca5e3186364077718a1ff69851435de0a69e0deadcdeae1ab5715cc8a5acf4e42b17bc8f2639f58a6d6dcb907d10380cda72b59bbebf29d536846de8
-  data.tar.gz: dac093c4058c50a6a8abb863bf61156a88f760768ea5709995ffc800d4654b380305fffc09d3bb6466d19f4ca1ac9a0a85f47a09043c3f9902a66e40012db8b3
+  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/README.md

@@ -121,6 +121,24 @@ and defining them requires no JavaScript edits. Preset keys must be declared in
 `default_editable_env`; recipes reject undeclared keys and secret-like values.
 Hidden environment values are never exposed in the editor or preset choices.
 
+Use `create --branch main --preset Demo` to save a preset for a new, still-idle
+workspace. `start ID --preset Demo` applies it before preparing a stopped
+workspace; `restart ID --preset 'Demo off'` switches a running workspace and
+restarts its server. `prepare ID --preset Demo` switches and rebuilds. An
+unknown name is rejected without changing saved settings. Selecting a preset
+replaces the editable settings (including custom editor lines) but preserves
+hidden legacy overrides. A running workspace requires `restart --preset` or
+`prepare --preset`, not `start --preset`.
+
+For one-off non-secret tweaks, add repeatable `--set NAME=VALUE` and
+`--unset NAME` flags to `create`, `start`, `prepare`, or `restart`. For example,
+`restart ID --preset Demo --set DEMO_FEATURE=on` applies the preset first,
+then the individual changes, and restarts. Without `--preset`, these flags
+patch current editable settings. Names reserved for the runner and names
+suggesting secrets are rejected; values on the command line may be visible
+in process listings and shell history. Use a secret store, not `--set`, for
+credentials.
+
 The front door is not an authentication boundary. Its host and same-origin checks
 protect routing and POST actions, but a publicly reachable instance still needs
 access control such as VPN or SSO. Do not expose workspace backend ports directly.

data/lib/workspaces/cli.rb

@@ -49,6 +49,28 @@ module Workspaces
       options = {}
       OptionParser.new do |parser|
         parse_common_options(parser, options)
+        parser.on('--preset NAME') { |value| options[:preset] = value } if %w(create start prepare restart).include?(command)
+        if %w(create start prepare restart).include?(command)
+          parser.on('--set NAME=VALUE') do |value|
+            name, separator, setting = value.partition('=')
+            raise OptionParser::InvalidArgument, '--set requires NAME=VALUE' if separator.empty?
+            EnvironmentOverrides.validate_name!(name)
+            EnvironmentOverrides.validate_value!(setting)
+            if name.match?(/(?:SECRET|TOKEN|PASSWORD|API_KEY|PRIVATE_KEY|CREDENTIAL)/i)
+              raise OptionParser::InvalidArgument, 'Secret-like names cannot be set on the command line'
+            end
+            options[:set] ||= {}
+            raise OptionParser::InvalidArgument, 'duplicate --set name' if options[:set].key?(name)
+            options[:set][name] = setting
+          end
+          parser.on('--unset NAME') do |value|
+            EnvironmentOverrides.validate_name!(value)
+            if value.match?(/(?:SECRET|TOKEN|PASSWORD|API_KEY|PRIVATE_KEY|CREDENTIAL)/i)
+              raise OptionParser::InvalidArgument, 'Secret-like names cannot be unset on the command line'
+            end
+            (options[:unset] ||= []) << value
+          end
+        end
         parse_tls_options(parser, options) if command == 'serve'
       end.parse!(argv)
       options
@@ -102,7 +124,8 @@ module Workspaces
     end
 
     def create(_id, options)
-      emit(registry.create(**options.slice(:branch, :pr, :new_branch, :from)).describe, options)
+      emit(registry.create(**options.slice(:branch, :pr, :new_branch, :from, :preset),
+                           set: options.fetch(:set, {}), unset: options.fetch(:unset, [])).describe, options)
     end
 
     def list(_id, options)
@@ -114,14 +137,16 @@ module Workspaces
     end
 
     def lifecycle(id, options)
-      action = proc { run_lifecycle(options.fetch(:command), id) }
+      action = proc { run_lifecycle(options.fetch(:command), id, preset: options[:preset],
+                                    set: options.fetch(:set, {}), unset: options.fetch(:unset, [])) }
       result = options[:json] ? with_stdout_on_stderr(&action) : action.call
       emit(result, options)
       raise ArgumentError, result['last_error'] if result['status'] == 'error'
     end
 
-    def run_lifecycle(command, id)
-      started = command == 'restart' ? coordinator.restart(id) : coordinator.start(id, force: command == 'prepare')
+    def run_lifecycle(command, id, preset: nil, set: {}, unset: [])
+      started = command == 'restart' ? coordinator.restart(id, preset: preset, set: set, unset: unset) :
+        coordinator.start(id, force: command == 'prepare', preset: preset, set: set, unset: unset)
       if !started && coordinator.snapshot(id)['active']
         raise ArgumentError, 'Workspace is busy; inspect it with show --json'
       end
@@ -171,8 +196,8 @@ module Workspaces
     end
 
     def usage
-      'Usage: bin/workspaces serve | create (--branch REF | --pr NUMBER | --new-branch NAME [--from REF]) [--json] | ' \
-        'list [--pr NUMBER] [--json] | show/start/prepare/restart/stop ID [--json] | ' \
+      'Usage: bin/workspaces serve | create (--branch REF | --pr NUMBER | --new-branch NAME [--from REF]) [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
+        'list [--pr NUMBER] [--json] | show/start/prepare/restart ID [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | stop ID | ' \
         'exec ID -- COMMAND... | remove ID [--force]'
     end
 

data/lib/workspaces/coordinator.rb

@@ -18,12 +18,12 @@ module Workspaces
       @workers_mutex = Mutex.new
     end
 
-    def start(id, force: false)
-      launch(id, restart: false, force: force)
+    def start(id, force: false, preset: nil, set: {}, unset: [])
+      launch(id, restart: false, force: force, prelaunch: settings_update(id, preset, set, unset))
     end
 
-    def restart(id)
-      launch(id, restart: true, force: true)
+    def restart(id, preset: nil, set: {}, unset: [])
+      launch(id, restart: true, force: true, prelaunch: settings_update(id, preset, set, unset))
     end
 
     def update_environment(id, set:, remove:)
@@ -73,6 +73,14 @@ module Workspaces
 
     private
 
+    def settings_update(id, preset, set, unset)
+      return if !preset && set.empty? && unset.empty?
+
+      lambda do |_workspace|
+        EnvironmentOverrides.new(id).apply_settings(preset: preset, set: set, unset: unset)
+      end
+    end
+
     def resolve_status(id, status, busy)
       return busy ? status : 'interrupted' if ACTIVE.include?(status)
       return status if status == 'error'
@@ -107,6 +115,9 @@ module Workspaces
       lock = acquire_lock(id)
       return false unless lock
 
+      if prelaunch && !restart && !force && Backend.new(id).running?
+        raise ArgumentError, 'Workspace is running; use restart --preset to change its environment'
+      end
       return false if backend_already_running?(id, force, lock)
       prelaunch&.call(workspace)
       publish_starting(id, restart)

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/environment_overrides.rb

@@ -75,6 +75,33 @@ module Workspaces
       load
     end
 
+    def apply_preset(name, recipe: Recipe.new)
+      apply_settings(preset: name, recipe: recipe)
+    end
+
+    def self.settings_for(recipe:, preset: nil, set: {}, unset: [], current: nil)
+      defaults = recipe.default_editable_env
+      preset_values = recipe.environment_presets.fetch(preset) { raise Invalid, "Unknown environment preset: #{preset}" } if preset
+      values = preset ? defaults.merge(preset_values) : (current || defaults).dup
+      validate_entries!(set)
+      unset.each { |name| validate_name!(name) }
+      raise Invalid, 'Cannot set and unset the same name' unless (set.keys & unset).empty?
+      names = set.keys + unset
+      if names.any? { |name| name.match?(/(?:SECRET|TOKEN|PASSWORD|API_KEY|PRIVATE_KEY|CREDENTIAL)/i) }
+        raise Invalid, 'Secret-like environment names cannot be stored in the visible editor'
+      end
+      values.merge!(set)
+      unset.each { |name| values.delete(name) }
+      validate_entries!(values)
+      values
+    end
+
+    def apply_settings(preset: nil, set: {}, unset: [], recipe: Recipe.new)
+      current = preset ? nil : editable_values(recipe.default_editable_env)
+      values = self.class.settings_for(recipe: recipe, preset: preset, set: set, unset: unset, current: current)
+      replace_editable(values.sort.map { |key, value| "#{key}=#{value}" }.join("\n"), defaults: recipe.default_editable_env)
+    end
+
     def apply_patch(set:, remove:)
       validate_patch!(set, remove)
       updated = load_file(file_path).merge(set)

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/registry.rb

@@ -1,6 +1,8 @@
 require_relative 'worktree'
 require_relative 'state_store'
 require_relative 'backend'
+require_relative 'recipe'
+require_relative 'environment_overrides'
 
 module Workspaces
   class Registry
@@ -17,9 +19,12 @@ module Workspaces
       end
     end
 
-    def create(**options)
+    def create(preset: nil, set: {}, unset: [], **options)
+      recipe = Recipe.new if preset || !set.empty? || !unset.empty?
+      EnvironmentOverrides.settings_for(recipe: recipe, preset: preset, set: set, unset: unset) if recipe
       workspace = Worktree.create(**options)
       StateStore.new(Config.state_file).set(workspace.id, 'status' => 'idle', 'related_pr' => workspace.related_pr)
+      EnvironmentOverrides.new(workspace.id).apply_settings(preset: preset, set: set, unset: unset, recipe: recipe) if recipe
       workspace
     end
 

data/lib/workspaces/version.rb

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

metadata

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