depot-linux 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39c0c6fedfcedab5ac5602cf96e2f1236c0d09b5a9395e34ed06ad80e8e902d8
+  data.tar.gz: f996a7aacd1f21f3925e6132c5b72bdcdee47db201fb8cbc5ebc48a39b83b4a5
+SHA512:
+  metadata.gz: 3859dc9e6f2f4687bbf7a11e9a4553e7f72c1eea9493957e752f8d3665935560d4ecdabeda93e7fb0ad9e773aedc807eadcf88048b371e94cc226dd409a1adea
+  data.tar.gz: cee4fb7b50e82c92d2e04950f78ab46560801757f7f4b605286a221f516b821277381b9738647fb7bc084101c1ba519e23d02cdf95eb02e5d4bcc9e45b090160

data/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org/"
+
+%w[
+  rice
+  qtcore
+  qtgui
+  qtwidgets
+].each do |lib|
+  gem "ruby-qt6-#{lib}", path: "ruby-qt6-main/#{lib}"
+end

data/README.md

@@ -0,0 +1,56 @@
+# Depot
+
+Depot is a Ruby + Qt6 Linux application installer and desktop integration layer. It presents software as one installable thing while the internals choose the right backend. The current build supports AppImage installation, portable `.deb` extraction, portable `.rpm` extraction, `.flatpakref` installation, and portable tar archive integration through the shared CLI/GUI core.
+
+## Run
+
+```sh
+bundle install
+./bin/setup-rubyqt6
+./bin/depot --help
+./bin/depot-gui
+```
+
+The CLI works without Qt loading. The GUI requires the local RubyQt6 native extensions built by `bin/setup-rubyqt6`.
+
+## Commands
+
+```sh
+./bin/depot inspect ./App.AppImage
+./bin/depot install ./App.AppImage
+./bin/depot inspect ./App.deb
+./bin/depot install ./App.deb
+./bin/depot inspect ./App.rpm
+./bin/depot install ./App.rpm
+./bin/depot inspect ./App.flatpakref
+./bin/depot install ./App.flatpakref
+./bin/depot inspect ./App.tar.gz
+./bin/depot install ./App.tar.gz
+./bin/depot list
+./bin/depot info app
+./bin/depot uninstall app
+./bin/depot update app
+./bin/depot update --all
+./bin/depot update-source app https://example.com/App.AppImage
+./bin/depot sandbox app enabled
+./bin/depot doctor
+./bin/depot settings
+```
+
+Installed applications are copied under `~/.local/share/depot/apps`, manifests live under `~/.local/share/depot/manifests`, and desktop entries are created under `~/.local/share/applications`.
+
+Sample packages used by tests and local backend checks live under `fixtures/`, grouped by format.
+
+`.deb` support is intentionally universal-first: Depot parses Debian packages itself, extracts installable files under Depot's user-local app directory, rewrites desktop launchers/icons, and does not require or call `apt`, `dpkg`, `sudo`, or Debian maintainer scripts. Packages that rely on Debian-family dependencies, services, or maintainer-script side effects may still need native distro installation or a future compatibility runtime.
+
+`.rpm` support follows the same universal-first model: Depot parses RPM headers for package metadata, requirements, scriptlets, payload format, desktop entries, and icons, then extracts the payload under Depot's user-local app directory through libarchive/`bsdtar`. It does not require or call `rpm`, `dnf`, `zypper`, `sudo`, or RPM scriptlets. Packages that rely on RPM-family dependencies, services, users, policies, or scriptlet side effects may still need native distro installation or a future compatibility runtime.
+
+`.flatpakref` support uses Flatpak as the backend instead of unpacking the application itself. Depot parses the ref for transparency, runs `flatpak install --user --from`, records a Depot manifest, creates a small launch wrapper, and calls `flatpak uninstall --user` when removing the app. Flatpak remains responsible for downloads, remotes, runtime dependencies, sandboxing, exported desktop entries, and updates.
+
+Tar archive support is also portable-first: Depot inspects `.tar.gz` / `.tgz` archives, extracts them user-locally, reuses or generates desktop launchers, copies icons when possible, and never runs installer scripts from the archive.
+
+Updates are enabled by default and can be disabled through settings. Flatpak apps update through `flatpak update --user`; AppImage, `.deb`, `.rpm`, and tar archive installs update by reinstalling from their original source file when that file is still available. You can also attach an HTTPS update URL with `depot update-source APP_ID HTTPS_URL`; Depot streams the download to a temporary file, enforces a size limit, inspects the package before uninstalling anything, and refuses updates that switch package families.
+
+Sandboxing is managed globally in Settings and per app from the Installed page. Portable AppImage, `.deb`, `.rpm`, and tar archive installs use a generated Bubblewrap launcher when sandboxing is enabled; Flatpak apps keep using Flatpak's own sandbox and permission model. If `bwrap` is missing, Depot falls back to the normal launcher instead of making the app unlaunchable.
+
+`depot doctor` checks required helper tools, Depot data paths, installed manifests, launchers, desktop entries, and original install sources.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/bin/depot

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "depot/cli"
+
+exit Depot::CLI.new.run(ARGV)

data/bin/depot-gui

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  nil
+end
+
+require "depot/gui/app"
+
+Depot::GUI::App.run

data/bin/setup-rubyqt6

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require "etc"
+require "open3"
+
+ROOT = File.expand_path("..", __dir__)
+GEMS = %w[rice qtcore qtgui qtwidgets].freeze
+LIB_TARGETS = {
+  "rice" => "lib/qt6/rice",
+  "qtcore" => "lib/qt6/qtcore",
+  "qtgui" => "lib/qt6/qtgui",
+  "qtwidgets" => "lib/qt6/qtwidgets"
+}.freeze
+QT_HEADERS = `qmake6 -query QT_INSTALL_HEADERS 2>/dev/null`.strip
+QT_HEADERS = `qmake -query QT_INSTALL_HEADERS 2>/dev/null`.strip if QT_HEADERS.empty?
+
+def run(*cmd, chdir:)
+  puts "$ #{cmd.join(" ")}"
+  env = { "BUNDLE_GEMFILE" => File.join(ROOT, "Gemfile") }
+  system(env, *cmd, chdir:) || abort("Command failed: #{cmd.join(" ")}")
+end
+
+def mark_build_complete(gem_name)
+  script = <<~RUBY
+    require "fileutils"
+    spec = Gem::Specification.find_all_by_name("ruby-qt6-#{gem_name}").first
+    abort("Could not find ruby-qt6-#{gem_name} spec") unless spec
+    FileUtils.mkdir_p(File.dirname(spec.gem_build_complete_path))
+    FileUtils.touch(spec.gem_build_complete_path)
+  RUBY
+  run("bundle", "exec", "ruby", "-e", script, chdir: ROOT)
+end
+
+def make_args(gem_name)
+  flags = ["-DRUBYQT6_BUILD_#{gem_name.upcase}_LIB"]
+  flags << "-I#{QT_HEADERS}" unless QT_HEADERS.empty?
+  %w[QtCore QtGui QtWidgets].each do |qt_module|
+    flags << "-I#{File.join(QT_HEADERS, qt_module)}" unless QT_HEADERS.empty?
+    version_dir = Dir[File.join(QT_HEADERS, qt_module, "*.*.*")].first
+    next unless version_dir
+
+    flags << "-I#{version_dir}"
+    flags << "-I#{File.join(version_dir, qt_module)}"
+  end
+
+  args = ["cppflags=#{flags.join(" ")}"]
+  if gem_name != "rice"
+    rice_so = File.join(ROOT, "ruby-qt6-main", "rice", "lib", "qt6", "rice", "rice.so")
+    args << "LOCAL_LIBS=#{rice_so}"
+  end
+  args
+end
+
+GEMS.each do |gem_name|
+  gem_dir = File.join(ROOT, "ruby-qt6-main", gem_name)
+  ext_dir = File.join(gem_dir, "ext", "qt6", gem_name)
+  target_dir = File.join(gem_dir, LIB_TARGETS.fetch(gem_name))
+  FileUtils.rm_f(File.join(ext_dir, "Makefile"))
+  FileUtils.rm_f(Dir.glob(File.join(ext_dir, "*.{o,so}")))
+  run("bundle", "exec", "ruby", "extconf.rb", chdir: ext_dir)
+  run("make", "-j#{Etc.nprocessors}", *make_args(gem_name), chdir: ext_dir)
+  FileUtils.mkdir_p(target_dir)
+  Dir.glob(File.join(ext_dir, "*.so")).each do |shared_object|
+    FileUtils.cp(shared_object, target_dir)
+    puts "installed #{File.basename(shared_object)} -> #{target_dir}"
+  end
+  mark_build_complete(gem_name)
+end
+
+puts "RubyQt6 native extensions are ready."

data/fixtures/flatpakrefs/org.qbittorrent.qBittorrent.flatpakref

@@ -0,0 +1,10 @@
+[Flatpak Ref]
+Name=org.qbittorrent.qBittorrent
+Branch=stable
+Title=org.qbittorrent.qBittorrent from flathub
+IsRuntime=false
+Url=https://dl.flathub.org/repo/
+SuggestRemoteName=flathub
+GPGKey=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
+RuntimeRepo=https://dl.flathub.org/repo/flathub.flatpakrepo
+

data/lib/depot/app_customizer.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require_relative "desktop_entry"
+require_relative "manifest_store"
+require_relative "paths"
+require_relative "result"
+require_relative "sandbox"
+
+module Depot
+  class AppCustomizer
+    ICON_EXTENSIONS = [".png", ".svg", ".xpm"].freeze
+
+    def initialize(store: ManifestStore.new)
+      @store = store
+    end
+
+    def rename(app_id, title)
+      manifest = @store.find(app_id)
+      return Result.err("No Depot manifest found for #{app_id}.") unless manifest
+
+      title = title.to_s.strip
+      return Result.err("Title cannot be empty.") if title.empty?
+
+      ensure_defaults(manifest)
+      manifest["display_name"] = title
+      manifest["customizations"]["display_name"] = title
+      persist(manifest)
+    end
+
+    def change_icon(app_id, source_path)
+      manifest = @store.find(app_id)
+      return Result.err("No Depot manifest found for #{app_id}.") unless manifest
+
+      source_path = File.expand_path(source_path.to_s)
+      return Result.err("Icon file does not exist.") unless File.file?(source_path)
+
+      ext = File.extname(source_path).downcase
+      return Result.err("Choose a PNG, SVG, or XPM icon.") unless ICON_EXTENSIONS.include?(ext)
+
+      ensure_defaults(manifest)
+      remove_custom_icon(manifest)
+
+      icon_name = "#{manifest.fetch("app_id")}-custom"
+      target_dir = File.join(Paths.icon_root, icon_theme_size(source_path, ext), "apps")
+      FileUtils.mkdir_p(target_dir)
+      target = File.join(target_dir, "#{icon_name}#{ext}")
+      FileUtils.cp(source_path, target)
+
+      manifest["custom_icon"] = {
+        "source" => source_path,
+        "path" => target,
+        "icon_name" => icon_name,
+        "set_at" => Time.now.utc.iso8601
+      }
+      manifest["created_files"] = (manifest["created_files"].to_a + [target]).uniq
+      persist(manifest)
+    rescue SystemCallError => e
+      Result.err("Could not change icon: #{e.message}")
+    end
+
+    def reset(app_id)
+      manifest = @store.find(app_id)
+      return Result.err("No Depot manifest found for #{app_id}.") unless manifest
+
+      ensure_defaults(manifest)
+      remove_custom_icon(manifest)
+      manifest["display_name"] = manifest.fetch("default_display_name")
+      manifest.delete("custom_icon")
+      manifest["customizations"] = {}
+      persist(manifest)
+    end
+
+    private
+
+    def ensure_defaults(manifest)
+      manifest["default_display_name"] ||= manifest.fetch("display_name")
+      manifest["default_icon_name"] = default_icon_name(manifest) unless manifest.key?("default_icon_name")
+      manifest["customizations"] ||= {}
+    end
+
+    def default_icon_name(manifest)
+      manifest["icons"].to_a.any? ? manifest.fetch("app_id") : nil
+    end
+
+    def persist(manifest)
+      rewrite_desktop_entry(manifest)
+      path = @store.write(manifest)
+      Result.ok(manifest.merge("manifest_path" => path))
+    rescue SystemCallError => e
+      Result.err("Could not update app integration: #{e.message}")
+    end
+
+    def rewrite_desktop_entry(manifest)
+      desktop_path = manifest["desktop_entry"]
+      return unless desktop_path && !desktop_path.empty?
+
+      FileUtils.mkdir_p(File.dirname(desktop_path))
+      entry = DesktopEntry.new(
+        app_id: manifest.fetch("app_id"),
+        name: manifest.fetch("display_name"),
+        exec_path: Sandbox.launch_path(manifest),
+        icon_name: active_icon_name(manifest)
+      )
+      File.write(desktop_path, entry.contents)
+      manifest["created_files"] = (manifest["created_files"].to_a + [desktop_path]).uniq
+    end
+
+    def active_icon_name(manifest)
+      custom = manifest["custom_icon"]
+      return custom["path"] if custom && custom["path"].to_s != ""
+
+      manifest["default_icon_name"]
+    end
+
+    def icon_theme_size(path, ext)
+      return "scalable" if ext == ".svg"
+      return png_size(path) if ext == ".png"
+
+      "256x256"
+    end
+
+    def png_size(path)
+      File.open(path, "rb") do |file|
+        header = file.read(24)
+        return "256x256" unless header&.start_with?("\x89PNG\r\n\x1A\n".b)
+
+        width, height = header.byteslice(16, 8).unpack("NN")
+        return "256x256" if width.to_i <= 0 || height.to_i <= 0
+
+        "#{width}x#{height}"
+      end
+    rescue SystemCallError
+      "256x256"
+    end
+
+    def remove_custom_icon(manifest)
+      custom = manifest["custom_icon"]
+      return unless custom
+
+      path = custom["path"]
+      FileUtils.rm_f(path) if path && custom_icon_path?(path)
+      manifest["created_files"] = manifest["created_files"].to_a - [path]
+    end
+
+    def custom_icon_path?(path)
+      expanded = File.expand_path(path)
+      expanded.start_with?(File.expand_path(Paths.icon_root) + File::SEPARATOR)
+    end
+  end
+end

data/lib/depot/assets.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Depot
+  module Assets
+    module_function
+
+    def logo_path
+      File.expand_path("../../fixtures/assets/download.png", __dir__)
+    end
+  end
+end

data/lib/depot/backends/app_image.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "shellwords"
+require "tmpdir"
+require "timeout"
+require "time"
+require_relative "../desktop_entry"
+require_relative "../paths"
+require_relative "../result"
+require_relative "../util"
+
+module Depot
+  module Backends
+    class AppImage
+      EXTRACTION_TIMEOUT_SECONDS = 25
+
+      def initialize(store:)
+        @store = store
+      end
+
+      def install(inspection, settings: {})
+        return Result.err("AppImage backend cannot install #{inspection.format}") unless inspection.appimage?
+
+        Paths.ensure_base_dirs
+
+        taken = @store.ids
+        app_id = Util.unique_id(Util.slug(inspection.display_name), taken)
+        app_dir = File.join(Paths.apps_dir, app_id)
+        FileUtils.mkdir_p(app_dir)
+
+        installed_name = File.basename(inspection.input)
+        installed_path = File.join(app_dir, installed_name)
+        FileUtils.cp(inspection.input, installed_path)
+        FileUtils.chmod(File.stat(installed_path).mode | 0o111, installed_path)
+
+        metadata = extract_metadata(installed_path, app_id)
+        display_name = metadata.fetch("name", inspection.display_name)
+        icon_paths = metadata.fetch("icons", [])
+        icon_name = icon_paths.any? ? app_id : nil
+
+        desktop_path = nil
+        if settings.fetch("desktop_integration", true)
+          desktop_path = File.join(Paths.desktop_entries_dir, "depot-#{app_id}.desktop")
+          entry = DesktopEntry.new(app_id:, name: display_name, exec_path: installed_path, icon_name:)
+          File.write(desktop_path, entry.contents)
+        end
+
+        manifest = {
+          "schema_version" => 1,
+          "app_id" => app_id,
+          "display_name" => display_name,
+          "default_display_name" => display_name,
+          "backend" => "appimage",
+          "install_source" => File.expand_path(inspection.input),
+          "source_sha256" => inspection.sha256,
+          "source_size" => inspection.size,
+          "installed_executable" => installed_path,
+          "desktop_entry" => desktop_path,
+          "icons" => icon_paths,
+          "default_icon_name" => icon_name,
+          "customizations" => {},
+          "created_files" => ([installed_path, desktop_path] + icon_paths).compact,
+          "created_dirs" => [app_dir],
+          "installed_at" => Time.now.utc.iso8601,
+          "permissions" => permission_summary(installed_path),
+          "sandbox" => {
+            "enabled" => false,
+            "preference" => settings.fetch("sandbox_preference", "ask")
+          },
+          "update" => {
+            "mechanism" => "manual",
+            "source" => File.expand_path(inspection.input)
+          },
+          "warnings" => inspection.warnings + metadata.fetch("warnings", [])
+        }
+
+        manifest_path = @store.write(manifest)
+        Result.ok(manifest.merge("manifest_path" => manifest_path), warnings: manifest["warnings"])
+      rescue SystemCallError => e
+        Result.err("Install failed: #{e.message}")
+      end
+
+      private
+
+      def extract_metadata(installed_path, app_id)
+        warnings = []
+        desktop_name = nil
+        icon_paths = []
+
+        Dir.mktmpdir("depot-appimage-") do |dir|
+          stdout, stderr, status = run_extract(installed_path, dir)
+          unless status&.success?
+            warnings << "Could not extract AppImage metadata; generated a desktop entry from the file name."
+            warnings << stderr.strip unless stderr.to_s.strip.empty?
+            warnings << stdout.strip unless stdout.to_s.strip.empty?
+            return { "warnings" => warnings, "icons" => icon_paths }
+          end
+
+          root = File.join(dir, "squashfs-root")
+          desktop = Dir.glob(File.join(root, "**", "*.desktop")).first
+          desktop_metadata = parse_desktop_metadata(desktop)
+          desktop_name = desktop_metadata["name"]
+          icon_paths = install_icons(app_id, find_icons(root, desktop_metadata["icon"]))
+        end
+
+        { "name" => desktop_name, "icons" => icon_paths, "warnings" => warnings }.compact
+      rescue Timeout::Error
+        { "warnings" => ["Timed out while extracting AppImage metadata."], "icons" => [] }
+      rescue SystemCallError => e
+        { "warnings" => ["Could not extract AppImage metadata: #{e.message}"], "icons" => [] }
+      end
+
+      def run_extract(installed_path, dir)
+        Timeout.timeout(EXTRACTION_TIMEOUT_SECONDS) do
+          Open3.capture3({ "APPIMAGE_EXTRACT_AND_RUN" => "1" }, installed_path, "--appimage-extract", chdir: dir)
+        end
+      end
+
+      def parse_desktop_metadata(path)
+        metadata = {}
+        return metadata unless path && File.exist?(path)
+
+        File.readlines(path, chomp: true).each do |line|
+          key, value = line.split("=", 2)
+          next unless value
+
+          value = value.strip
+          metadata["name"] = value if key == "Name" && !value.empty?
+          metadata["icon"] = value if key == "Icon" && !value.empty?
+        end
+        metadata
+      end
+
+      def find_icons(root, preferred_icon = nil)
+        icons = [".png", ".svg", ".xpm"].flat_map do |ext|
+          Dir.glob(File.join(root, "**", "*#{ext}"))
+        end
+        icons << File.join(root, ".DirIcon")
+        preferred = preferred_icon.to_s
+        preferred_base = File.basename(preferred, ".*")
+
+        icons.select { |path| File.file?(path) && File.size(path).positive? }
+             .uniq { |path| real_icon_path(path) }
+             .sort_by { |path| icon_score(path, preferred_base) }
+             .first(8)
+      end
+
+      def install_icons(app_id, icons)
+        icons.filter_map do |source|
+          ext = icon_extension(source)
+          next unless [".png", ".svg", ".xpm"].include?(ext)
+
+          size = icon_size(source)
+          target_dir = File.join(Paths.icon_root, size, "apps")
+          FileUtils.mkdir_p(target_dir)
+          target = File.join(target_dir, "#{app_id}#{ext}")
+          FileUtils.cp(source, target)
+          target
+        rescue SystemCallError
+          nil
+        end.uniq
+      end
+
+      def icon_size(path)
+        parts = path.split(File::SEPARATOR)
+        found = parts.find { |part| part.match?(/\A\d+x\d+\z/) }
+        return found if found
+
+        icon_extension(path) == ".svg" ? "scalable" : "256x256"
+      end
+
+      def icon_score(path, preferred_base)
+        base = File.basename(path, ".*")
+        ext = icon_extension(path)
+        [
+          preferred_base.empty? || base != preferred_base ? 1 : 0,
+          File.basename(path) == ".DirIcon" ? 0 : 1,
+          ext == ".svg" ? 0 : 1,
+          -File.size(path)
+        ]
+      end
+
+      def icon_extension(path)
+        ext = File.extname(path).downcase
+        return ext unless ext.empty?
+
+        File.extname(real_icon_path(path)).downcase
+      rescue SystemCallError
+        ext
+      end
+
+      def real_icon_path(path)
+        File.realpath(path)
+      rescue SystemCallError
+        path
+      end
+
+      def permission_summary(path)
+        {
+          "executable" => File.executable?(path),
+          "requires_sudo" => false,
+          "writes_outside_depot" => false,
+          "notes" => ["Portable AppImage installed user-locally."]
+        }
+      end
+    end
+  end
+end