workspaces 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 431b59c0d2a5bef3dc7a2456416d865992ac05664b371bbf6245bb7d5ae3a3b4
+  data.tar.gz: 88526e06c47837b47e6b507df9ecaf48cd4656365427cf9a7922bcf3fefcff52
+SHA512:
+  metadata.gz: 3ce730d1d8d81bfd3e2f997c867623b3f8936b6861a441abec837e38b3ab6098371c0a1e800e8934eccfa651af0f33c81d93e7d0764543bacadb48df3f5cd6b2
+  data.tar.gz: 489216342c60ff24c9455c41e43cc05753f396c18ac690f051cada947c01b06d97af40123b75bf639cb51d394499e90d20cc37a69884f70bedbbe1ecc0baa9bb

data/DESIGN.md

@@ -0,0 +1,67 @@
+# Managed Workspace Dashboard Design Tokens
+
+## Scope
+
+Workspace list/create screen and per-workspace setup/status screen. Workspace identity is independent of PR provenance.
+
+GET is read-only. All creation and lifecycle controls submit same-origin POST forms. No source-reset or cleanup button exists. Workspace IDs, branches and filesystem paths wrap on narrow screens. Native labelled inputs and buttons are keyboard accessible; polling announces status without replacing form focus or making the entire log an ARIA live region.
+
+## Visual direction
+
+Restrained tooling UI: dark elevated panels, compact spacing rhythm, clear status affordances, and no decorative animation.
+
+## Tokens used
+
+### Color
+
+- `--bg`: shell background
+- `--bg-elevated`: panel surface
+- `--border`: panel/control borders
+- `--text`: primary text
+- `--muted`: secondary/supporting text
+- `--accent`: active status and primary action
+- `--success`: completed/ready states
+- `--danger`: failed/error states
+- `--warning`: retry/connection warning text
+
+### Radius and depth
+
+- `--radius`: 12px panel corners
+- `--shadow`: single elevated panel shadow
+
+### Spacing scale
+
+- `--space-1` to `--space-8` (4px base multiples)
+
+### Typography
+
+- System sans stack for body/content
+- System mono stack for logs/error text
+
+## Component primitives
+
+- **Creation form**: labelled branch, PR, and new-branch inputs with a primary create action
+- **Status pill**: current workspace status as text
+- **Setup progress**: names and ordered states come from repository run steps; failures are highlighted. Restart shows the background launch and later readiness commands.
+- **Actions by state**: idle/stopped offers Start; active operations show progress without lifecycle buttons; failure offers Retry; ready offers Open workspace plus rebuild/restart/stop.
+- **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.
+- **Action buttons**: start, prepare/rebuild, restart server, stop server, and refresh
+- **Open workspace**: success-styled link available when the server is ready
+- **Lifecycle controls**: disabled while busy; 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.
+
+## Accessibility constraints
+
+- Semantic sections/headings for all regions
+- Focus-visible outlines on actionable controls
+- `aria-live` limited to phase-change and connection warnings (not full log stream)
+- No-JS refresh path always available
+
+## Responsive behavior
+
+- Single-column layout with intrinsic grid sections
+- Panel padding compresses at <=640px
+- No horizontal scrolling expected at 375px viewport

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 G2 Engineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+# Workspaces
+
+Workspaces is a Ruby gem for managed Git worktrees, lifecycle commands, and browser previews.
+It runs independently of Rails. Each project supplies its own `.workspaces.yml` recipe and
+any setup or readiness scripts that recipe calls. Workspace state and logs are stored outside
+the project under `WORKSPACES_HOME`.
+
+## Usage
+
+Install the gem in your project's bundle:
+
+```ruby
+# Gemfile
+gem 'workspaces'
+```
+
+```sh
+bundle install
+bundle exec workspaces help
+bundle exec workspaces create --branch main --json
+bundle exec workspaces start <workspace-id> --json
+```
+
+Or install it into your Ruby environment without Bundler:
+
+```sh
+gem install workspaces
+workspaces help
+```
+
+Run the commands from the project containing `.workspaces.yml`, or set
+`WORKSPACES_REPO_ROOT` to its absolute path. The gem executable does not load Rails.
+Gem installation requires a published release; until then, a project may reference a
+tagged Git revision in its Gemfile instead of the RubyGems release.
+
+`create` makes a managed worktree but does not start the application. `start` runs the
+project's `.workspaces.yml` steps, starts its background server, and waits for readiness.
+The returned JSON includes the workspace ID, dashboard URL, and preview URL. You can also
+create from a pull request with `create --pr NUMBER`, or create a new branch with
+`create --new-branch NAME --from REF`. Run `help` for lifecycle and other commands.
+
+## Serve the dashboard and previews
+
+Run `serve` in a separate terminal using the **same project root and `WORKSPACES_HOME`**
+as `create` and `start`:
+
+```sh
+bundle exec workspaces serve
+```
+
+For a global installation, omit `bundle exec` in every example.
+
+By default, the front door listens on `127.0.0.1:4747`. Open
+`http://localhost:4747/workspaces` for the dashboard. Preview URLs use
+`http://ws-<workspace-id>.localhost:4747/`. Make sure the wildcard preview hosts
+resolve to the machine running the front door; a DNS entry or local resolver may be
+needed on your system. Set `WORKSPACES_BASE_DOMAIN` and
+`WORKSPACES_SUBDOMAIN_PREFIX` to choose a different preview hostname pattern.
+
+The front door is a reverse proxy. It accepts the dashboard host for workspace status
+and lifecycle actions, recognizes `ws-<workspace-id>` preview hosts, checks that the
+workspace is ready, and forwards requests (including cookies) to that workspace's
+server on a reserved `127.0.0.1` port in the `30000–30999` range. The recipe's
+`background: true` step must start the application on `127.0.0.1:$WORKSPACE_PORT`;
+the following foreground readiness step must verify it is *this* boot (the runner
+provides `WORKSPACE_RUN_ID`). The runner also supplies `WORKSPACE_URL` and
+`WORKSPACE_HOST` for applications that need browser-facing URLs and host settings.
+`serve` does **not** start workspace backends; use `start` or `restart` for those.
+
+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.
+
+### Local HTTPS
+
+To serve TLS directly, install/trust a local CA and create a certificate covering
+`workspaces.localhost` and `*.workspaces.localhost`. For example, with `mkcert`:
+
+```sh
+mkcert -install
+mkdir -p ~/.workspaces/certs
+mkcert -cert-file ~/.workspaces/certs/workspaces.pem \
+  -key-file ~/.workspaces/certs/workspaces-key.pem \
+  workspaces.localhost '*.workspaces.localhost'
+chmod 600 ~/.workspaces/certs/workspaces-key.pem
+```
+
+Keep the private key out of Git and readable only by the service user. Then run:
+
+```sh
+bundle exec workspaces serve --secure
+```
+
+Without explicit settings, `--secure` serves the dashboard at
+`https://workspaces.localhost:4747/workspaces` and previews at
+`https://ws-<workspace-id>.workspaces.localhost:4747/`. The shortcut sets these
+host/origin defaults **only in the `serve` process**. For correct URLs in separate
+`create`, `show`, `start`, or `restart` invocations, export the same settings there:
+
+```sh
+export WORKSPACES_PUBLIC_ORIGIN=https://workspaces.localhost:4747
+export WORKSPACES_BASE_DOMAIN=workspaces.localhost
+```
+
+Alternatively, pass both `--tls-cert PATH` and `--tls-key PATH` to `serve`, and set
+`WORKSPACES_PUBLIC_ORIGIN` to an HTTPS origin and `WORKSPACES_BASE_DOMAIN` to the
+matching preview domain. TLS startup fails for missing, unreadable, invalid, or
+mismatched files; it does not fall back to HTTP. TLS flags apply to `serve` only.
+
+### HTTPS behind a reverse proxy
+
+When an ingress terminates HTTPS, keep the front door on HTTP internally. Set
+`WORKSPACES_BIND=0.0.0.0` if it must listen outside the container, set
+`WORKSPACES_PUBLIC_ORIGIN` to the external HTTPS dashboard origin, and set
+`WORKSPACES_BASE_DOMAIN` to the domain used for preview hosts. Route both the
+dashboard hostname and the wildcard preview hostnames to the front door, **preserving
+the original Host header**. The configured public origin determines generated URLs
+and forwarded scheme/host headers; it does not change the internal listener to TLS.
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `WORKSPACES_REPO_ROOT` | Nearest ancestor Git checkout with `.workspaces.yml` | Trusted recipe and source repository |
+| `WORKSPACES_HOME` | `~/.workspaces/<repository-path-hash>` | Per-project worktrees, state, locks, and logs |
+| `WORKSPACES_BIND` | `127.0.0.1` | Front-door bind address |
+| `WORKSPACES_PORT` | `4747` | Front-door listener port |
+| `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 |
+
+Keep the project root, public origin, preview domain, and storage settings consistent
+across CLI and server processes. Changing the browser-facing origin requires restarting
+workspace backends that need updated `WORKSPACE_URL` or `WORKSPACE_HOST` values.
+
+## Development
+
+Use Ruby 3.3.10. To run the standalone test suite from a source checkout, install and
+use its test bundle:
+
+```sh
+BUNDLE_GEMFILE=Gemfile.test bundle install
+BUNDLE_GEMFILE=Gemfile.test bundle exec rspec spec/workspaces
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/exe/workspaces

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'workspaces'
+
+exit Workspaces::Cli.run(ARGV)

data/lib/workspaces/backend.rb

@@ -0,0 +1,108 @@
+require 'timeout'
+require 'securerandom'
+require 'time'
+require_relative 'config'
+require_relative 'state_store'
+require_relative 'port_allocator'
+
+module Workspaces
+  class Backend
+    class BootFailedError < StandardError; end
+    attr_reader :workspace_id
+
+    def initialize(workspace_id)
+      @workspace_id = Config.validate_id!(workspace_id.to_s)
+      @state = StateStore.new(Config.state_file)
+    end
+
+    def running?
+      entry = @state.get(workspace_id) || {}
+      entry['pid'] && entry['port'] && !process_exited?(entry['pid'])
+    end
+
+    def port
+      @state.get(workspace_id)&.fetch('port', nil)
+    end
+
+    def reserve!
+      @state.transaction do |data|
+        taken = data.values.filter_map { |entry| entry['port'] }
+        assigned = PortAllocator.allocate(Config::BACKEND_PORT_RANGE, taken)
+        data[workspace_id] = (data[workspace_id] || {}).merge('port' => assigned)
+        assigned
+      end
+    end
+
+    def start!(workspace, command, env:)
+      assigned = port
+      raise BootFailedError, 'Reserved port became occupied before server launch' unless PortAllocator.free?(assigned)
+
+      pid = spawn_command(workspace, command, env)
+      @state.set(workspace_id, 'pid' => pid, 'process_group' => pid, 'started_at' => Time.now.utc.iso8601)
+      pid
+    rescue StandardError
+      terminate(pid) if pid
+      raise
+    end
+
+    def ensure_alive!
+      raise BootFailedError, 'Application exited before readiness completed; inspect the server log' unless running?
+    end
+
+    def stop!
+      entry = @state.get(workspace_id) || {}
+      terminate(entry['pid'], group: entry['process_group']) if entry['pid']
+      @state.transaction do |data|
+        %w(pid port process_group).each { |key| data[workspace_id]&.delete(key) }
+      end
+    end
+
+    private
+
+    def spawn_command(workspace, command, env)
+      File.open(Config.backend_log_path(workspace_id), 'a') do |file|
+        Process.spawn(env, [command.first, command.first], *command.drop(1),
+                      chdir: workspace.path.to_s, in: File::NULL, out: file, err: file, pgroup: true)
+      end
+    end
+
+    def terminate(pid, group: nil)
+      return if stopped?(pid, group)
+
+      target = group ? -group : pid
+      Process.kill('TERM', target)
+      Timeout.timeout(10) { sleep 0.05 until stopped?(pid, group) }
+    rescue Timeout::Error
+      Process.kill('KILL', target)
+      Timeout.timeout(5) { sleep 0.05 until process_exited?(pid) }
+    rescue Errno::ESRCH
+      nil
+    end
+
+    def stopped?(pid, group)
+      process_exited?(pid) && !group_alive?(group)
+    end
+
+    def group_alive?(group)
+      return false unless group
+
+      Process.kill(0, -group)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+
+    def process_exited?(pid)
+      !!Process.waitpid(pid, Process::WNOHANG)
+    rescue Errno::ECHILD
+      !pid_alive?(pid)
+    end
+
+    def pid_alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH, TypeError
+      false
+    end
+  end
+end

data/lib/workspaces/cli.rb

@@ -0,0 +1,189 @@
+require 'optparse'
+require 'rack'
+require 'rackup'
+require 'rack/handler/puma'
+require_relative 'registry'
+require_relative 'coordinator'
+require_relative 'front_door'
+require_relative 'tls'
+
+module Workspaces
+  class Cli
+    COMMANDS = {
+      'serve' => :serve, 'create' => :create, 'list' => :list, 'show' => :show,
+      'start' => :lifecycle, 'prepare' => :lifecycle, 'restart' => :lifecycle,
+      'stop' => :stop, 'remove' => :remove, 'help' => :help
+    }.freeze
+    def self.run(argv)
+      new.run(argv.dup)
+    end
+
+    def run(argv)
+      command = argv.shift || 'serve'
+      return execute(argv) if command == 'exec'
+
+      options = parse(command, argv)
+      id = argv.shift
+      raise ArgumentError, 'Unexpected extra arguments' unless argv.empty?
+
+      handler = COMMANDS.fetch(command) { raise ArgumentError, usage }
+      send(handler, id, options.merge(command: command))
+      0
+    rescue ArgumentError, OptionParser::ParseError, Worktree::CommandFailedError => e
+      warn e.message
+      1
+    end
+
+    private
+
+    def registry
+      @registry ||= Registry.new
+    end
+
+    def coordinator
+      @coordinator ||= Coordinator.new(registry: registry)
+    end
+
+    def parse(command, argv)
+      options = {}
+      OptionParser.new do |parser|
+        parse_common_options(parser, options)
+        parse_tls_options(parser, options) if command == 'serve'
+      end.parse!(argv)
+      options
+    end
+
+    def parse_common_options(parser, options)
+      parser.on('--branch REF') { |value| options[:branch] = value }
+      parser.on('--pr NUMBER') { |value| options[:pr] = value }
+      parser.on('--new-branch NAME') { |value| options[:new_branch] = value }
+      parser.on('--from REF') { |value| options[:from] = value }
+      parser.on('--json') { options[:json] = true }
+      parser.on('--force') { options[:force] = true }
+    end
+
+    def parse_tls_options(parser, options)
+      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 }
+    end
+
+    def serve(_id, options)
+      tls = Tls.from_serve_options(options)&.validate!
+
+      if tls
+        tls.apply_env_defaults { serve_with_tls(tls) }
+      else
+        serve_with_tls(nil)
+      end
+    end
+
+    def serve_with_tls(tls)
+      puts "Workspaces listening on #{Config.bind_address}:#{Config.front_door_port}"
+      puts "Dashboard: #{Config.public_origin}/workspaces"
+      puts "Managed directory: #{Config.worktrees_dir}"
+      print_tls_exports(tls)
+      Rackup::Handler::Puma.run(FrontDoor.new, **puma_options(tls))
+    end
+
+    def print_tls_exports(tls)
+      return unless tls&.shortcut
+
+      puts 'When using separate commands, export the workspace public origin settings first:'
+      tls.env_exports.each { |command| puts command }
+    end
+
+    def puma_options(tls)
+      options = { config_files: ['-'], workers: 0 }
+      return options.merge(Host: tls.bind_uri(host: Config.bind_address, port: Config.front_door_port)) if tls
+
+      options.merge(Host: Config.bind_address, Port: Config.front_door_port)
+    end
+
+    def create(_id, options)
+      emit(registry.create(**options.slice(:branch, :pr, :new_branch, :from)).describe, options)
+    end
+
+    def list(_id, options)
+      emit(registry.list(pr: options[:pr]), options)
+    end
+
+    def show(id, options)
+      emit(coordinator.snapshot(id), options)
+    end
+
+    def lifecycle(id, options)
+      action = proc { run_lifecycle(options.fetch(:command), id) }
+      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')
+      if !started && coordinator.snapshot(id)['active']
+        raise ArgumentError, 'Workspace is busy; inspect it with show --json'
+      end
+
+      coordinator.wait(id)
+    end
+
+    def stop(id, options)
+      registry.with_lock(id) do
+        Backend.new(id).stop!
+        StateStore.new(Config.state_file).set(id, 'status' => 'stopped', 'message' => 'Server stopped')
+      end
+      emit(coordinator.snapshot(id), options)
+    end
+
+    def remove(id, options)
+      registry.with_lock(id) do |workspace|
+        if !options[:force] && workspace.dirty?
+          raise ArgumentError,
+                'Workspace has uncommitted/untracked work; use --force to discard it'
+        end
+
+        Backend.new(id).stop!
+        workspace.remove!(force: options[:force])
+        StateStore.new(Config.state_file).delete(id)
+      end
+      emit({ 'id' => id, 'removed' => true, 'branch_preserved' => true }, options)
+    end
+
+    def execute(argv)
+      id = argv.shift
+      unless argv.shift == '--' && !argv.empty?
+        raise ArgumentError,
+              'Usage: workspaces exec ID -- COMMAND [ARGUMENTS...]'
+      end
+
+      registry.with_lock(id) do |workspace|
+        pid = Process.spawn([argv.first, argv.first], *argv.drop(1), chdir: workspace.path.to_s)
+        _, status = Process.wait2(pid)
+        status.exitstatus || (128 + status.termsig)
+      end
+    end
+
+    def with_stdout_on_stderr
+      previous = $stdout
+      $stdout = $stderr
+      yield
+    ensure
+      $stdout = previous
+    end
+
+    def emit(data, options)
+      puts(options[:json] ? JSON.generate(data) : JSON.pretty_generate(data))
+    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] | ' \
+        'exec ID -- COMMAND... | remove ID [--force]'
+    end
+
+    def help(*)
+      puts usage
+    end
+  end
+end

data/lib/workspaces/command_runner.rb

@@ -0,0 +1,49 @@
+require 'open3'
+require 'timeout'
+
+module Workspaces
+  class CommandRunner
+    class Failed < StandardError; end
+
+    def initialize(path, log)
+      @path = path
+      @log = log
+    end
+
+    def run!(command, env:, timeout:)
+      executable = [command.first, command.first]
+      Open3.popen2e(env, executable, *command.drop(1), chdir: @path.to_s, pgroup: true) do |input, output, child|
+        input.close
+        output.set_encoding(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        run_child(output, child, timeout)
+      end
+    rescue Errno::ENOENT
+      raise Failed, "Executable not found: #{command.first}. Install it or update the repository's run step."
+    end
+
+    private
+
+    def run_child(output, child, timeout)
+      Timeout.timeout(timeout) do
+        output.each_line { |line| @log.print(line) }
+        result = child.value
+        unless result.success?
+          raise Failed,
+                "Command exited with status #{result.exitstatus || "signal #{result.termsig}"}; see setup log"
+        end
+      end
+    rescue Timeout::Error
+      terminate(child)
+      raise Failed, "Command exceeded its #{timeout}s timeout"
+    ensure
+      terminate(child) if child.alive?
+    end
+
+    def terminate(child)
+      Process.kill('KILL', -child.pid)
+      child.join
+    rescue Errno::ESRCH
+      child.join
+    end
+  end
+end