workspaces 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0102752fa27b9aa9b5fd40ab163411bc9d0411cdfaa00d8a82f6a04088e0099
-  data.tar.gz: 63704204815a6e183e1e244da898defcf67ff3e55b45e69400e19e9f275abaec
+  metadata.gz: 1974af7e7acc6d19fe556efa4af5e2f9e05635d8df564aa6b3e7e7f8a9096370
+  data.tar.gz: d819cb05a41259c8f9b0c7e49d42155f7b072daa88bd839b44351ddec7445b51
 SHA512:
-  metadata.gz: a6e7e66264833d0b55493fc42203af62be3726ee6d8422d913e00f11afc2b9cf65aaef078e0ac06ecdedbced9c1cd1ff62d37759e1eb7a28295b01908d8bb976
-  data.tar.gz: 2bac52fea92eee837b049d2ce5b24946c0d4f3e306530dd6f4a8aef3e772495725dcdb1d7eec9c4b0b339f54d12948202d725ef609e6c1a2237c470c474276c8
+  metadata.gz: ad1115622e9f3c85fb12c63ba8268161054cca32675a081b6d43b5a11b1b5f1a55c0491a143631277c12aa2d019e10eb228acfcdb26fecce719a45f0336c8f3f
+  data.tar.gz: 236ca0df90dc5e0403fca4d494bcbeabf90117aabbd12c12175d3eecf4d2475fc36e432430e3ece7c61c651188c234daeef041ed148812d80ef71e983fda5afe

data/README.md

@@ -143,6 +143,64 @@ The front door is not an authentication boundary. Its host and same-origin check
 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.
 
+### Proxy middleware
+
+The front door can run Rack middleware around traffic that is forwarded to a workspace
+backend. The gem knows nothing about what a middleware does: the container or host
+that runs `serve` registers its own. Typical uses are injecting a script tag, adding a
+header, or logging.
+
+```ruby
+# my_middleware.rb
+Workspaces.configure_proxy do
+  use MyMiddleware, option: 'value'
+end
+```
+
+Load it with `serve --require FILE` (repeatable) or by setting `WORKSPACES_REQUIRE` to
+one or more paths separated like `PATH` entries. Environment entries load first, then
+`--require` files in order. A missing file or an error while loading stops `serve` with
+a non-zero exit instead of silently running without it. These files are executed with
+the front door's privileges, so only name files the operator controls. With nothing
+registered, the front door behaves exactly as before.
+
+Blocks run in registration order and the first `use` is outermost. The stack wraps only
+the step that forwards a request to a ready workspace backend. The dashboard, redirects
+for workspaces that are not ready, and error pages never pass through it. For each
+proxied request, two Rack env keys are available:
+
+| Key | Value |
+| --- | --- |
+| `workspaces.workspace_id` | The workspace ID, such as `main-1ae4815f` |
+| `workspaces.workspace` | The workspace snapshot hash (branch, status, related PR, and so on) |
+
+Two details matter when rewriting response bodies. The proxy passes the browser's
+`Accept-Encoding` to the backend, so a compressed response arrives compressed; set
+`env['HTTP_ACCEPT_ENCODING'] = 'identity'` before calling the app, or skip responses
+with a `Content-Encoding` header. If you change the body, drop the stale `Content-Length`
+header. An example that appends a script tag to HTML pages:
+
+```ruby
+class ScriptInjector
+  TAG = '<script src="https://example.test/widget.js" data-thread-id="%<id>s"></script>'
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    env['HTTP_ACCEPT_ENCODING'] = 'identity'
+    status, headers, body = @app.call(env)
+    return [status, headers, body] unless headers['content-type'].to_s.start_with?('text/html')
+
+    html = body.each.to_a.join.sub('</body>', format(TAG, id: env['workspaces.workspace_id']) + '</body>')
+    [status, headers.reject { |key, _| key.casecmp?('content-length') }, [html]]
+  end
+end
+
+Workspaces.configure_proxy { use ScriptInjector }
+```
+
 ### Local HTTPS
 
 To serve TLS directly, install/trust a local CA and create a certificate covering
@@ -198,6 +256,7 @@ and forwarded scheme/host headers; it does not change the internal listener to T
 | `WORKSPACES_PUBLIC_ORIGIN` | `http://localhost:4747` | Browser-facing dashboard origin and scheme |
 | `WORKSPACES_BASE_DOMAIN` | `localhost` | Preview hostname suffix |
 | `WORKSPACES_SUBDOMAIN_PREFIX` | `ws-` | Prefix before the workspace ID on preview hosts |
+| `WORKSPACES_REQUIRE` | none | Ruby files, separated like `PATH`, loaded by `serve` to register proxy middleware |
 
 Keep the project root, public origin, preview domain, and storage settings consistent
 across CLI and server processes. Changing the browser-facing origin requires restarting

data/lib/workspaces/cli.rb

@@ -5,6 +5,7 @@ require 'rack/handler/puma'
 require_relative 'registry'
 require_relative 'coordinator'
 require_relative 'front_door'
+require_relative 'proxy_middleware'
 require_relative 'tls'
 require_relative 'child_env'
 
@@ -86,6 +87,7 @@ module Workspaces
     end
 
     def parse_tls_options(parser, options)
+      parser.on('--require PATH') { |value| (options[:require] ||= []) << value }
       parser.on('--secure') { options[:secure] = true }
       parser.on('--tls-cert PATH') { |value| options[:tls_cert] = value }
       parser.on('--tls-key PATH') { |value| options[:tls_key] = value }
@@ -93,6 +95,7 @@ module Workspaces
 
     def serve(_id, options)
       tls = Tls.from_serve_options(options)&.validate!
+      ProxyMiddleware.load_files(ProxyMiddleware.env_paths + options.fetch(:require, []))
 
       if tls
         tls.apply_env_defaults { serve_with_tls(tls) }
@@ -196,7 +199,7 @@ module Workspaces
     end
 
     def usage
-      'Usage: bin/workspaces serve | create (--branch REF | --pr NUMBER | --new-branch NAME [--from REF]) [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
+      'Usage: bin/workspaces serve [--require FILE] | 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/dashboard/pull_request.html.erb

@@ -1,6 +1,6 @@
 <main class="dashboard">
   <header class="dashboard__header">
-    <div><p class="eyebrow">PR preview</p><h1>PR #<%= escape(@number) %></h1></div>
+    <div class="dashboard__title"><p class="eyebrow">PR preview</p><h1>PR #<%= escape(@number) %></h1></div>
     <a href="/workspaces" class="button button--subtle">All workspaces</a>
   </header>
   <% unless @workspaces.empty? %>
@@ -8,7 +8,7 @@
       <h2 id="existing-heading"><%= @workspaces.one? ? 'Continue in your workspace' : 'Choose a workspace' %></h2>
       <p>Open an existing workspace to view its status, run it, or continue working.</p>
       <% @workspaces.each do |workspace| %>
-        <article>
+        <article class="stack stack--tight">
           <h3><%= escape(workspace.fetch('id')) %></h3>
           <p><%= escape(workspace['branch']) %></p>
           <a href="/workspaces/<%= escape(workspace.fetch('id')) %>" class="button button--primary" aria-label="Open workspace <%= escape(workspace.fetch('id')) %>">Open workspace</a>
@@ -24,11 +24,13 @@
     <details class="status-panel">
       <summary>Create another workspace</summary>
   <% end %>
+    <div class="stack">
     <p>Create a fresh workspace from the PR's current head and start its server. Existing workspaces and edits stay untouched.</p>
     <form method="post" action="/pr/<%= escape(@number) %>">
       <button class="button <%= @workspaces.empty? ? 'button--primary' : 'button--subtle' %>">Create and start workspace</button>
     </form>
     <p class="muted">Creation fetches the PR. Repository setup steps continue on the workspace dashboard.</p>
+    </div>
   <% if @workspaces.empty? %>
     </section>
   <% else %>

data/lib/workspaces/dashboard/styles.css

@@ -17,27 +17,51 @@
   --space-5: 20px;
   --space-6: 24px;
   --space-8: 32px;
+  --space-10: 40px;
+  --panel-padding: var(--space-6);
 }
 
 * {
   box-sizing: border-box;
 }
 
+/* Vertical rhythm: browsers ship per-element default margins, so spacing depended on
+   which tag was used. Reset them once; every gap is declared by a stack rule below
+   using the --space-* scale. */
+h1, h2, h3, h4, p, ul, ol, dl, dd, pre, fieldset, figure { margin: 0; }
+ol, ul { padding-inline-start: var(--space-6); }
+legend { padding: 0; }
+
+/* A stack separates its direct children by one step of the scale. Four steps only:
+     tight  8px  label and control, control and its help text
+     snug  12px  heading and its content, tightly related groups
+     block 16px  blocks inside a panel (the default)
+     loose 24px  panels on a page, and panel padding
+   Grid gaps skip [hidden] and out-of-flow children, so toggling sections never leaves
+   a stray gap behind (margins on siblings would). */
+.stack { display: grid; gap: var(--space-4); align-content: start; }
+.stack--tight { gap: var(--space-2); }
+.stack--snug { gap: var(--space-3); }
+.stack--loose { gap: var(--space-6); }
+
 [hidden] { display: none !important; }
 input { max-width: 100%; padding: var(--space-2); color: var(--text); background: var(--bg); border: 1px solid var(--border); border-radius: var(--space-1); }
 input:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 textarea:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 summary { cursor: pointer; color: var(--muted); }
 summary:focus-visible { outline: 2px solid var(--accent); outline-offset: 4px; }
-.workspace-actions { display: flex; flex-wrap: wrap; gap: var(--space-3); margin-block-start: var(--space-4); }
-.setup-error { margin-block-start: var(--space-5); border-color: var(--danger); }
+.workspace-actions { display: flex; flex-wrap: wrap; gap: var(--space-3); }
+/* The server-rendered action forms live in a wrapper; let them flow with the sibling button. */
+#actions { display: contents; }
+.setup-error { --panel-padding: var(--space-4); padding: var(--panel-padding); border-color: var(--danger); box-shadow: none; }
 .setup-error h3 { color: var(--danger); margin-block-start: 0; }
 .step-outcome { margin-inline-start: auto; font-size: 12px; }
 .activity-dot { display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: var(--accent); animation: workspace-pulse 1.5s infinite; }
 @keyframes workspace-pulse { 50% { opacity: 0.3; } }
 @media (prefers-reduced-motion: reduce) { .activity-dot { animation: none; } }
 dd, h1, code { overflow-wrap: anywhere; }
-dd { margin-inline-start: 0; margin-block-end: var(--space-3); }
+dt + dd { margin-block-start: var(--space-1); }
+dd + dt { margin-block-start: var(--space-3); }
 #log { max-height: 400px; overflow: auto; white-space: pre-wrap; overflow-wrap: anywhere; }
 
 body {
@@ -69,7 +93,7 @@ a {
 }
 
 .eyebrow {
-  margin: 0 0 var(--space-1);
+  margin: 0;
   color: var(--muted);
   font-size: 12px;
   letter-spacing: 0.08em;
@@ -87,6 +111,11 @@ h1 {
   color: var(--muted);
 }
 
+.dashboard__title {
+  display: grid;
+  gap: var(--space-1);
+}
+
 .header-actions {
   display: flex;
   gap: var(--space-3);
@@ -100,13 +129,30 @@ h1 {
   background: var(--bg-elevated);
   border: 1px solid var(--border);
   border-radius: var(--radius);
-  padding: var(--space-5);
+  padding: var(--panel-padding);
   box-shadow: var(--shadow);
 }
 
-.status-row {
+/* Disclosure panels keep their native layout; only the open state adds spacing below. */
+.status-panel:not(details),
+.controls-panel,
+.error-panel,
+.log-panel,
+.noscript-note {
   display: grid;
   gap: var(--space-4);
+  align-content: start;
+}
+
+.error-panel,
+.log-panel,
+.danger-zone { gap: var(--space-3); }
+
+details.status-panel[open] > summary { margin-block-end: var(--space-4); }
+
+.status-row {
+  display: grid;
+  gap: var(--space-2) var(--space-4);
   grid-template-columns: repeat(auto-fit, minmax(min(180px, 100%), 1fr));
 }
 
@@ -152,7 +198,7 @@ h1 {
 }
 
 .stepper {
-  margin: var(--space-5) 0 0;
+  margin: 0;
   padding: 0;
   list-style: none;
   display: grid;
@@ -217,7 +263,7 @@ h1 {
   margin: 0;
   padding: var(--space-4);
   display: grid;
-  gap: var(--space-3);
+  gap: var(--space-4);
 }
 
 .env-legend {
@@ -226,16 +272,9 @@ h1 {
   padding-inline: var(--space-2);
 }
 
-.env-input-label {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--space-2);
-  font-size: 14px;
-}
-
 .env-input-label {
   display: block;
-  margin-block-end: var(--space-1);
+  font-size: 14px;
 }
 
 .env-fieldset textarea {
@@ -265,31 +304,21 @@ fieldset:disabled {
 }
 
 .controls-panel {
-  display: grid;
-  gap: var(--space-4);
   align-items: start;
 }
 
-.controls-panel h2,
-.controls-panel h3 {
-  margin: 0;
-}
-
 .workspace-actions-group,
 .workspace-settings {
   display: grid;
   gap: var(--space-3);
 }
 
-.workspace-settings {
+/* The divider only separates two groups: skip it when settings is the only one showing. */
+.workspace-actions-group:not([hidden]) + .workspace-settings {
   border-top: 1px solid var(--border);
   padding-top: var(--space-4);
 }
 
-.workspace-actions {
-  margin-block-start: 0;
-}
-
 .workspace-actions .button,
 .workspace-actions form {
   margin: 0;
@@ -312,6 +341,7 @@ fieldset:disabled {
 }
 
 .button {
+  justify-self: start;
   display: inline-flex;
   justify-content: center;
   align-items: center;
@@ -361,10 +391,25 @@ fieldset:disabled {
 .button:disabled { opacity: 0.55; cursor: not-allowed; transform: none; }
 
 .danger-zone { border-color: var(--danger); }
-.danger-zone h2 { margin-block-start: 0; color: var(--danger); }
+.danger-zone h2 { color: var(--danger); }
 .danger-zone form { display: grid; justify-items: start; gap: var(--space-3); }
-.workspace-list { list-style: none; padding: 0; display: grid; gap: var(--space-3); }
-.workspace-list__item { display: grid; gap: var(--space-1); padding-block: var(--space-3); border-block-end: 1px solid var(--border); overflow-wrap: anywhere; }
+
+.workspace-table { inline-size: 100%; border-collapse: collapse; }
+.workspace-table th,
+.workspace-table td { padding: var(--space-3) var(--space-4); text-align: start; vertical-align: middle; border-block-end: 1px solid var(--border); overflow-wrap: anywhere; }
+.workspace-table th:first-child,
+.workspace-table td:first-child { padding-inline-start: 0; }
+.workspace-table th:last-child,
+.workspace-table td:last-child { padding-inline-end: 0; }
+.workspace-table thead th { padding-block-start: 0; color: var(--muted); font-size: 12px; font-weight: 600; letter-spacing: 0.08em; text-transform: uppercase; }
+.workspace-table tbody tr:last-child > * { padding-block-end: 0; border-block-end: 0; }
+.workspace-table tbody th { font-weight: 600; }
+.workspace-table__date { color: var(--muted); font-size: 13px; white-space: nowrap; }
+
+.field { display: grid; gap: var(--space-2); max-inline-size: 28rem; font-size: 14px; }
+.field input { inline-size: 100%; }
+
+ol:not(.stepper) > li + li { margin-block-start: var(--space-2); }
 
 .button--success {
   background: color-mix(in oklab, var(--success) 22%, transparent);
@@ -379,11 +424,12 @@ fieldset:disabled {
 
 .error-panel h2,
 .log-panel h2 {
-  margin: 0 0 var(--space-3);
+  margin: 0;
   font-size: 1rem;
 }
 
 .error-panel pre,
+.status-panel pre,
 .log-panel pre {
   margin: 0;
   padding: var(--space-3);
@@ -408,14 +454,12 @@ fieldset:disabled {
   justify-content: space-between;
   align-items: baseline;
   gap: var(--space-3);
-  margin-block-end: var(--space-3);
 }
 
 .log-switch {
   display: flex;
   flex-wrap: wrap;
   gap: var(--space-2);
-  margin-block-end: var(--space-3);
 }
 
 .log-switch a {
@@ -450,7 +494,9 @@ fieldset:disabled {
   display: none !important;
 }
 
-.visually-hidden {
+.visually-hidden,
+[role='status']:empty,
+[aria-live]:empty {
   position: absolute !important;
   inline-size: 1px;
   block-size: 1px;
@@ -461,7 +507,22 @@ fieldset:disabled {
   border: 0;
 }
 
+p:empty:not([role]):not([aria-live]) { display: none; }
+
 @media (max-width: 640px) {
+  /* Stack each row: workspace, then status. Dates are desktop-only detail. */
+  .workspace-table,
+  .workspace-table tbody { display: block; }
+  .workspace-table thead,
+  .workspace-table th.workspace-table__date,
+  .workspace-table td.workspace-table__date { display: none; }
+  .workspace-table tr { display: grid; gap: var(--space-1); padding-block: var(--space-3); border-block-end: 1px solid var(--border); }
+  .workspace-table tbody tr:first-child { padding-block-start: 0; }
+  .workspace-table tbody tr:last-child { padding-block-end: 0; border-block-end: 0; }
+  .workspace-table th,
+  .workspace-table td { display: block; padding: 0; border: 0; }
+  .workspace-table tbody tr:last-child > * { padding-block-end: 0; }
+
   .dashboard {
     inline-size: min(100% - var(--space-4), 960px);
     padding-block: var(--space-6);
@@ -472,7 +533,8 @@ fieldset:disabled {
   .error-panel,
   .log-panel,
   .noscript-note {
-    padding: var(--space-4);
+    --panel-padding: var(--space-4);
+    padding: var(--panel-padding);
   }
 
   .log-header {

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

@@ -1,6 +1,6 @@
 <main class="dashboard" id="workspace" data-id="<%= @id %>" data-status="<%= field('status') %>" data-started="<%= field('prepare_started_at') %>" data-completed="<%= field('completed_at') %>" data-busy="<%= @presentation['busy'] %>">
   <header class="dashboard__header">
-    <div><p class="eyebrow">Managed workspace</p><h1><%= @id %></h1><p><%= field('branch') %></p></div>
+    <div class="dashboard__title"><p class="eyebrow">Managed workspace</p><h1><%= @id %></h1><p class="muted"><%= field('branch') %></p></div>
     <a class="button button--subtle" href="/workspaces">All workspaces</a>
   </header>
   <section class="status-panel" aria-labelledby="status">
@@ -32,11 +32,11 @@
     </div>
     <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) %>">
+      <form method="post" action="/workspaces/<%= @id %>/environment" id="environment-form" class="stack" 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>
           <% unless environment_presets.empty? %>
-            <div data-preset-controls hidden>
+            <div class="stack stack--tight" data-preset-controls hidden>
               <p class="env-input-label" id="environment-preset-label">Preset</p>
               <div class="env-preset-buttons" role="group" aria-labelledby="environment-preset-label" aria-describedby="environment-preset-help">
                 <% environment_presets.each_key do |name| %>
@@ -46,8 +46,10 @@
               <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>
+          <div class="stack stack--tight">
+            <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>
+          </div>
         </fieldset>
         <div class="env-actions">
           <button class="button button--primary" data-env-submit <%= 'disabled' if @presentation['busy'] %>><%= escape(@presentation['environment_submit']) %></button>

data/lib/workspaces/dashboard_view.rb

@@ -15,16 +15,16 @@ module Workspaces
         <main class="dashboard"><header class="dashboard__header"><h1>Workspaces</h1></header>
         <section class="status-panel"><h2>Create workspace</h2>
         <p>Choose a branch, PR number, or new branch. Every submission creates a separate managed worktree.</p>
-        <form method="post" action="/workspaces/create">
-          <p><label>Existing branch <input name="branch" placeholder="main"></label></p>
-          <p><label>PR number <input name="pr" inputmode="numeric" placeholder="43828"></label></p>
-          <p><label>New branch <input name="new_branch" placeholder="agent/fix-checkout"></label></p>
-          <p><label>Start new branch from <input name="from" placeholder="HEAD"></label></p>
+        <form method="post" action="/workspaces/create" class="stack">
+          <label class="field">Existing branch <input name="branch" placeholder="main"></label>
+          <label class="field">PR number <input name="pr" inputmode="numeric" placeholder="43828"></label>
+          <label class="field">New branch <input name="new_branch" placeholder="agent/fix-checkout"></label>
+          <label class="field">Start new branch from <input name="from" placeholder="HEAD"></label>
           <button class="button button--primary">Create workspace</button>
         </form></section>
-        <section class="status-panel"><h2>Managed workspaces</h2><ul class="workspace-list">
-        #{workspaces.map { |workspace| view.inventory_item(workspace) }.join}
-        </ul></section></main>
+        <section class="status-panel"><h2>Managed workspaces</h2>
+        #{view.inventory_table(workspaces)}
+        </section></main>
       HTML
     end
 
@@ -90,17 +90,33 @@ module Workspaces
       ERB::Util.html_escape(value.to_s)
     end
 
-    def inventory_item(workspace)
+    # Tabular data gets a real table. The workspace ID is both the row header and the
+    # link, so no separate name/branch/link columns are needed. Narrow screens hide the
+    # date columns and stack each row (see styles.css).
+    def inventory_table(workspaces)
+      return '<p class="muted">No workspaces yet.</p>' if workspaces.empty?
+
+      <<~HTML
+        <table class="workspace-table">
+          <thead><tr><th scope="col">Workspace</th><th scope="col">Status</th><th scope="col" class="workspace-table__date">Created</th><th scope="col" class="workspace-table__date">Last startup</th></tr></thead>
+          <tbody>
+        #{workspaces.map { |workspace| inventory_row(workspace) }.join}
+          </tbody>
+        </table>
+      HTML
+    end
+
+    def inventory_row(workspace)
       id = escape(Config.validate_id!(workspace.fetch('id')))
+      status = escape(workspace['status'] || 'idle')
       running = workspace['running'] ? 'Running' : 'Not running'
       <<~HTML
-        <li class="workspace-list__item">
-          <a href="/workspaces/#{id}">#{id}</a>
-          <span class="muted">#{escape(workspace['branch'])}</span>
-          <span>#{running} · #{escape(workspace['status'] || 'idle')}#{workspace['active'] ? ' (busy)' : ''}</span>
-          <span class="muted">Created <time datetime="#{escape(workspace['created_at'])}">#{escape(workspace['created_at'] || 'Unavailable')}</time></span>
-          <span class="muted">Last startup <time datetime="#{escape(workspace['started_at'])}">#{escape(workspace['started_at'] || 'Never')}</time></span>
-        </li>
+        <tr>
+          <th scope="row"><a href="/workspaces/#{id}">#{id}</a></th>
+          <td><span class="status-pill" data-status="#{status}"><span class="status-dot" aria-hidden="true"></span>#{running} · #{status}#{workspace['active'] ? ' (busy)' : ''}</span></td>
+          <td class="workspace-table__date"><time datetime="#{escape(workspace['created_at'])}">#{escape(workspace['created_at'] || 'Unavailable')}</time></td>
+          <td class="workspace-table__date"><time datetime="#{escape(workspace['started_at'])}">#{escape(workspace['started_at'] || 'Never')}</time></td>
+        </tr>
       HTML
     end
 

data/lib/workspaces/front_door.rb

@@ -5,15 +5,22 @@ require 'net/http'
 require_relative 'coordinator'
 require_relative 'dashboard_view'
 require_relative 'environment_overrides'
+require_relative 'proxy_middleware'
 
 module Workspaces
   class FrontDoor
     WORKSPACE_ROUTE = %r{\A/workspaces/([a-z0-9]+(?:-[a-z0-9]+)*)
                           (?:/(status|start|prepare|restart|stop|remove|update-pr|environment))?\z}x
 
+    # Rack env keys set on requests that reach a ready workspace backend, for use by
+    # middleware registered with Workspaces.configure_proxy.
+    WORKSPACE_ID_ENV = 'workspaces.workspace_id'.freeze
+    WORKSPACE_ENV = 'workspaces.workspace'.freeze
+
     def initialize(coordinator: Coordinator.new, registry: Registry.new)
       @coordinator = coordinator
       @registry = registry
+      @forwarder = ProxyMiddleware.build(method(:forward_to_backend))
     end
 
     def call(env)
@@ -230,7 +237,9 @@ module Workspaces
       snapshot = @coordinator.snapshot(id, include_log: false)
       return unavailable(id, request) unless snapshot['status'] == 'ready' && !snapshot['active']
 
-      forward(id, request)
+      request.env[WORKSPACE_ID_ENV] = id
+      request.env[WORKSPACE_ENV] = snapshot
+      @forwarder.call(request.env)
     rescue IOError, SystemCallError, Timeout::Error => e
       response(502, "Workspace backend unavailable: #{e.class}")
     end
@@ -241,6 +250,11 @@ module Workspaces
       response(503, "Workspace not ready. Visit #{Config.dashboard_url(id)}")
     end
 
+    # Innermost app of the proxy stack: sends the request to the workspace backend.
+    def forward_to_backend(env)
+      forward(env.fetch(WORKSPACE_ID_ENV), Rack::Request.new(env))
+    end
+
     def forward(id, request)
       uri = URI("http://127.0.0.1:#{Backend.new(id).port}#{request.fullpath}")
       upstream = upstream_request(id, request, uri)

data/lib/workspaces/proxy_middleware.rb

@@ -0,0 +1,77 @@
+require 'rack'
+
+module Workspaces
+  # Adds a Rack middleware stack around workspace preview traffic.
+  #
+  # The gem stays unaware of what any middleware does: the process hosting the front
+  # door registers its own, for example from a file named by WORKSPACES_REQUIRE:
+  #
+  #   Workspaces.configure_proxy do
+  #     use MyMiddleware, option: 'value'
+  #   end
+  #
+  # Blocks are replayed in registration order into a Rack::Builder, so the first
+  # `use` is the outermost middleware. The stack wraps only the step that forwards a
+  # request to a ready workspace backend. The dashboard, redirects for workspaces that
+  # are not ready, and error responses never pass through it.
+  module ProxyMiddleware
+    ENV_VAR = 'WORKSPACES_REQUIRE'
+
+    # Raised for unusable configuration; the CLI reports it and exits non-zero.
+    class ConfigurationError < ArgumentError; end
+
+    @blocks = []
+
+    def self.register(&block)
+      raise ConfigurationError, 'Workspaces.configure_proxy requires a block' unless block
+
+      @blocks << block
+      self
+    end
+
+    def self.any?
+      !@blocks.empty?
+    end
+
+    def self.reset!
+      @blocks.clear
+    end
+
+    # Returns the endpoint untouched when nothing is registered, so an unconfigured
+    # front door behaves exactly as it did before this seam existed.
+    def self.build(endpoint)
+      blocks = @blocks.dup
+      return endpoint if blocks.empty?
+
+      Rack::Builder.new do
+        blocks.each { |block| instance_exec(&block) }
+        run endpoint
+      end.to_app
+    end
+
+    # Paths from WORKSPACES_REQUIRE, separated like PATH entries.
+    def self.env_paths
+      ENV.fetch(ENV_VAR, '').split(File::PATH_SEPARATOR).map(&:strip).reject(&:empty?)
+    end
+
+    # Executes the given Ruby files so they can register middleware. These files run
+    # with the privileges of the front door; only name files the operator controls.
+    def self.load_files(paths)
+      paths.each do |path|
+        full_path = File.expand_path(path)
+        raise ConfigurationError, "Proxy middleware file not found: #{path}" unless File.file?(full_path)
+
+        begin
+          require full_path
+        rescue ScriptError, StandardError => e
+          raise ConfigurationError, "Could not load proxy middleware #{path}: #{e.class}: #{e.message}"
+        end
+      end
+      paths
+    end
+  end
+
+  def self.configure_proxy(&block)
+    ProxyMiddleware.register(&block)
+  end
+end

data/lib/workspaces/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -88,6 +88,7 @@ files:
 - lib/workspaces/paths.rb
 - lib/workspaces/port_allocator.rb
 - lib/workspaces/presentation.rb
+- lib/workspaces/proxy_middleware.rb
 - lib/workspaces/recipe.rb
 - lib/workspaces/registry.rb
 - lib/workspaces/state_store.rb