workspaces 0.1.0

data/lib/workspaces/recipe.rb

@@ -0,0 +1,135 @@
+require 'yaml'
+require_relative 'config'
+
+module Workspaces
+  class Recipe
+    class Invalid < ArgumentError; end
+    RESERVED_ENV = %w(WORKSPACE_ID WORKSPACE_PATH WORKSPACE_REPO_ROOT WORKSPACE_PORT WORKSPACE_URL
+                      WORKSPACE_HOST WORKSPACE_CACHE_DIR WORKSPACE_RUN_ID).freeze
+    attr_reader :steps, :environment
+
+    def initialize(root: Config.repo_root)
+      @root = root
+      document = YAML.safe_load(root.join('.workspaces.yml').read, aliases: false)
+      validate_document!(document)
+      @environment = validate_env!(document.fetch('env', {}))
+      @steps = document.fetch('steps').map { |step| validate_step!(step) }
+      validate_sequence!
+    rescue Errno::ENOENT
+      raise Invalid, 'Add .workspaces.yml to the source repository before starting a workspace'
+    rescue Psych::Exception => e
+      raise Invalid, "Invalid .workspaces.yml: #{e.message}"
+    end
+
+    def for_operation(restart: false)
+      restart ? steps.drop(steps.index { |step| step['background'] }) : steps
+    end
+
+    def command(step, context)
+      command = step.fetch('run')
+      return ['sh', '-c', command] if command.is_a?(String)
+
+      command.map { |argument| expand(argument, context) }
+    end
+
+    def env(step, context, overrides: {})
+      expanded = environment.merge(step.fetch('env', {})).transform_values do |value|
+        value.nil? ? nil : expand(value, context)
+      end
+      expanded.merge(overrides).merge(context)
+    end
+
+    private
+
+    def validate_document!(document)
+      unless document.is_a?(Hash) && document['version'] == 1
+        raise Invalid,
+              'Configuration must be a mapping with version: 1'
+      end
+      unknown_keys!(document, %w(version env steps))
+      raise Invalid, 'steps must be a nonempty array' unless document['steps'].is_a?(Array) && !document['steps'].empty?
+    end
+
+    def validate_step!(step)
+      raise Invalid, 'Each step must be a mapping' unless step.is_a?(Hash)
+      unknown_keys!(step, %w(id name run env timeout background))
+      validate_step_identity!(step)
+      validate_command!(step['run'])
+      validate_background!(step)
+      timeout = step.fetch('timeout', 600)
+      unless timeout.is_a?(Integer) && timeout.positive?
+        raise Invalid,
+              'Step timeout must be a positive integer (seconds)'
+      end
+
+      step.merge('timeout' => timeout, 'env' => validate_env!(step.fetch('env', {})))
+    end
+
+    def validate_step_identity!(step)
+      unless step['id'].is_a?(String) && step['id'].match?(/\A[a-z][a-z0-9_-]*\z/)
+        raise Invalid,
+              'Step id must be a lowercase slug'
+      end
+      return if step['name'].is_a?(String) && !step['name'].strip.empty?
+      raise Invalid,
+            'Step name must be a nonempty string'
+    end
+
+    def validate_command!(command)
+      valid = command.is_a?(String) ? (!command.strip.empty? && valid_argument?(command)) : valid_argv?(command)
+      raise Invalid, 'run must be a nonempty shell string or an array of string arguments' unless valid
+    end
+
+    def valid_argv?(command)
+      command.is_a?(Array) && !command.empty? && command.first != '' && command.all? { |arg| valid_argument?(arg) }
+    end
+
+    def valid_argument?(argument)
+      argument.is_a?(String) && argument.index("\0").nil?
+    end
+
+    def validate_background!(step)
+      return unless step.key?('background')
+      raise Invalid, 'background must be true or false' unless [true, false].include?(step['background'])
+      return unless step['background'] && step.key?('timeout')
+      raise Invalid,
+            'timeout applies to foreground steps, not the server lifetime'
+    end
+
+    def validate_env!(values)
+      raise Invalid, 'env must be a mapping' unless values.is_a?(Hash)
+      values.each do |key, value|
+        validate_env_name!(key)
+        raise Invalid, "#{key} is supplied by the workspace runner" if RESERVED_ENV.include?(key)
+        raise Invalid, 'Environment values must be strings or null' unless value.nil? || value.is_a?(String)
+      end
+      values
+    end
+
+    def validate_env_name!(key)
+      return if key.is_a?(String) && key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+
+      raise Invalid, 'Environment names must be strings'
+    end
+
+    def validate_sequence!
+      raise Invalid, 'Step IDs must be unique' unless steps.uniq { |step| step['id'] }.length == steps.length
+      unless steps.one? { |step| step['background'] }
+        raise Invalid, 'Configure exactly one background run step for the application'
+      end
+      raise Invalid, 'Add a foreground readiness command after the background step' if steps.last['background']
+    end
+
+    def unknown_keys!(mapping, allowed)
+      unknown = mapping.keys - allowed
+      raise Invalid, "Unknown configuration keys: #{unknown.join(', ')}" unless unknown.empty?
+    end
+
+    def expand(value, context)
+      value.gsub(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/) do
+        name = Regexp.last_match(1)
+        context.fetch(name) { ENV.fetch(name) { raise Invalid, "Missing environment variable: #{name}" } }
+      end
+    end
+  end
+end

data/lib/workspaces/registry.rb

@@ -0,0 +1,55 @@
+require_relative 'worktree'
+require_relative 'state_store'
+
+module Workspaces
+  class Registry
+    def find(id)
+      Worktree.new(id).require_owned!
+    end
+
+    def list(**filters)
+      root = Config.worktrees_dir(create: false)
+      return [] unless root.directory?
+
+      root.children.sort.filter_map do |directory|
+        describe_directory(directory, filters[:pr])
+      end
+    end
+
+    def create(**options)
+      workspace = Worktree.create(**options)
+      StateStore.new(Config.state_file).set(workspace.id, 'status' => 'idle', 'related_pr' => workspace.related_pr)
+      workspace
+    end
+
+    def with_lock(id)
+      workspace = find(id)
+      Config.locks_dir.mkpath
+      File.open(Config.prepare_lock_path(id), File::RDWR | File::CREAT, 0o600) do |lock|
+        unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+          raise ArgumentError,
+                'Workspace is busy preparing, restarting, or running a command'
+        end
+
+        yield workspace
+      end
+    end
+
+    private
+
+    def describe_directory(directory, number)
+      return unless managed_directory?(directory)
+      return unless directory.basename.to_s.match?(/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/)
+
+      workspace = Worktree.new(directory.basename.to_s)
+      return unless workspace.exists?
+      return if number && workspace.related_pr&.fetch('number', nil).to_s != number.to_s
+
+      workspace.describe
+    end
+
+    def managed_directory?(directory)
+      directory.directory? && !directory.symlink?
+    end
+  end
+end

data/lib/workspaces/state_store.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module Workspaces
+  # Tiny JSON-file-backed key/value store, keyed by PR number (as a string), guarded by an
+  # exclusive flock so the front door and CLI commands can safely read/modify it concurrently.
+  class StateStore
+    def initialize(path)
+      @path = path
+    end
+
+    # Yields the full state hash (String pr_number => attrs Hash) inside an exclusive lock and
+    # persists whatever the block leaves it as. Returns the block's return value.
+    def transaction
+      with_lock(File::LOCK_EX, create: true) do |file|
+        data = read_data(file)
+        result = yield(data)
+        write_data(file, data)
+        result
+      end
+    end
+
+    def all
+      with_lock(File::LOCK_SH, default: {}) { |file| deep_copy(read_data(file)) }
+    end
+
+    def get(pr_number)
+      with_lock(File::LOCK_SH, default: nil) { |file| deep_copy(read_data(file)[pr_number.to_s]) }
+    end
+
+    def set(pr_number, attrs)
+      transaction { |data| data[pr_number.to_s] = (data[pr_number.to_s] || {}).merge(attrs) }
+    end
+
+    def delete(pr_number)
+      transaction { |data| data.delete(pr_number.to_s) }
+    end
+
+    private
+
+    attr_reader :path
+
+    def with_lock(lock_type, create: false, default: nil)
+      ensure_parent_dir! if create
+      mode = create ? (File::RDWR | File::CREAT) : File::RDONLY
+      File.open(path, mode) do |file|
+        file.flock(lock_type)
+        yield(file)
+      end
+    rescue Errno::ENOENT
+      default
+    end
+
+    def ensure_parent_dir!
+      FileUtils.mkdir_p(File.dirname(path))
+    end
+
+    def read_data(file)
+      file.rewind
+      raw = file.read
+      return {} if raw.to_s.strip.empty?
+
+      parsed = JSON.parse(raw)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def write_data(file, data)
+      file.rewind
+      file.truncate(0)
+      file.write(JSON.pretty_generate(data))
+      file.flush
+    end
+
+    def deep_copy(value)
+      return nil if value.nil?
+
+      JSON.parse(JSON.generate(value))
+    end
+  end
+end

data/lib/workspaces/tee_log.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'environment_overrides'
+
+module Workspaces
+  # Duplicates every log line to both the persistent per-PR log file AND the front door
+  # process's own stdout - so progress during a (sometimes 1-2 minute) first-time prepare shows
+  # up live in the terminal running `bin/pr-preview`, not just in a file nobody's tailing.
+  # Prefixed with the PR number since multiple previews can be preparing concurrently.
+  class TeeLog
+    def initialize(workspace_id, file)
+      @workspace_id = workspace_id
+      @file = file
+      @overrides = EnvironmentOverrides.new(workspace_id)
+    end
+
+    def puts(message = '')
+      scrubbed = scrub(message)
+      @file.puts(scrubbed)
+      $stdout.puts(prefixed(scrubbed))
+    end
+
+    def print(message)
+      scrubbed = scrub(message)
+      @file.print(scrubbed)
+      $stdout.print(prefixed(scrubbed))
+    end
+
+    private
+
+    def scrub(message)
+      @overrides.scrub(message)
+    end
+
+    def prefixed(message)
+      "[Workspace #{@workspace_id}] #{message}"
+    end
+  end
+end

data/lib/workspaces/tls.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'uri'
+require_relative 'config'
+
+module Workspaces
+  class Tls
+    DEFAULT_CERT_PATH = '~/.workspaces/certs/workspaces.pem'
+    DEFAULT_KEY_PATH = '~/.workspaces/certs/workspaces-key.pem'
+    DEFAULT_PUBLIC_ORIGIN_HOST = 'workspaces.localhost'
+
+    attr_reader :cert_path, :key_path, :shortcut
+
+    def self.from_serve_options(options)
+      cert = options[:tls_cert]
+      key = options[:tls_key]
+      raise ArgumentError, '--tls-cert and --tls-key must be provided together' if cert.nil? ^ key.nil?
+      return nil unless options[:secure] || cert
+
+      new(tls_cert: cert || default_cert_path, tls_key: key || default_key_path,
+          shortcut: cert.nil?)
+    end
+
+    def self.default_cert_path
+      File.expand_path(DEFAULT_CERT_PATH)
+    end
+
+    def self.default_key_path
+      File.expand_path(DEFAULT_KEY_PATH)
+    end
+
+    def initialize(tls_cert:, tls_key:, shortcut: false)
+      @cert_path = File.expand_path(tls_cert.to_s)
+      @key_path = File.expand_path(tls_key.to_s)
+      @shortcut = shortcut
+    end
+
+    def validate!
+      validate_public_origin!
+      validate_file!(:certificate, cert_path)
+      validate_file!(:private_key, key_path)
+
+      certificate = OpenSSL::X509::Certificate.new(File.read(cert_path))
+      private_key = OpenSSL::PKey.read(File.read(key_path))
+
+      unless certificate.check_private_key(private_key)
+        raise ArgumentError, 'TLS certificate does not match the TLS private key'
+      end
+
+      self
+    rescue OpenSSL::OpenSSLError, ArgumentError => e
+      raise e if e.is_a?(ArgumentError)
+
+      raise ArgumentError, 'TLS certificate or private key is invalid'
+    end
+
+    def bind_uri(host:, port:)
+      query = URI.encode_www_form(cert: cert_path, key: key_path, verify_mode: 'none')
+      "ssl://#{host}:#{port}?#{query}"
+    end
+
+    def env_exports
+      origin = default_public_origin
+      domain = default_base_domain
+      [
+        "export WORKSPACES_PUBLIC_ORIGIN=#{origin}",
+        "export WORKSPACES_BASE_DOMAIN=#{domain}"
+      ]
+    end
+
+    def apply_env_defaults
+      defaults = { 'WORKSPACES_PUBLIC_ORIGIN' => default_public_origin,
+                   'WORKSPACES_BASE_DOMAIN' => default_base_domain }
+      temporary = defaults.select { |name, _| ENV.fetch(name, '').empty? }
+      previous = temporary.keys.to_h { |name| [name, ENV.fetch(name, nil)] }
+      temporary.each { |name, value| ENV[name] = value }
+      yield
+    ensure
+      previous&.each { |name, value| value.nil? ? ENV.delete(name) : ENV[name] = value }
+    end
+
+    private
+
+    def effective_public_origin
+      return default_public_origin if ENV['WORKSPACES_PUBLIC_ORIGIN'].to_s.empty?
+
+      Config.public_origin
+    end
+
+    def default_public_origin
+      "https://#{DEFAULT_PUBLIC_ORIGIN_HOST}:#{Config.front_door_port}"
+    end
+
+    def default_base_domain
+      DEFAULT_PUBLIC_ORIGIN_HOST
+    end
+
+    def validate_public_origin!
+      return if URI.parse(effective_public_origin).scheme == 'https'
+
+      raise ArgumentError, 'TLS requires an HTTPS WORKSPACES_PUBLIC_ORIGIN'
+    rescue URI::InvalidURIError
+      raise ArgumentError, 'Invalid WORKSPACES_PUBLIC_ORIGIN'
+    end
+
+    def validate_file!(label, path)
+      raise ArgumentError, "TLS #{label} file does not exist: #{path}" unless File.file?(path)
+      raise ArgumentError, "TLS #{label} file is not readable: #{path}" unless File.readable?(path)
+    end
+  end
+end

data/lib/workspaces/version.rb

@@ -0,0 +1,3 @@
+module Workspaces
+  VERSION = '0.1.0'
+end

data/lib/workspaces/workflow.rb

@@ -0,0 +1,78 @@
+require 'securerandom'
+require_relative 'recipe'
+require_relative 'command_runner'
+require_relative 'backend'
+require_relative 'environment_overrides'
+
+module Workspaces
+  class Workflow
+    def initialize(workspace, log, state: StateStore.new(Config.state_file))
+      @workspace = workspace
+      @log = log
+      @state = state
+      @backend = Backend.new(workspace.id)
+    end
+
+    def run!(restart: false)
+      recipe = Recipe.new
+      overrides = EnvironmentOverrides.new(@workspace.id).load
+      steps = recipe.for_operation(restart: restart)
+      publish_steps(steps)
+      @backend.stop!
+      context = build_context(@backend.reserve!)
+      runner = CommandRunner.new(@workspace.path, @log)
+      steps.each { |step| execute(step, recipe, context, runner, overrides) }
+      @backend.ensure_alive!
+      @backend.port
+    rescue StandardError
+      @backend.stop!
+      raise
+    end
+
+    private
+
+    def publish_steps(steps)
+      @state.set(@workspace.id, 'steps' => steps.map do |step|
+        { 'key' => step['id'], 'label' => step['name'], 'state' => 'pending' }
+      end)
+    end
+
+    def build_context(port)
+      {
+        'WORKSPACE_ID' => @workspace.id, 'WORKSPACE_PATH' => @workspace.path.to_s,
+        'WORKSPACE_REPO_ROOT' => Config.repo_root.to_s, 'WORKSPACE_PORT' => port.to_s,
+        'WORKSPACE_URL' => Config.preview_url(@workspace.id).delete_suffix('/'),
+        'WORKSPACE_HOST' => Config.preview_host(@workspace.id),
+        'WORKSPACE_CACHE_DIR' => Config.home.to_s, 'WORKSPACE_RUN_ID' => SecureRandom.hex(24)
+      }
+    end
+
+    def execute(step, recipe, context, runner, overrides)
+      progress(step, 'active')
+      @log.puts "==> #{step.fetch('name')}"
+      command = recipe.command(step, context)
+      env = recipe.env(step, context, overrides: overrides)
+      if step['background']
+        @backend.start!(@workspace, command, env: env)
+      else
+        runner.run!(command, env: env, timeout: step.fetch('timeout'))
+        @backend.ensure_alive! if @server_started
+      end
+      @server_started = true if step['background']
+      progress(step, 'complete')
+    rescue StandardError
+      progress(step, 'failed')
+      raise
+    end
+
+    def progress(step, status)
+      @state.transaction do |data|
+        entry = data.fetch(@workspace.id)
+        entry['steps'].find { |item| item['key'] == step['id'] }['state'] = status
+        entry['message'] = step['name']
+        entry['current_step'] = step['id']
+        entry['updated_at'] = Time.now.utc.iso8601
+      end
+    end
+  end
+end