rosett-ai 1.3.3

data/lib/rosett_ai/thor/tasks/build.rb

@@ -0,0 +1,1162 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'thor'
+require 'terminal-table'
+require 'rainbow'
+require 'tty-spinner'
+require 'fileutils'
+require 'pathname'
+require 'securerandom'
+require 'time'
+require_relative '../../formatting'
+
+module RosettAi
+  module Thor
+    module Tasks
+      # Mutable build state: ID, log path, timings, and failure info.
+      BuildContext = Struct.new(
+        :build_id, :build_start, :build_log,
+        :stage_timings, :completed_stages,
+        :failed_stage, :failure_reason, :summary_printed
+      ) do
+        def self.create(log_dir)
+          id = SecureRandom.uuid
+          log_path = log_dir.join("build-#{id}.log")
+          FileUtils.mkdir_p(log_path.dirname)
+          ctx = new(
+            build_id: id,
+            build_start: Time.now,
+            build_log: log_path,
+            stage_timings: {},
+            completed_stages: [],
+            failed_stage: nil,
+            failure_reason: nil,
+            summary_printed: false
+          )
+          File.open(log_path, 'w', 0o644) do |f|
+            f.write("# rosett-ai build log\n# Build ID: #{id}\n" \
+                    "# Started:  #{ctx.build_start.iso8601}\n\n")
+          end
+          ctx
+        end
+      end
+
+      # Thor subcommand for building a .deb package using fpm + ruby-build.
+      #
+      # Produces a self-contained Debian package at /opt/rosett-ai with an
+      # embedded Ruby runtime (compiled via ruby-build), vendored gems,
+      # and maintainer scripts for proper APT lifecycle handling.
+      #
+      # Build tooling references:
+      #   fpm            — https://github.com/jordansissel/fpm
+      #   ruby-build     — https://github.com/rbenv/ruby-build
+      #   dpkg-deb       — https://man7.org/linux/man-pages/man1/dpkg-deb.1.html
+      #   fakeroot       — https://wiki.debian.org/FakeRoot
+      class BuildPackage < ::Thor
+        include RosettAi::Formatting
+
+        default_task :create
+
+        INSTALL_DIR = '/opt/rosett-ai'
+
+        # Files/directories excluded when syncing app source into the staging tree
+        APP_EXCLUDES = [
+          # Version control
+          '.git', '.gitignore',
+          # Bundler / gem build artifacts
+          '.bundle', '.binstubs', 'vendor/bundle', '*.gem',
+          'Gemfile.dev', 'Gemfile.dev.lock', 'Gemfile.integration',
+          # CI/CD
+          '.gitlab-ci*',
+          # Build & packaging
+          'coverage', 'tmp', 'pkg', 'spec', 'test', 'packaging',
+          # Dev tool configs
+          '.rspec', '.rubocop*', '.reek*',
+          '.fasterer.yml', '.gitleaks.toml', '.mutant.yml',
+          '.overcommit.yml', '.git-hooks',
+          '.mdlrc', '.mdl_style.rb', '.yamllint', '.yardopts',
+          '.project', '.rosett-ai',
+          # AI assistant state — never ship in package
+          '.claude', 'doc/claude-sessions',
+          'cliff.toml', 'kitchen.yml', 'Rakefile'
+        ].freeze
+
+        # Build stages in execution order (for tracking)
+        BUILD_STAGES = [
+          :validate, :clean, :prepare, :compile_ruby,
+          :sync_app, :install_gems, :clean_build_artifacts,
+          :install_wrapper,
+          :install_config, :install_man, :install_build_info, :package
+        ].freeze
+
+        # Bundler/RubyGems environment variables that must be stripped
+        # when shelling out to the embedded Ruby. Without this, a parent
+        # `bundle exec` leaks RUBYOPT=-rbundler/setup and BUNDLE_* vars
+        # into child processes, causing the embedded Ruby to try loading
+        # the project's Gemfile (which it cannot resolve).
+        BUNDLER_ENV_VARS = [
+          'BUNDLE_GEMFILE', 'BUNDLE_PATH', 'BUNDLE_BIN_PATH',
+          'BUNDLE_APP_CONFIG',
+          'BUNDLE_DEPLOYMENT', 'BUNDLE_WITHOUT', 'BUNDLE_FROZEN',
+          'BUNDLE_DISABLE_SHARED_GEMS', 'BUNDLE_IGNORE_CONFIG',
+          'BUNDLER_ORIG_BUNDLE_GEMFILE', 'BUNDLER_ORIG_BUNDLE_BIN_PATH',
+          'BUNDLER_ORIG_BUNDLER_SETUP', 'BUNDLER_ORIG_BUNDLER_VERSION',
+          'BUNDLER_ORIG_GEM_HOME', 'BUNDLER_ORIG_GEM_PATH',
+          'BUNDLER_ORIG_MANPATH', 'BUNDLER_ORIG_PATH',
+          'BUNDLER_ORIG_RB_USER_INSTALL',
+          'BUNDLER_ORIG_RUBYLIB', 'BUNDLER_ORIG_RUBYOPT',
+          'BUNDLER_VERSION',
+          'BUNDLER_SETUP', 'GEM_HOME', 'GEM_PATH',
+          'RUBYOPT', 'RUBYLIB'
+        ].freeze
+
+        # Hermetic system PATH — no workstation paths allowed.
+        # Native gem compilation needs basic system tools (make, gcc, ld)
+        # but must never reference /home/*, ~/.rbenv, or other user paths.
+        HERMETIC_SYSTEM_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'
+
+        desc 'create', 'Build a .deb package using fpm + ruby-build'
+        long_desc <<~LONGDESC
+          Builds a self-contained Debian package at /opt/rosett-ai with an embedded
+          Ruby runtime (compiled via ruby-build), vendored gems, wrapper script,
+          man pages, and maintainer scripts.
+
+          Requires fakeroot, dpkg-deb, rsync, ruby-build, and fpm.
+          Internal command — only available when developing Rosett-AI itself.
+
+          EXAMPLES
+
+            raictl build package
+            raictl build package --clean --verbose
+            raictl build package --variant gtk4 --architecture arm64
+            raictl build package --ruby-version 3.3.10 --output-dir /tmp/pkg
+        LONGDESC
+        method_option :verbose,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Show detailed build output'
+        method_option :clean,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Clean staging directory before building'
+        method_option :ruby_version,
+                      type: :string,
+                      desc: 'Ruby version to compile (default: read from .ruby-version)'
+        method_option :architecture,
+                      type: :string,
+                      default: nil,
+                      desc: 'Target architecture (default: auto-detect via dpkg)'
+        method_option :output_dir,
+                      type: :string,
+                      default: 'pkg',
+                      desc: 'Directory for the produced .deb file'
+        method_option :build_iteration,
+                      type: :numeric,
+                      default: 1,
+                      desc: 'Package build iteration (release number)'
+        method_option :variant,
+                      type: :string,
+                      default: 'core',
+                      desc: 'Package variant (core, gtk4, qt6)'
+
+        def create
+          unless RosettAi.context.rai_internal?
+            raise ::Thor::Error,
+                  ::I18n.t('rosett_ai.cli.build_package_internal_only')
+          end
+
+          init_build_context!
+          load_variant_config!
+          print_build_header
+
+          run_stage(:validate) { validate_environment! }
+          run_stage(:clean) { clean_staging! } if options[:clean]
+          run_stage(:prepare) { prepare_staging! }
+          run_stage(:compile_ruby) { compile_ruby! }
+          run_stage(:sync_app) { sync_application! }
+          run_stage(:install_gems) { install_gems! }
+          run_stage(:clean_build_artifacts) { clean_build_artifacts! }
+          run_stage(:install_wrapper) { install_wrapper! }
+          run_stage(:install_config) { install_default_config! }
+          run_stage(:install_man) { install_man_pages! }
+          run_stage(:install_build_info) { install_build_info! }
+          run_stage(:package) { build_package! }
+
+          print_build_summary(:success)
+        rescue ::Thor::Error => e
+          print_build_summary(:failed) if @ctx && !@ctx.summary_printed
+          raise e
+        end
+
+        private
+
+        # -- build context -----------------------------------------------------
+
+        def init_build_context!
+          @ctx = BuildContext.create(project_root.join('tmp'))
+        end
+
+        def load_variant_config!
+          @variant_config = RosettAi::Packaging::VariantConfig.load(options[:variant])
+        end
+
+        def log_to_file(message)
+          File.open(@ctx.build_log, 'a', 0o644) { |f| f.puts("[#{Time.now.iso8601}] #{message}") }
+        end
+
+        def run_stage(name)
+          stage_start = Time.now
+          log_to_file("STAGE #{name}: started")
+          yield
+          elapsed = Time.now - stage_start
+          @ctx.stage_timings[name] = elapsed
+          @ctx.completed_stages << name
+          log_to_file("STAGE #{name}: completed (#{format('%.1f', elapsed)}s)")
+        rescue ::Thor::Error => e
+          elapsed = Time.now - stage_start
+          @ctx.stage_timings[name] = elapsed
+          @ctx.failed_stage = name
+          log_to_file("STAGE #{name}: FAILED after #{format('%.1f', elapsed)}s")
+          log_to_file("FAILURE: #{@ctx.failure_reason}") if @ctx.failure_reason
+          raise e
+        end
+
+        def print_build_header
+          puts
+          puts Rainbow('raictl package build').bright
+          puts "  Build ID:      #{@ctx.build_id}"
+          puts "  Log file:      #{@ctx.build_log}"
+          puts "  Variant:       #{@variant_config.variant}"
+          puts "  Package:       #{@variant_config.name}"
+          puts "  Version:       #{RosettAi::VERSION}"
+          puts "  Ruby version:  #{ruby_version}"
+          puts "  Architecture:  #{architecture}"
+          puts "  Output:        #{project_root.join(options[:output_dir])}"
+          puts
+        end
+
+        # -- paths -------------------------------------------------------------
+
+        def project_root
+          @project_root ||= RosettAi.root
+        end
+
+        def staging_dir
+          @staging_dir ||= project_root.join('tmp', 'staging')
+        end
+
+        def staging_install
+          @staging_install ||= staging_dir.join('opt', 'rosett-ai')
+        end
+
+        def staging_embedded
+          @staging_embedded ||= staging_install.join('embedded')
+        end
+
+        def staging_app
+          @staging_app ||= staging_install.join('app')
+        end
+
+        def output_dir
+          @output_dir ||= project_root.join(options[:output_dir]).tap { |dir| FileUtils.mkdir_p(dir) }
+        end
+
+        def packaging_dir
+          @packaging_dir ||= project_root.join('packaging')
+        end
+
+        # -- validation --------------------------------------------------------
+
+        def validate_environment!
+          check_required_commands
+          check_ronn_available!
+          check_variant_adapter!
+          log_verbose('Build environment validated')
+        end
+
+        def check_required_commands
+          required = ['fakeroot', 'dpkg-deb', 'rsync']
+          required << 'ruby-build' unless ruby_already_compiled?
+
+          required.each do |cmd|
+            next if command_available?(cmd)
+
+            abort_build("'#{cmd}' is not installed. " \
+                        'Install build dependencies: apt-get install fakeroot dpkg-dev rsync; ' \
+                        'and ensure ruby-build is on PATH.')
+          end
+
+          return if command_available?('fpm')
+
+          abort_build("'fpm' is not installed. Run: bundle install (fpm is in the :build group)")
+        end
+
+        def check_ronn_available!
+          ronn_source = project_root.join('doc', 'man', 'rai.1.ronn')
+          return unless ronn_source.exist?
+
+          begin
+            require 'ronn'
+          rescue LoadError
+            abort_build("'ronn-ng' gem is required to compile man pages but is not installed. " \
+                        'Run: gem install ronn-ng (or add it to the :build group in Gemfile)')
+          end
+        end
+
+        def check_variant_adapter!
+          return if @variant_config.variant == 'core'
+
+          adapter = @variant_config.ui_adapter
+          adapter_path = project_root.join('lib', 'rosett_ai', 'ui', "#{adapter}.rb")
+          return if adapter_path.exist?
+
+          abort_build(<<~MSG.chomp)
+            Adapter file lib/rosett_ai/ui/#{adapter}.rb not found.
+              The #{adapter} UI adapter has not been implemented yet.
+              See P3 (ui_framework) for implementation schedule.
+          MSG
+        end
+
+        def command_available?(cmd)
+          ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? do |dir|
+            File.executable?(File.join(dir, cmd))
+          end
+        end
+
+        # -- staging -----------------------------------------------------------
+
+        def clean_staging!
+          spinner = build_spinner('Cleaning staging directory...')
+          FileUtils.rm_rf(staging_dir)
+          spinner.success(Rainbow(' done').green)
+          log_verbose("Removed #{staging_dir}")
+        end
+
+        def prepare_staging!
+          log_verbose("Preparing staging tree at #{staging_dir}")
+          [
+            staging_embedded,
+            staging_app,
+            staging_install.join('bin'),
+            staging_install.join('etc')
+          ].each { |dir| FileUtils.mkdir_p(dir) }
+        end
+
+        # -- ruby-build --------------------------------------------------------
+
+        def ruby_version
+          @ruby_version ||= options[:ruby_version] || read_ruby_version_file
+        end
+
+        def read_ruby_version_file
+          version_file = project_root.join('.ruby-version')
+          abort_build('.ruby-version file not found and --ruby-version not given') unless version_file.exist?
+          version_file.read.strip
+        end
+
+        def compile_ruby!
+          if ruby_already_compiled?
+            log_verbose("Ruby #{ruby_version} already compiled in staging — skipping")
+            return
+          end
+
+          spinner = build_spinner("Compiling Ruby #{ruby_version}...")
+          success = run_clean_command(
+            'ruby-build', ruby_version, staging_embedded.to_s
+          )
+          return spinner.success(Rainbow(' done').green) if success
+
+          spinner.error(Rainbow(' failed').red)
+          detect_ruby_build_log
+          abort_build('ruby-build failed — see build log for details.')
+        end
+
+        def detect_ruby_build_log
+          logs = Dir.glob('/tmp/ruby-build.*.log').sort_by { |f| File.mtime(f) }
+          return if logs.empty?
+
+          latest = logs.last
+          log_to_file("ruby-build log: #{latest}")
+          tail = File.readlines(latest).last(30).join
+          log_to_file("ruby-build tail output:\n#{tail}")
+          @ctx.failure_reason = "ruby-build failed. Compiler log: #{latest}"
+        end
+
+        def ruby_already_compiled?
+          ruby_bin = staging_embedded.join('bin', 'ruby')
+          return false unless ruby_bin.exist?
+
+          installed = IO.popen([ruby_bin.to_s, '-e', 'puts RUBY_VERSION'], &:read).strip
+          installed == ruby_version.sub(/\A(\d+\.\d+\.\d+).*/, '\1')
+        rescue StandardError
+          false
+        end
+
+        # -- application sync --------------------------------------------------
+
+        def sync_application!
+          spinner = build_spinner('Syncing application source...')
+          excludes = APP_EXCLUDES.flat_map { |e| ['--exclude', e] }
+          success = run_command(
+            'rsync', '-a', '--delete',
+            *excludes,
+            "#{project_root}/",
+            "#{staging_app}/"
+          )
+          return spinner.success(Rainbow(' done').green) if success
+
+          spinner.error(Rainbow(' failed').red)
+          abort_build('rsync failed to sync application source.')
+        end
+
+        # -- gem installation --------------------------------------------------
+
+        def install_gems!
+          spinner = build_spinner('Installing gems (deployment mode)...')
+          embedded_bundle = staging_embedded.join('bin', 'bundle').to_s
+
+          env = embedded_env
+          cmds = [
+            [env, embedded_bundle, 'config', 'set', '--local', 'deployment', 'true'],
+            [env, embedded_bundle, 'config', 'set', '--local', 'path', 'vendor/bundle'],
+            [env, embedded_bundle, 'config', 'set', '--local', 'without', 'development test build desktop engines'],
+            [env, embedded_bundle, 'config', 'set', '--local', 'jobs', jobs_count.to_s],
+            [env, embedded_bundle, 'install']
+          ]
+
+          cmds.each do |cmd|
+            next if run_command_in(staging_app.to_s, *cmd)
+
+            spinner.error(Rainbow(' failed').red)
+            log_bundle_debug(env, embedded_bundle)
+            abort_build(<<~MSG.chomp)
+              Gem installation failed.
+                The embedded Ruby bundler could not resolve or install gems.
+                This usually means Bundler environment variables from the parent
+                process leaked into the build. Check the build log for details.
+            MSG
+          end
+
+          spinner.success(Rainbow(' done').green)
+        end
+
+        # -- build artifact cleanup --------------------------------------------
+
+        # Strips native-gem build debris (gem_make.out, mkmf.log, Makefile)
+        # that embeds workstation-specific paths from the staging tree.
+        # These files are not needed at runtime and their presence leaks
+        # the build host's directory layout into the .deb package.
+        def clean_build_artifacts!
+          spinner = build_spinner('Cleaning native gem build artifacts...')
+          count = remove_build_debris
+          log_to_file("clean_build_artifacts: removed #{count} files")
+          spinner.success(Rainbow(" done (#{count} files removed)").green)
+        end
+
+        def remove_build_debris
+          artifacts = collect_build_artifacts
+          artifacts.each { |f| remove_artifact(f) }
+          artifacts.size
+        end
+
+        def collect_build_artifacts
+          Dir.glob(staging_app.join('vendor', 'bundle', '**', '{gem_make.out,mkmf.log}')) +
+            Dir.glob(staging_app.join('vendor', 'bundle', '**', 'ext', '**', 'Makefile'))
+        end
+
+        def remove_artifact(path)
+          FileUtils.rm_f(path)
+          log_verbose("Removed build artifact: #{path}")
+        end
+
+        def log_bundle_debug(env, bundle_bin)
+          log_to_file('--- bundle environment debug ---')
+          log_to_file("  BUNDLE_GEMFILE: #{env['BUNDLE_GEMFILE']}")
+          log_to_file("  PATH (first entry): #{env['PATH'].to_s.split(':').first}")
+          log_to_file("  bundle binary: #{bundle_bin}")
+          log_to_file("  bundle exists: #{File.exist?(bundle_bin)}")
+          gemfile = staging_app.join('Gemfile')
+          log_to_file("  Gemfile exists: #{gemfile.exist?}")
+          lockfile = staging_app.join('Gemfile.lock')
+          log_to_file("  Gemfile.lock exists: #{lockfile.exist?}")
+
+          # Log which BUNDLE_ vars are still set in the current process
+          leaked = ENV.select { |k, _| k.start_with?('BUNDLE', 'GEM_', 'RUBY') }
+          log_to_file('  Env vars in parent process (potential leaks):')
+          leaked.each { |k, v| log_to_file("    #{k}=#{v}") }
+          log_to_file('--- end bundle debug ---')
+        end
+
+        # Returns an environment hash that:
+        # 1. Unsets all Bundler/RubyGems vars inherited from `bundle exec`
+        # 2. Sets PATH to prefer the embedded Ruby
+        # 3. Points BUNDLE_GEMFILE at the staging app's Gemfile
+        def embedded_env
+          env = clean_env.merge(
+            'PATH' => "#{staging_embedded.join('bin')}:#{HERMETIC_SYSTEM_PATH}",
+            'BUNDLE_GEMFILE' => staging_app.join('Gemfile').to_s
+          )
+          log_to_file("embedded_env: #{env.inspect}")
+          env
+        end
+
+        # Strips all Bundler/RubyGems variables. When passed to system(),
+        # nil values cause the variable to be unset in the child process.
+        def clean_env
+          BUNDLER_ENV_VARS.to_h { |var| [var, nil] }
+        end
+
+        def jobs_count
+          @jobs_count ||= begin
+            nproc = `nproc 2>/dev/null`.strip
+            nproc.empty? ? 4 : [nproc.to_i, 1].max
+          end
+        end
+
+        # -- wrapper + config --------------------------------------------------
+
+        def install_wrapper!
+          template = packaging_dir.join('wrapper.sh.template').read
+          ruby_abi = query_embedded_ruby('RbConfig::CONFIG["ruby_version"]')
+          ruby_arch = query_embedded_ruby('RbConfig::CONFIG["arch"]')
+
+          content = template
+            .gsub('@@RUBY_ABI@@', ruby_abi)
+            .gsub('@@RUBY_ARCH@@', ruby_arch)
+
+          dest = staging_install.join('bin', 'raictl')
+          File.write(dest, content)
+          FileUtils.chmod(0o755, dest)
+          log_verbose("Installed wrapper script to #{dest} (ABI=#{ruby_abi}, arch=#{ruby_arch})")
+        end
+
+        def query_embedded_ruby(expression)
+          ruby_bin = staging_embedded.join('bin', 'ruby').to_s
+          env = clean_env.merge(
+            'LD_LIBRARY_PATH' => staging_embedded.join('lib').to_s
+          )
+          result = IO.popen([env, ruby_bin, '-e', "puts #{expression}"], &:read).strip
+          abort_build("Failed to query embedded Ruby for: #{expression}") if result.empty?
+          result
+        end
+
+        def install_default_config!
+          src = project_root.join('settings.json')
+          return unless src.exist?
+
+          # Ship default at /opt/rosett-ai/etc/ for reference
+          default_dest = staging_install.join('etc', 'settings.json.default')
+          FileUtils.cp(src, default_dest)
+          log_verbose("Installed default settings to #{default_dest}")
+
+          # Ship config at /etc/rosett-ai/ so dpkg treats it as a conffile
+          # (dpkg will prompt on upgrade if user has modified it)
+          etc_dir = staging_dir.join('etc', 'rosett-ai')
+          FileUtils.mkdir_p(etc_dir)
+          FileUtils.cp(src, etc_dir.join('settings.json'))
+          log_verbose("Installed conffile to #{etc_dir.join('settings.json')}")
+        end
+
+        # -- man pages ---------------------------------------------------------
+
+        def install_man_pages!
+          ronn_source = project_root.join('doc', 'man', 'rai.1.ronn')
+          return log_verbose('No man page source found — skipping') unless ronn_source.exist?
+
+          man_dir = staging_dir.join('usr', 'share', 'man', 'man1')
+          FileUtils.mkdir_p(man_dir)
+
+          require 'ronn'
+          doc = Ronn::Document.new(ronn_source.to_s)
+          roff_content = doc.to_roff
+
+          man_path = man_dir.join('rai.1')
+          File.write(man_path, roff_content)
+
+          # gzip the man page for dpkg conventions
+          system('gzip', '-f', man_path.to_s)
+          log_verbose("Installed man page to #{man_path}.gz")
+        end
+
+        # -- build info --------------------------------------------------------
+
+        def install_build_info!
+          info = build_info_content
+          dest = staging_install.join('etc', 'BUILD_INFO')
+          File.open(dest, 'w', 0o644) { |f| f.write(info) }
+          log_verbose("Installed build info to #{dest}")
+        end
+
+        def build_info_content
+          <<~INFO
+            version=#{RosettAi::VERSION}
+            commit=#{git_commit_sha}
+            branch=#{git_branch}
+            build_date=#{Time.now.utc.iso8601}
+            build_id=#{@ctx.build_id}
+            variant=#{@variant_config.variant}
+            ruby_version=#{ruby_version}
+            architecture=#{architecture}
+            builder=#{ENV.fetch('USER', 'unknown')}
+          INFO
+        end
+
+        def git_commit_sha
+          IO.popen(['git', '-C', project_root.to_s, 'rev-parse', '--short', 'HEAD'], err: File::NULL, &:read).strip
+            .then { |s| s.empty? ? 'unknown' : s }
+        rescue StandardError
+          'unknown'
+        end
+
+        def git_branch
+          IO.popen(['git', '-C', project_root.to_s, 'rev-parse', '--abbrev-ref', 'HEAD'], err: File::NULL, &:read).strip
+            .then { |s| s.empty? ? 'unknown' : s }
+        rescue StandardError
+          'unknown'
+        end
+
+        # -- fpm ---------------------------------------------------------------
+
+        def architecture
+          @architecture ||= options[:architecture] || detect_architecture
+        end
+
+        def detect_architecture
+          arch = `dpkg --print-architecture 2>/dev/null`.strip
+          if arch.empty?
+            RosettAi.logger.warn('dpkg --print-architecture failed; falling back to amd64')
+            log_to_file('WARNING: dpkg --print-architecture returned empty — defaulting to amd64')
+            puts Rainbow('  Warning: could not detect architecture via dpkg; defaulting to amd64').yellow
+            'amd64'
+          else
+            arch
+          end
+        end
+
+        def package_filename
+          "#{@variant_config.name}_#{RosettAi::VERSION}-#{options[:build_iteration]}_#{architecture}.deb"
+        end
+
+        def build_package!
+          spinner = build_spinner('Building .deb package with fpm...')
+
+          fpm_args = [
+            'fpm',
+            '-s', 'dir',
+            '-t', 'deb',
+            '--name', @variant_config.name,
+            '--version', RosettAi::VERSION,
+            '--iteration', options[:build_iteration].to_s,
+            '--maintainer', 'NeatNerds <query@neatnerds.be>',
+            '--vendor', 'NeatNerds',
+            '--description', @variant_config.description,
+            '--url', 'https://gitlab.neatnerds.be/neatnerds/NeatNerds-AI/rosett-ai',
+            '--license', 'GPL-3.0-only',
+            '--architecture', architecture,
+            '--category', 'devel',
+            *fpm_depends_args,
+            '--config-files', '/etc/rosett-ai/settings.json',
+            '--directories', '/opt/rosett-ai',
+            '--after-install', packaging_dir.join('scripts', 'postinst').to_s,
+            '--before-remove', packaging_dir.join('scripts', 'prerm').to_s,
+            '--after-remove', packaging_dir.join('scripts', 'postrm').to_s,
+            '--deb-compression', 'xz',
+            '--deb-field', 'Vcs-Git: https://gitlab.neatnerds.be/neatnerds/NeatNerds-AI/rosett-ai.git',
+            '--deb-field', "Build-Commit: #{git_commit_sha}",
+            '--deb-field', "Build-Branch: #{git_branch}",
+            '--deb-field', "Build-Date: #{Time.now.utc.iso8601}",
+            '--package', output_dir.join(package_filename).to_s,
+            '--force',
+            '-C', staging_dir.to_s,
+            '.'
+          ]
+
+          success = run_command(*fpm_args)
+          return spinner.success(Rainbow(' done').green) if success
+
+          spinner.error(Rainbow(' failed').red)
+          abort_build('fpm packaging failed.')
+        end
+
+        def fpm_depends_args
+          @variant_config.fpm_depends.flat_map { |dep| ['--depends', dep] }
+        end
+
+        # -- build summary -----------------------------------------------------
+
+        def print_build_summary(status)
+          @ctx.summary_printed = true
+          elapsed = Time.now - @ctx.build_start
+          puts
+
+          print_stages_table(status, elapsed)
+          print_failure_detail if status == :failed
+          print_artifacts_table if status == :success
+          print_build_footer(status, elapsed)
+        end
+
+        def print_stages_table(status, total_elapsed)
+          rows = BUILD_STAGES.map { |stage| build_stage_row(stage) }
+          rows.compact!
+
+          title_label, _, color = status_text(status)
+          table = ::Terminal::Table.new(
+            title: Rainbow("Build #{title_label}").send(color).bright,
+            headings: ['Stage', 'Status', 'Duration'],
+            rows: rows,
+            style: { border: :unicode_round }
+          )
+          puts table
+          puts "  Total: #{format_duration(total_elapsed)}"
+        end
+
+        def build_stage_row(stage)
+          if @ctx.completed_stages.include?(stage)
+            elapsed = @ctx.stage_timings[stage]
+            [stage_label(stage), Rainbow('OK').green, format_duration(elapsed)]
+          elsif @ctx.failed_stage == stage
+            elapsed = @ctx.stage_timings[stage]
+            [stage_label(stage), Rainbow('FAILED').red, format_duration(elapsed)]
+          elsif skipped_stage?(stage)
+            nil
+          else
+            [stage_label(stage), Rainbow('--').faint, '--']
+          end
+        end
+
+        def skipped_stage?(stage)
+          stage == :clean && !options[:clean]
+        end
+
+        def stage_label(stage)
+          {
+            validate: 'Validate environment',
+            clean: 'Clean staging',
+            prepare: 'Prepare staging tree',
+            compile_ruby: "Compile Ruby #{ruby_version}",
+            sync_app: 'Sync application source',
+            install_gems: 'Install gems (deployment)',
+            install_wrapper: 'Install wrapper script',
+            install_config: 'Install default config',
+            install_man: 'Install man pages',
+            install_build_info: 'Install build info',
+            package: 'Build .deb with fpm'
+          }.fetch(stage, stage.to_s)
+        end
+
+        def print_failure_detail
+          puts
+          puts Rainbow('Failure Detail').red.bright
+          puts Rainbow("  Stage:  #{stage_label(@ctx.failed_stage)}").red
+          puts Rainbow("  Reason: #{@ctx.failure_reason}").red if @ctx.failure_reason
+          puts
+          puts "  Build log: #{@ctx.build_log}"
+          puts '  Re-run with --verbose for full command output.'
+          puts
+        end
+
+        def print_artifacts_table
+          packages = Dir.glob(output_dir.join('*.deb').to_s)
+          return puts Rainbow('  No .deb packages found in output directory.').yellow if packages.empty?
+
+          rows = packages.map { |pkg| [File.basename(pkg), format_size(File.size(pkg))] }
+          table = ::Terminal::Table.new(
+            title: Rainbow('Artifacts').bright,
+            headings: ['Package', 'Size'],
+            rows: rows,
+            style: { border: :unicode_round }
+          )
+          puts table
+        end
+
+        def print_build_footer(status, elapsed)
+          _, footer_label, color = status_text(status)
+          puts
+          puts "  Build ID:  #{@ctx.build_id}"
+          puts "  Log file:  #{@ctx.build_log}"
+          puts "  Duration:  #{format_duration(elapsed)}"
+          puts "  Status:    #{Rainbow(footer_label).send(color)}"
+          puts
+        end
+
+        # format_size and format_duration are provided by RosettAi::Formatting
+
+        # Returns [table_title, footer_label, color] for the given build status.
+        def status_text(status)
+          status == :success ? ['Complete', 'SUCCESS', :green] : ['Failed', 'FAILED', :red]
+        end
+
+        # -- helpers -----------------------------------------------------------
+
+        def build_spinner(message)
+          spinner = TTY::Spinner.new("[:spinner] #{message}", format: :dots, clear: !options[:verbose])
+          spinner.auto_spin
+          spinner
+        end
+
+        def run_command(*cmd)
+          if options[:verbose]
+            system(*cmd)
+          else
+            system(*cmd, [:out, :err] => File::NULL)
+          end
+        end
+
+        # Runs a command with a fully clean environment (no Bundler leakage).
+        # Used for ruby-build and any process that must not see the parent's bundle.
+        def run_clean_command(*cmd)
+          if options[:verbose]
+            system(clean_env, *cmd)
+          else
+            system(clean_env, *cmd, [:out, :err] => File::NULL)
+          end
+        end
+
+        def run_command_in(dir, env, *cmd)
+          if options[:verbose]
+            system(env, *cmd, chdir: dir)
+          else
+            system(env, *cmd, chdir: dir, [:out, :err] => File::NULL)
+          end
+        end
+
+        def abort_build(message)
+          @ctx.failure_reason = message
+          log_to_file("ABORT: #{message}")
+          raise ::Thor::Error, "Error: #{message}"
+        end
+
+        def log_verbose(message)
+          puts "  #{message}" if options[:verbose]
+        end
+      end
+
+      # Thor subcommand for building a .deb package for an rosett-ai engine plugin.
+      #
+      # Replaces the per-engine packaging/build-deb.sh shell scripts with a
+      # unified Ruby implementation that auto-detects engine name and version
+      # from the gemspec, derives the Ruby ABI from the current runtime, and
+      # packages with fpm.
+      #
+      # Build tooling references:
+      #   fpm  — https://github.com/jordansissel/fpm
+      class BuildEngine < ::Thor
+        include RosettAi::Formatting
+
+        default_task :create
+
+        INSTALL_BASE = '/opt/rosett-ai/embedded/lib/ruby/gems'
+
+        desc 'create', 'Build a .deb package for an rosett-ai engine plugin'
+        long_desc <<~LONGDESC
+          Builds a .deb package for an rosett-ai engine plugin by auto-detecting
+          the engine name and version from the gemspec. The package installs
+          the gem into /opt/rosett-ai/embedded/ and depends on the Rosett-AI core package.
+
+          Requires gem and fpm. Run from the engine repo directory or use --path.
+
+          EXAMPLES
+
+            raictl build engine
+            raictl build engine --path ../rosett-ai-engine-claude --verbose
+            raictl build engine --rai-min-version 1.0.0 --output-dir /tmp/pkg
+        LONGDESC
+        method_option :verbose,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Show detailed build output'
+        method_option :path,
+                      type: :string,
+                      default: nil,
+                      desc: 'Engine repo directory (default: current directory)'
+        method_option :output_dir,
+                      type: :string,
+                      default: 'pkg',
+                      desc: 'Directory for the produced .deb file'
+        method_option :rai_min_version,
+                      type: :string,
+                      default: nil,
+                      desc: 'Minimum Rosett-AI dependency version (default: current Rosett-AI version)'
+        method_option :build_iteration,
+                      type: :numeric,
+                      default: 1,
+                      desc: 'Package build iteration (release number)'
+
+        def create
+          resolve_engine_dir!
+          detect_gemspec!
+          parse_gemspec!
+          print_engine_header
+
+          run_stage(:validate) { validate_engine_environment! }
+          run_stage(:gem_build) { build_gem! }
+          run_stage(:staging) { prepare_staging! }
+          run_stage(:gem_install) { install_gem_to_staging! }
+          run_stage(:package) { build_engine_package! }
+
+          print_engine_summary(:success)
+        rescue ::Thor::Error => e
+          print_engine_summary(:failed) unless @summary_printed
+          raise e
+        end
+
+        private
+
+        # -- resolution --------------------------------------------------------
+
+        def resolve_engine_dir!
+          dir = options[:path] || ENV.fetch('RAI_ORIGINAL_PWD', Dir.pwd)
+          @engine_dir = Pathname.new(dir).expand_path
+          abort_engine("Directory does not exist: #{@engine_dir}") unless @engine_dir.directory?
+        end
+
+        def detect_gemspec!
+          candidates = Dir.glob(@engine_dir.join('rosett-ai-engine-*.gemspec').to_s)
+          case candidates.length
+          when 0
+            abort_engine(::I18n.t('rosett_ai.cli.build_engine.no_gemspec', dir: @engine_dir))
+          when 1
+            @gemspec_path = Pathname.new(candidates.first)
+          else
+            abort_engine(::I18n.t('rosett_ai.cli.build_engine.multiple_gemspecs', dir: @engine_dir))
+          end
+        end
+
+        def parse_gemspec!
+          spec = Gem::Specification.load(@gemspec_path.to_s)
+          abort_engine("Failed to load gemspec: #{@gemspec_path}") unless spec
+
+          @engine_name = spec.name
+          @engine_version = spec.version.to_s
+          log_verbose("Detected engine: #{@engine_name} v#{@engine_version}")
+        end
+
+        # -- paths -------------------------------------------------------------
+
+        def ruby_abi
+          @ruby_abi ||= RbConfig::CONFIG['ruby_version']
+        end
+
+        def staging_dir
+          @staging_dir ||= @engine_dir.join('tmp', 'staging')
+        end
+
+        def gem_install_dir
+          @gem_install_dir ||= "#{INSTALL_BASE}/#{ruby_abi}"
+        end
+
+        def staging_gem_dir
+          @staging_gem_dir ||= staging_dir.join(gem_install_dir.delete_prefix('/'))
+        end
+
+        def output_dir
+          @output_dir ||= @engine_dir.join(options[:output_dir]).tap { |d| FileUtils.mkdir_p(d) }
+        end
+
+        def gem_file
+          @gem_file ||= @engine_dir.join('tmp', "#{@engine_name}-#{@engine_version}.gem")
+        end
+
+        def rai_min_version
+          @rai_min_version ||= options[:rai_min_version] || RosettAi::VERSION
+        end
+
+        # -- validation --------------------------------------------------------
+
+        def validate_engine_environment!
+          ['gem', 'fpm'].each do |cmd|
+            next if command_available?(cmd)
+
+            abort_engine("'#{cmd}' is not installed.")
+          end
+          log_verbose('Engine build environment validated')
+        end
+
+        def command_available?(cmd)
+          ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? do |dir|
+            File.executable?(File.join(dir, cmd))
+          end
+        end
+
+        # -- build stages ------------------------------------------------------
+
+        def build_gem!
+          spinner = build_spinner("Building #{@engine_name}-#{@engine_version}.gem...")
+          FileUtils.mkdir_p(gem_file.dirname)
+
+          success = run_command(
+            'gem', 'build', @gemspec_path.to_s,
+            '--output', gem_file.to_s,
+            chdir: @engine_dir.to_s
+          )
+          return spinner.success(Rainbow(' done').green) if success
+
+          spinner.error(Rainbow(' failed').red)
+          abort_engine('gem build failed.')
+        end
+
+        def prepare_staging!
+          FileUtils.rm_rf(staging_dir)
+          FileUtils.mkdir_p(staging_gem_dir)
+          log_verbose("Staging tree at #{staging_dir}")
+        end
+
+        def install_gem_to_staging!
+          spinner = build_spinner('Installing gem into staging tree...')
+          success = run_command(
+            'gem', 'install',
+            '--local',
+            '--install-dir', staging_gem_dir.to_s,
+            '--no-document',
+            '--ignore-dependencies',
+            gem_file.to_s
+          )
+          return spinner.success(Rainbow(' done').green) if success
+
+          spinner.error(Rainbow(' failed').red)
+          abort_engine('gem install into staging failed.')
+        end
+
+        def build_engine_package!
+          spinner = build_spinner('Building .deb package with fpm...')
+
+          fpm_args = [
+            'fpm',
+            '-s', 'dir',
+            '-t', 'deb',
+            '--name', @engine_name,
+            '--version', @engine_version,
+            '--iteration', options[:build_iteration].to_s,
+            '--maintainer', 'NeatNerds <query@neatnerds.be>',
+            '--vendor', 'NeatNerds',
+            '--description', "rosett-ai engine plugin: #{@engine_name}",
+            '--url', "https://gitlab.neatnerds.be/neatnerds/#{@engine_name}",
+            '--license', 'GPL-3.0-only',
+            '--architecture', 'all',
+            '--category', 'devel',
+            '--depends', "rosett-ai (>= #{rai_min_version})",
+            '--directories', gem_install_dir,
+            '--deb-compression', 'xz',
+            '--deb-field', "Vcs-Git: https://gitlab.neatnerds.be/neatnerds/#{@engine_name}.git",
+            '--deb-field', "Build-Commit: #{engine_git_commit_sha}",
+            '--deb-field', "Build-Branch: #{engine_git_branch}",
+            '--deb-field', "Build-Date: #{Time.now.utc.iso8601}",
+            '--package', output_dir.join(package_filename).to_s,
+            '--force',
+            '-C', staging_dir.to_s,
+            '.'
+          ]
+
+          success = run_command(*fpm_args)
+          return spinner.success(Rainbow(' done').green) if success
+
+          spinner.error(Rainbow(' failed').red)
+          abort_engine('fpm packaging failed.')
+        end
+
+        def package_filename
+          "#{@engine_name}_#{@engine_version}-#{options[:build_iteration]}_all.deb"
+        end
+
+        # -- output ------------------------------------------------------------
+
+        def print_engine_header
+          puts
+          puts Rainbow('raictl engine build').bright
+          puts "  Engine:        #{@engine_name}"
+          puts "  Version:       #{@engine_version}"
+          puts "  Ruby ABI:      #{ruby_abi}"
+          puts "  Source:        #{@engine_dir}"
+          puts "  Output:        #{output_dir}"
+          puts "  rai dep:      >= #{rai_min_version}"
+          puts
+        end
+
+        def print_engine_summary(status)
+          @summary_printed = true
+          puts
+
+          if status == :success
+            puts Rainbow('Build Complete').green.bright
+            deb = output_dir.join(package_filename)
+            if deb.exist?
+              puts "  Package: #{deb}"
+              puts "  Size:    #{format_size(deb.size)}"
+            end
+          else
+            puts Rainbow('Build Failed').red.bright
+            puts "  Reason: #{@failure_reason}" if @failure_reason
+          end
+          puts
+        end
+
+        # -- stages tracking ---------------------------------------------------
+
+        def run_stage(name)
+          log_verbose("Stage #{name}: started")
+          yield
+          log_verbose("Stage #{name}: completed")
+        rescue ::Thor::Error
+          @failed_stage = name
+          raise
+        end
+
+        # -- helpers -----------------------------------------------------------
+
+        def build_spinner(message)
+          spinner = TTY::Spinner.new("[:spinner] #{message}", format: :dots, clear: !options[:verbose])
+          spinner.auto_spin
+          spinner
+        end
+
+        def run_command(*cmd, chdir: nil)
+          kwargs = {}
+          kwargs[:chdir] = chdir if chdir
+          kwargs[[:out, :err]] = File::NULL unless options[:verbose]
+          system(*cmd, **kwargs)
+        end
+
+        def engine_git_commit_sha
+          IO.popen(['git', '-C', @engine_dir.to_s, 'rev-parse', '--short', 'HEAD'], err: File::NULL, &:read).strip
+            .then { |s| s.empty? ? 'unknown' : s }
+        rescue StandardError
+          'unknown'
+        end
+
+        def engine_git_branch
+          IO.popen(['git', '-C', @engine_dir.to_s, 'rev-parse', '--abbrev-ref', 'HEAD'], err: File::NULL, &:read).strip
+            .then { |s| s.empty? ? 'unknown' : s }
+        rescue StandardError
+          'unknown'
+        end
+
+        def abort_engine(message)
+          @failure_reason = message
+          raise ::Thor::Error, "Error: #{message}"
+        end
+
+        def log_verbose(message)
+          puts "  #{message}" if options[:verbose]
+        end
+
+        # format_size is provided by RosettAi::Formatting
+      end
+
+      # Parent Thor group for build subcommands
+      class Build < ::Thor
+        def self.exit_on_failure?
+          true
+        end
+
+        desc 'package', 'Build a .deb package using fpm + ruby-build'
+        subcommand 'package', BuildPackage
+
+        desc 'engine', 'Build a .deb package for an rosett-ai engine plugin'
+        subcommand 'engine', BuildEngine
+      end
+    end
+  end
+end