space-cadet 9.0.0

data/lib/space_core/cli/run.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../oci_runner"
+
+module Space::Core::CLI
+class Run < BaseCommand
+  desc "Run the packed OCI image for the current space (auth injected at runtime). Pass a command and its arguments after `--` so they forward as separate argv tokens"
+
+  argument :command, type: :array, required: false, desc: "Command to run in the container (default: login shell). Use `--` to pass a command with arguments, e.g. `space run -- hermes -z \"hello\"`"
+  option :tty, type: :boolean, default: nil, desc: "Force interactive TTY (default: auto-detect)"
+  option :env, type: :array, desc: "Host env var to forward into the container (repeatable; adds to run.env)"
+  example "-- hermes -z \"What is 17 plus 4?\"   # `--` forwards the command and its args as separate tokens (a quoted multi-word command arrives as one token and fails in-guest)"
+
+  def call(command: [], tty: nil, env: [], **opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    handle_errors do
+      result = store.current.bind do |space|
+        runner = Space::Core::OciRunner.new(
+          space: space, interactive: tty.nil? ? CLI.tty?(out) : tty, env_vars: env
+        )
+        runner.command(command).fmap { |argv| { argv: argv, runner: runner } }
+      end
+      render(result) do |r|
+        r[:runner].host_dirs.each { |d| FileUtils.mkdir_p(d) }
+        warn_missing_env(r[:runner].missing_env)
+        terminal.say "Running: #{r[:argv].join(' ')}"
+        out.flush # Kernel.exec replaces the process without flushing buffered IO
+        Kernel.exec(*r[:argv])
+      end
+    end
+  end
+
+  private
+
+  # A requested var absent from the host env is almost always a forgotten export;
+  # forwarding silently omits it and the payload fails opaquely in-guest. Warn, don't fail.
+  def warn_missing_env(missing)
+    return if missing.empty?
+
+    terminal.error("Warning: requested env not set on host, not forwarded: #{missing.join(', ')}")
+  end
+end
+end

data/lib/space_core/cli/shell.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+module Shell
+  class ShellInit < BaseCommand
+    desc "Print shell integration script"
+    argument :shell_name, required: true, desc: "Shell name (e.g. fish)"
+
+    def call(shell_name:, **opts)
+      setup_terminal(**opts.slice(:color, :colors))
+      handle_errors do
+        terminal.say Space::Core::ShellIntegration.for(shell_name)
+        CLI.record_outcome(Outcome.new(exit_code: 0))
+      end
+    end
+  end
+
+  class Fish < BaseCommand
+    desc "Manage fish shell integration: install, uninstall, path"
+    argument :subcommand, required: false, desc: "install, uninstall, or path (default: install)"
+    option :force, type: :boolean, default: false, desc: "Overwrite or remove existing shell files"
+
+    def call(subcommand: "install", force: false, **opts)
+      setup_terminal(**opts.slice(:color, :colors))
+      handle_errors do
+        case subcommand
+        when "install"
+          result = Space::Core::ShellIntegration.install("fish", env: project_config.env, force: force)
+          terminal.success fish_install_message(result.fetch(:action), result.fetch(:path))
+          terminal.success fish_completions_install_message(result.fetch(:completions_action), result.fetch(:completions_path))
+          terminal.say "Restart fish to load the integration in this terminal: exec fish"
+        when "uninstall"
+          result = Space::Core::ShellIntegration.uninstall("fish", env: project_config.env, force: force)
+          terminal.success fish_uninstall_message(result.fetch(:action), result.fetch(:path))
+          terminal.success fish_completions_uninstall_message(result.fetch(:completions_action), result.fetch(:completions_path))
+        when "path"
+          terminal.say "Function:    #{terminal.path(Space::Core::ShellIntegration.path_for('fish', env: project_config.env))}"
+          terminal.say "Completions: #{terminal.path(Space::Core::ShellIntegration.completions_path_for('fish', env: project_config.env))}"
+        else
+          err.puts "Usage: space shell fish [install|uninstall|path]"
+          CLI.record_outcome(Outcome.new(exit_code: 1))
+          next
+        end
+        CLI.record_outcome(Outcome.new(exit_code: 0))
+      end
+    end
+
+    private
+
+    def fish_install_message(action, path)
+      case action
+      when :unchanged then "Fish integration already installed: #{terminal.path(path)}"
+      when :updated   then "Updated fish integration: #{terminal.path(path)}"
+      else                 "Installed fish integration: #{terminal.path(path)}"
+      end
+    end
+
+    def fish_uninstall_message(action, path)
+      case action
+      when :missing then "Fish integration was not installed: #{terminal.path(path)}"
+      else               "Removed fish integration: #{terminal.path(path)}"
+      end
+    end
+
+    def fish_completions_install_message(action, path)
+      case action
+      when :unchanged then "Fish completions already installed: #{terminal.path(path)}"
+      when :updated   then "Updated fish completions: #{terminal.path(path)}"
+      else                 "Installed fish completions: #{terminal.path(path)}"
+      end
+    end
+
+    def fish_completions_uninstall_message(action, path)
+      case action
+      when :missing then "Fish completions were not installed: #{terminal.path(path)}"
+      else               "Removed fish completions: #{terminal.path(path)}"
+      end
+    end
+  end
+
+  class Complete < BaseCommand
+    desc "Print completion candidates"
+    argument :kind, required: true, desc: "Completion kind"
+    argument :extra, type: :array, required: false, desc: "Extra args for completion"
+
+    def call(kind:, extra: [], **opts)
+      setup_terminal(**opts.slice(:color, :colors))
+      handle_errors do
+        completion_candidates(kind, Array(extra)).each { |c| terminal.say c }
+        CLI.record_outcome(Outcome.new(exit_code: 0))
+      end
+    end
+
+    private
+
+    def completion_candidates(kind, args)
+      case kind
+      when "spaces"          then store.list.map { |space| "#{space.id}\t#{space.title}" }
+      when "statuses"        then Space::Core::Space::VALID_STATUSES
+      when "config-keys"     then Space::Core::Config::EDITABLE_KEYS
+      when "config-values"   then completion_values_for_config_key(args.first)
+      when "shells"          then ["fish"]
+      when "color-modes"     then %w[auto always never]
+      when "repo-subcommands"   then %w[add list ls resolve]
+      when "config-subcommands" then %w[show path set]
+      when "fish-subcommands"   then %w[install uninstall path]
+      else
+        raise Space::Core::Error, "Usage: space shell complete #{completion_kinds.join('|')}"
+      end
+    end
+
+    def completion_values_for_config_key(key)
+      case key
+      when "git_clone_protocol" then Space::Core::Config::VALID_GIT_CLONE_PROTOCOLS
+      when "default_provider"   then %w[github.com gitlab.com]
+      else []
+      end
+    end
+
+    def completion_kinds
+      %w[spaces statuses config-keys config-values shells color-modes repo-subcommands config-subcommands fish-subcommands]
+    end
+  end
+end
+end

data/lib/space_core/cli/show.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+class Show < BaseCommand
+  desc "Show metadata for a space or the current space"
+  argument :identifier, required: false, desc: "Space ID or title slug"
+
+  def call(identifier: nil, **opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    render(store.find(identifier)) do |space|
+      terminal.say "ID:         #{space.id}"
+      terminal.say "Title:      #{space.title}"
+      terminal.say "Status:     #{space.status}"
+      terminal.say "Path:       #{terminal.path(space.path)}"
+      terminal.say "Created:    #{space.data['created_at']}"
+      terminal.say "Updated:    #{space.data['updated_at']}"
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+end
+end

data/lib/space_core/cli/status.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+class Status < BaseCommand
+  desc "Set a space status: active, paused, done, archived"
+  argument :rest, type: :array, required: false, desc: "[SPACE] STATUS"
+
+  # One command, overloaded by its positional(s):
+  #   help token (`help`, or dry-cli's -h/--help which never reach here) → help
+  #   lone keyword / `<space> <keyword>`                                 → set
+  #   bare, or a lone non-keyword identifier                            → report
+  def call(rest: [], **opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    args = Array(rest)
+    return show_help if help_token?(args)
+
+    handle_errors do
+      if set_args?(args)
+        set_status(args)
+      elsif args.length <= 1
+        report(args.first)
+      else
+        raise Space::Core::Error, "Usage: space status [SPACE] STATUS"
+      end
+    end
+  end
+
+  private
+
+  # The bare word `help` shows the command help, like dry-cli's -h/--help (which
+  # it intercepts before dispatch). It must never set status to "help" or report.
+  def help_token?(args)
+    args == ["help"]
+  end
+
+  def show_help
+    out.puts Dry::CLI::Banner.call(self.class, Dry::CLI::ProgramName.call(["status"]))
+    CLI.record_outcome(Outcome.new(exit_code: 0))
+  end
+
+  # A set request: `<space> <keyword>` (two args), or a lone status keyword. A
+  # lone non-keyword arg is a space identifier to REPORT, not a malformed status.
+  def set_args?(args)
+    args.length == 2 ||
+      (args.length == 1 && Space::Core::Space::VALID_STATUSES.include?(args.first))
+  end
+
+  def set_status(args)
+    identifier, status_value = args.length == 2 ? args : [nil, args.first]
+    render(store.find(identifier)) do |space|
+      space.update_status(status_value)
+      terminal.success "#{space.id} is #{space.status}"
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+
+  def report(identifier)
+    render(store.find(identifier)) do |space|
+      terminal.say "ID:         #{space.id}"
+      terminal.say "Title:      #{space.title}"
+      terminal.say "Status:     #{space.status}"
+      terminal.say "Path:       #{terminal.path(space.path)}"
+      terminal.say "Created:    #{space.data['created_at']}"
+      terminal.say "Updated:    #{space.data['updated_at']}"
+      lines = LoopStatus.lines(space.data["project"])
+      if lines
+        terminal.say ""
+        lines.each { |line| terminal.say line }
+      end
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+end
+end

data/lib/space_core/cli/use.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+class Use < BaseCommand
+  desc "Remember a space in recent state and print its path"
+  argument :identifier, required: true, desc: "Space ID or title slug"
+
+  def call(identifier:, **opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    render(store.use(identifier)) do |space|
+      terminal.success "Recent space: #{space.id}"
+      terminal.say terminal.path(space.path)
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+end
+end

data/lib/space_core/cli.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require "pastel"
+require_relative "cli/repeatable_options"
+require_relative "cli/help"
+
+module Space::Core
+  module CLI
+    CLI = self
+
+    Outcome = Data.define(:exit_code, :message) do
+      def initialize(exit_code:, message: nil) = super
+    end
+
+    def self.record_outcome(o) = (Thread.current[:space_core_cli_outcome] = o)
+    def self.last_outcome = Thread.current[:space_core_cli_outcome]
+
+    # Pastel used by the colourful help listing (Help / the Usage reopen). Set
+    # per-invocation in .call from the output stream and --color; defaults to a
+    # disabled instance so non-CLI callers and tests render plain text.
+    def self.help_pastel = @help_pastel ||= Pastel.new(enabled: false)
+
+    def self.help_pastel=(pastel)
+      @help_pastel = pastel
+    end
+
+    # Whether the help listing should be colourised: honour an explicit
+    # --color/--colors (always/never), otherwise auto-detect from the streams the
+    # listing can land on (stdout for top-level help, stderr for bare namespaces).
+    def self.help_colors?(argv, out, err)
+      case color_mode(argv)
+      when "always" then true
+      when "never"  then false
+      else tty?(out) || tty?(err)
+      end
+    end
+
+    def self.tty?(io) = io.respond_to?(:tty?) && io.tty?
+
+    def self.color_mode(argv)
+      argv.each_with_index do |arg, i|
+        return arg.split("=", 2)[1].to_s.downcase if arg.start_with?("--color=", "--colors=")
+        return argv[i + 1].to_s.downcase if %w[--color --colors].include?(arg)
+      end
+      "auto"
+    end
+
+    module Registry
+      extend Dry::CLI::Registry
+    end
+
+    TOP_LEVEL_HELP  = [[], ["--help"], ["-h"], ["help"]].freeze
+    VERSION_REQUEST = [["version"], ["--version"]].freeze
+
+    def self.call(argv, out = $stdout, err = $stderr)
+      Thread.current[:space_core_cli_outcome] = nil
+      self.help_pastel = Pastel.new(enabled: help_colors?(argv, out, err))
+
+      if TOP_LEVEL_HELP.include?(argv)
+        print_usage(out)
+        return 0
+      end
+
+      if VERSION_REQUEST.include?(argv)
+        print_version(out)
+        return 0
+      end
+
+      Dry::CLI.new(Registry).call(arguments: normalize_args(argv), out: out, err: err)
+      last_outcome&.exit_code || 0
+    end
+
+    # Move --color/--colors options to the end of the argument list so dry-cli's
+    # command routing is not confused by options before the subcommand name.
+    #
+    # Two passes:
+    #   1. Leading: extract two-token form (--color VALUE) and =-form from the
+    #      front while args still look like options.
+    #   2. Non-leading: extract =-form (--color=VALUE / --colors=VALUE) from any
+    #      position before the -- separator. The bare two-token form is ambiguous
+    #      with a subcommand name in non-leading position and is left in place.
+    def self.normalize_args(argv)
+      args = argv.dup
+      extracted = []
+
+      # Pass 1: leading two-token and =-form (existing behavior, unchanged)
+      while (arg = args.first) && arg != "--" && arg.start_with?("-")
+        if %w[--color --colors].include?(arg)
+          extracted << args.shift
+          extracted << args.shift if args.first && !args.first.start_with?("-")
+        elsif arg.start_with?("--color=", "--colors=")
+          extracted << args.shift
+        else
+          break
+        end
+      end
+
+      # Pass 2: =-form from any non-leading position, stop at --
+      sep = args.index("--")
+      head = sep ? args[0, sep] : args
+      tail = sep ? args[sep..] : []
+      mid_color, head = head.partition { |a| a.start_with?("--color=", "--colors=") }
+      extracted += mid_color
+      args = head + tail
+
+      extracted.empty? ? args : args + extracted
+    end
+
+    def self.print_usage(out)
+      out.puts Dry::CLI::Usage.call(Registry.get([]))
+    end
+
+    def self.print_version(out)
+      out.puts ::Space::Core::VERSION
+    end
+
+    def self.run(argv, out = $stdout, err = $stderr)
+      Kernel.exit(call(argv, out, err))
+    rescue Interrupt
+      err.puts "interrupted"
+      Kernel.exit(130)
+    end
+  end
+end
+
+require_relative "cli/helpers"
+require_relative "cli/base_command"
+require_relative "cli/init"
+require_relative "cli/new"
+require_relative "cli/list"
+require_relative "cli/show"
+require_relative "cli/path"
+require_relative "cli/use"
+require_relative "cli/current"
+require_relative "cli/status"
+require_relative "cli/config"
+require_relative "cli/repo"
+require_relative "cli/shell"
+require_relative "cli/pack"
+require_relative "cli/build"
+require_relative "cli/run"
+
+Space::Core::CLI::Registry.register "init",    Space::Core::CLI::Init
+Space::Core::CLI::Registry.register "new",     Space::Core::CLI::New
+Space::Core::CLI::Registry.register "list",    Space::Core::CLI::List
+Space::Core::CLI::Registry.register "ls",      Space::Core::CLI::List
+Space::Core::CLI::Registry.register "show",    Space::Core::CLI::Show
+Space::Core::CLI::Registry.register "path",    Space::Core::CLI::Path
+Space::Core::CLI::Registry.register "use",     Space::Core::CLI::Use
+Space::Core::CLI::Registry.register "current", Space::Core::CLI::Current
+Space::Core::CLI::Registry.register "status",  Space::Core::CLI::Status
+Space::Core::CLI::Registry.register "config" do |c|
+  c.register "show", Space::Core::CLI::Config::Show
+  c.register "path", Space::Core::CLI::Config::ConfigPath
+  c.register "set",  Space::Core::CLI::Config::Set
+end
+Space::Core::CLI::Registry.register "repo" do |r|
+  r.register "add",     Space::Core::CLI::Repo::Add
+  r.register "list",    Space::Core::CLI::Repo::RepoList
+  r.register "ls",      Space::Core::CLI::Repo::RepoList
+  r.register "resolve", Space::Core::CLI::Repo::Resolve
+end
+Space::Core::CLI::Registry.register "repos" do |r|
+  r.register "add",     Space::Core::CLI::Repo::Add
+  r.register "list",    Space::Core::CLI::Repo::RepoList
+  r.register "ls",      Space::Core::CLI::Repo::RepoList
+  r.register "resolve", Space::Core::CLI::Repo::Resolve
+end
+Space::Core::CLI::Registry.register "shell" do |s|
+  s.register "init",     Space::Core::CLI::Shell::ShellInit
+  s.register "fish",     Space::Core::CLI::Shell::Fish
+  s.register "complete", Space::Core::CLI::Shell::Complete
+end
+Space::Core::CLI::Registry.register "pack",  Space::Core::CLI::Pack
+Space::Core::CLI::Registry.register "build", Space::Core::CLI::Build
+Space::Core::CLI::Registry.register "run",   Space::Core::CLI::Run

data/lib/space_core/cloner.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "async"
+require "dry/monads"
+require "space_core/shell"
+
+module Space::Core
+  # Resolution + COW-copy boundary for `clone`. Returns Result; no
+  # side effects on Failure. Injected shell seam defaults to ShellRunner
+  # (wraps Shell.run in Sync{} so the Fiber-scheduler requirement is met
+  # from a plain synchronous CLI command — same pattern as Launchd::Agent).
+  class Cloner
+    include Dry::Monads[:result]
+
+    class ShellRunner
+      def run(*argv)
+        Sync { Shell.run(*argv) }
+      end
+    end
+
+    def initialize(base_dir:, shell: ShellRunner.new)
+      @base_dir = File.expand_path(base_dir)
+      @shell = shell
+    end
+
+    # Resolve `name` against `base_dir` and copy to `into/<leaf>`.
+    # Returns Success(dest_path) or Failure(message).
+    def call(name:, into: ".")
+      result = resolve(name)
+      return result if result.failure?
+      copy(result.success, into)
+    end
+
+    private
+
+    def resolve(name)
+      parts = name.split("/")
+      case parts.length
+      when 1
+        # paths:exempt - layout intent (checkout resolution by depth); checkout depth drives the glob shape
+        candidates = Dir.glob(File.join(@base_dir, "*", "*", name))
+        case candidates.length
+        when 0 then Failure("#{name.inspect} not found under base_dir #{@base_dir}")
+        when 1 then Success(candidates.first)
+        else ambiguous(name, candidates, "owner/name or host/owner/name")
+        end
+      when 2
+        owner, repo_name = parts
+        # paths:exempt - layout intent (checkout resolution by depth); checkout depth drives the glob shape
+        candidates = Dir.glob(File.join(@base_dir, "*", owner, repo_name))
+        case candidates.length
+        when 0 then Failure("#{name.inspect} not found under base_dir #{@base_dir}")
+        when 1 then Success(candidates.first)
+        else ambiguous(name, candidates, "host/owner/name")
+        end
+      when 3
+        path = File.join(@base_dir, *parts)
+        File.directory?(path) ? Success(path) : Failure("#{name.inspect} not found under base_dir #{@base_dir}")
+      else
+        Failure("invalid repo reference: #{name.inspect}")
+      end
+    end
+
+    def ambiguous(name, candidates, hint)
+      list = candidates.map { |c| "  #{c.delete_prefix("#{@base_dir}/")}" }.join("\n")
+      Failure("ambiguous name #{name.inspect}; qualify with #{hint}:\n#{list}")
+    end
+
+    def copy(src, into)
+      leaf = File.basename(src)
+      dest = File.join(File.expand_path(into), leaf)
+      return Failure("destination already exists: #{dest}") if File.exist?(dest)
+      result = @shell.run("cp", "-Rc", src, dest)
+      result.success? ? Success(dest) : result
+    end
+  end
+end

data/lib/space_core/commands.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Space::Core
+  module Commands
+    module_function
+
+    # Render a multi-flag command with trailing " \" continuations broken at
+    # "--flag" boundaries, continuation lines indented two spaces. Commands
+    # without "--" flags are returned unchanged.
+    def wrap(command)
+      parts = split_at_flag_boundaries(command)
+      return command if parts.size <= 1
+
+      parts.each_with_index.map do |part, i|
+        segment = i.zero? ? part.rstrip : "  #{part.lstrip}"
+        i < parts.size - 1 ? "#{segment} \\" : segment
+      end.join("\n")
+    end
+
+    # Same split points as command.split(/(?= --)/), but blind to " --" that
+    # falls inside a single- or double-quoted flag value, so a --title
+    # containing " -- " isn't torn apart mid-argument.
+    def split_at_flag_boundaries(command)
+      parts = []
+      start = 0
+      in_squote = false
+      in_dquote = false
+      escaped = false
+      command.each_char.with_index do |ch, i|
+        if escaped
+          escaped = false
+          next
+        end
+        case ch
+        # A backslash escapes the next character outside quotes and inside
+        # double quotes, but is a literal character inside single quotes.
+        when "\\" then escaped = true unless in_squote
+        when "'" then in_squote = !in_squote unless in_dquote
+        when '"' then in_dquote = !in_dquote unless in_squote
+        when " "
+          if !in_squote && !in_dquote && command[i + 1, 2] == "--"
+            parts << command[start...i]
+            start = i
+          end
+        end
+      end
+      parts << command[start..]
+      parts
+    end
+  end
+end