dotlayer 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d30157869fd9bd7c0d98d7957fd82879a06db355368ae7a66919d43ba2dac6dc
+  data.tar.gz: 560bf0f69bc6a68083d67739d91a97cbd3f208696313ba97f03619ccbae3901a
+SHA512:
+  metadata.gz: ffe27ed4bf4d65aacd1a52fc1c7697771f53b1fe69b1622a10a0789a2e01ce698d56ce6f4a485256e9b86faf5b696efe974d32dacfdfc894ddfdeb6540bb26fc
+  data.tar.gz: 919ce9855ebfb9a7a5ba0b74c06d818f405bf843ba7505433f3529a89dc6565a5f6a04e5f8bf03853fb45f625b964b19c3e2a8686821f5fced95b7e952f2294d

data/LICENSE

@@ -0,0 +1,9 @@
+Copyright © 2026, Douglas Andrade.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+2. No licensee or downstream recipient may use the Software (including any modified or derivative versions) to directly compete with the original Licensor by offering it to third parties as a hosted, managed, or Software-as-a-Service (SaaS) product or cloud service where the primary value of the service is the functionality of the Software itself.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,192 @@
+# dotlayer
+
+A convention-driven CLI wrapper around [GNU Stow](https://www.gnu.org/software/stow/) for managing dotfiles across multiple machines with layered overrides.
+
+## Why
+
+Managing dotfiles across machines with different OSes, hardware profiles, and Linux distros means lots of conditional logic in install scripts. Dotlayer replaces that with a naming convention: directory names declare when they should be stowed.
+
+```
+config/                     → always stowed
+config-linux/               → stowed on Linux
+config-macos/               → stowed on macOS
+config-omarchy/             → stowed when Omarchy is detected
+config-omarchy-desktop/     → stowed on Omarchy + desktop profile
+config-omarchy-laptop/      → stowed on Omarchy + laptop profile
+config-doximity/            → stowed when doximity group is detected
+```
+
+No config file needed — just name your directories and dotlayer figures out the rest.
+
+## Install
+
+```sh
+gem install dotlayer
+```
+
+Or clone and run directly:
+
+```sh
+git clone https://github.com/douglas/dotlayer.git
+export PATH="$HOME/src/dotlayer/exe:$PATH"
+```
+
+**Requirements:** Ruby >= 3.2, GNU Stow
+
+## Quick start
+
+```sh
+# See what dotlayer detects on your system
+dotlayer status
+
+# Stow all matching packages
+dotlayer install
+
+# Pull latest changes and re-stow
+dotlayer update
+
+# Check for broken symlinks and missing deps
+dotlayer doctor
+
+# Move existing config into a stow package
+dotlayer adopt ~/.config/lazygit config
+
+# Move config into the private repo
+dotlayer adopt --private ~/.config/lazysql config
+```
+
+## How it works
+
+Dotlayer auto-detects four things about your system:
+
+| Detection | Method | Example |
+|-----------|--------|---------|
+| **OS** | `RbConfig::CONFIG["host_os"]` | `linux`, `macos` |
+| **Profile** | `hostnamectl chassis` or `$DOTLAYER_PROFILE` | `desktop`, `laptop` |
+| **Distro** | Shell commands from config | `omarchy`, `fedora` |
+| **Group** | Shell commands from config | `doximity`, `acme` |
+
+It then scans your dotfiles repo for directories matching these tags and stows them in layer order:
+
+1. **Base packages** — `stow`, `bin`, `git`, `zsh`, `config`
+2. **OS layer** — `config-linux` or `config-macos`
+3. **Distro layer** — `config-omarchy`
+4. **Distro + profile** — `config-omarchy-desktop`
+5. **Group layer** — `config-doximity`
+
+Each layer can add files but never conflict with earlier layers (Stow constraint).
+
+## Configuration
+
+Dotlayer works with zero configuration using sensible defaults. For customization, create a `dotlayer.yml`:
+
+```yaml
+target: ~
+
+repos:
+  - path: ~/.public_dotfiles
+  - path: ~/.private_dotfiles
+    private: true
+
+packages:
+  - stow
+  - bin
+  - git
+  - zsh
+  - config
+
+profiles:
+  detect: hostnamectl chassis
+  env: DOTLAYER_PROFILE
+
+distros:
+  omarchy:
+    detect: test -d ~/.local/share/omarchy
+  fedora:
+    detect: . /etc/os-release && test "$ID" = "fedora"
+
+groups:
+  doximity:
+    detect: test -d ~/src/dox
+
+system_files:
+  - source: config-linux/etc/systemd/system-sleep/xremap-restart.sh
+    dest: /etc/systemd/system-sleep/xremap-restart.sh
+    mode: "0755"
+
+hooks:
+  after_system_files:
+    - sudo udevadm control --reload-rules
+```
+
+Config file is discovered automatically from:
+- `~/.config/dotlayer/dotlayer.yml`
+- `~/.public_dotfiles/dotlayer.yml`
+- `~/.dotfiles/dotlayer.yml`
+
+## Multi-repo support
+
+Dotlayer supports multiple repos. Each repo can have its own base packages:
+
+```yaml
+repos:
+  - path: ~/.public_dotfiles
+  - path: ~/.private_dotfiles
+    private: true
+    packages:
+      - config
+      - fonts
+```
+
+Repos without any matching base packages automatically stow all their top-level directories (sorted alphabetically). This is useful for private repos that only contain standalone packages.
+
+Repos are processed in order — packages from the first repo are stowed before packages from the second.
+
+## CLI reference
+
+```
+dotlayer [options] <command>
+
+Commands:
+  install     Detect system, stow all layers, install system files
+  update      Pull repos, re-stow all layers
+  status      Show detected OS, profile, distros, groups, and packages
+  doctor      Check for broken symlinks, missing repos, missing stow
+  adopt       Move config files into a stow package and restow
+  version     Print version
+
+Options:
+  -c, --config PATH   Config file path
+  -n, --dry-run       Show what would be done without making changes
+  -p, --private       Use private repo (for adopt command)
+  -v, --verbose       Verbose output
+```
+
+### adopt
+
+Moves existing config files or directories into a stow package, then restows so the originals become symlinks managed by stow.
+
+```sh
+# Move a single directory
+dotlayer adopt ~/.config/lazygit config
+
+# Move multiple paths at once
+dotlayer adopt ~/.config/lazygit ~/.config/lazydocker config
+
+# Move into the private repo
+dotlayer adopt --private ~/.config/lazysql config
+
+# Preview without moving anything
+dotlayer adopt --dry-run ~/.config/lazygit config
+```
+
+The last argument is always the package name. Dotlayer finds the first repo containing that package, or falls back to the first repo for new packages.
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — system design, data flow, and class responsibilities
+- [Contributing](CONTRIBUTING.md) — setup, testing, and contribution guidelines
+
+## License
+
+[O-SaaSy](https://osaasy.dev)

data/exe/dotlayer

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "dotlayer"
+
+Dotlayer::CLI.new.run(ARGV)

data/lib/dotlayer/cli.rb

@@ -0,0 +1,84 @@
+require "optparse"
+
+module Dotlayer
+  class CLI
+    def run(argv = ARGV)
+      if argv.first == "--version"
+        puts "dotlayer #{VERSION}"
+        return
+      end
+
+      options = parse_global_options(argv)
+      command = argv.shift
+      config = Config.new(options[:config])
+
+      case command
+      when "status"  then Commands::Status.new(config:).run
+      when "install" then Commands::Install.new(config:, dry_run: options[:dry_run], verbose: options[:verbose]).run
+      when "update"  then Commands::Update.new(config:, dry_run: options[:dry_run], verbose: options[:verbose]).run
+      when "doctor"  then Commands::Doctor.new(config:).run
+      when "adopt"   then run_adopt(config:, argv:, options:)
+      when "version"
+        puts "dotlayer #{VERSION}"
+      else
+        print_usage
+      end
+    end
+
+    private
+
+    def parse_global_options(argv)
+      options = { dry_run: false, verbose: false, config: nil, private: false }
+
+      OptionParser.new do |opts|
+        opts.on("-c", "--config PATH", "Config file path") { |v| options[:config] = v }
+        opts.on("-n", "--dry-run", "Show what would be done") { options[:dry_run] = true }
+        opts.on("-v", "--verbose", "Verbose output") { options[:verbose] = true }
+        opts.on("-p", "--private", "Use private repo") { options[:private] = true }
+      end.parse!(argv)
+
+      options
+    end
+
+    def run_adopt(config:, argv:, options:)
+      package = argv.pop
+      paths = argv
+
+      if paths.empty? || package.nil?
+        abort "Usage: dotlayer adopt <path>... <package>"
+      end
+
+      Commands::Adopt.new(
+        config:, paths:, package:,
+        private_repo: options[:private],
+        dry_run: options[:dry_run], verbose: options[:verbose]
+      ).run
+    end
+
+    def print_usage
+      puts <<~USAGE
+        Usage: dotlayer [options] <command>
+
+        Commands:
+          install   Detect system, stow all layers, install system files
+          update    Pull repos, re-stow all layers
+          status    Show detected OS, profile, distros, and packages
+          doctor    Check for broken symlinks, conflicts, missing deps
+          adopt     Move config into a stow package and restow
+          version   Print version
+
+        Options:
+          -c, --config PATH   Config file path (default: dotlayer.yml in repo)
+          -n, --dry-run       Show what would be done without making changes
+          -p, --private       Use private repo (for adopt command)
+          -v, --verbose       Verbose output
+
+        Examples:
+          dotlayer adopt ~/.config/lazygit config
+          dotlayer adopt ~/.config/lazygit ~/.config/lazydocker config
+          dotlayer adopt --private ~/.config/lazysql config
+
+      USAGE
+    end
+  end
+end

data/lib/dotlayer/commands/adopt.rb

@@ -0,0 +1,88 @@
+require "fileutils"
+
+module Dotlayer
+  module Commands
+    class Adopt
+      include Output
+
+      def initialize(config:, paths:, package:, private_repo: false, dry_run: false, verbose: false)
+        @config = config
+        @paths = paths
+        @package = package
+        @private_repo = private_repo
+        @dry_run = dry_run
+        @verbose = verbose
+        @target = File.expand_path(@config.target)
+      end
+
+      def run
+        repo_path = find_repo
+        unless repo_path
+          abort "Error: package '#{@package}' not found in any repo"
+        end
+
+        stow = Stow.new(target: @target, dry_run: @dry_run, verbose: @verbose)
+
+        @paths.each do |path|
+          adopt_path(File.expand_path(path), repo_path)
+        end
+
+        restow_package(stow, repo_path, @package, verb: "Restowing")
+      end
+
+      private
+
+      def find_repo
+        if @private_repo
+          repo = @config.repos.find(&:private)
+          return repo.path if repo
+          abort "Error: no private repo found in config (add private: true to a repo)"
+        end
+
+        @config.repos.each do |repo|
+          next unless Dir.exist?(repo.path)
+
+          pkg_dir = File.join(repo.path, @package)
+          return repo.path if Dir.exist?(pkg_dir)
+        end
+
+        # Package doesn't exist yet — use first repo
+        @config.repos.first&.path
+      end
+
+      def adopt_path(source, repo_path)
+        unless File.exist?(source)
+          error "  Skipping #{source}: does not exist"
+          return
+        end
+
+        relative = relative_to_target(source)
+        unless relative
+          error "  Skipping #{source}: not under target #{@target}"
+          return
+        end
+
+        dest = File.join(repo_path, @package, relative)
+
+        if File.exist?(dest)
+          warning "  Skipping #{relative}: already exists in #{@package}"
+          return
+        end
+
+        puts "  Moving #{green(relative)} → #{@package}/"
+
+        return if @dry_run
+
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.mv(source, dest)
+      end
+
+      def relative_to_target(path)
+        path = File.expand_path(path)
+        return nil unless path.start_with?("#{@target}/")
+
+        path.delete_prefix("#{@target}/")
+      end
+    end
+  end
+end

data/lib/dotlayer/commands/doctor.rb

@@ -0,0 +1,109 @@
+module Dotlayer
+  module Commands
+    class Doctor
+      include Output
+
+      def initialize(config:, detector: nil)
+        @config = config
+        @detector = detector || Detector.new(config: @config)
+        @issues = []
+      end
+
+      def run
+        detection = @detector.detect
+        resolver = Resolver.new(config: @config, detection: detection)
+        @packages = resolver.resolve
+
+        heading "Dotlayer Doctor"
+        puts
+
+        check_stow_installed
+        check_repos_exist
+        check_packages_exist(@packages)
+        check_broken_symlinks
+
+        puts
+        if @issues.empty?
+          ok "No issues found."
+        else
+          error "#{@issues.size} issue(s) found:"
+          @issues.each { |issue| puts "  - #{issue}" }
+        end
+      end
+
+      private
+
+      def check_stow_installed
+        print "  Checking stow... "
+        if system("which", "stow", out: File::NULL, err: File::NULL)
+          ok "installed"
+        else
+          error "missing"
+          @issues << "GNU Stow is not installed"
+        end
+      end
+
+      def check_repos_exist
+        @config.repos.each do |repo|
+          print "  Checking repo #{repo.path}... "
+          if Dir.exist?(repo.path)
+            ok "exists"
+          else
+            error "missing"
+            @issues << "Repo not found: #{repo.path}"
+          end
+        end
+      end
+
+      def check_packages_exist(packages)
+        packages.each do |repo_path, package|
+          pkg_path = File.join(repo_path, package)
+          unless Dir.exist?(pkg_path)
+            @issues << "Package directory missing: #{pkg_path}"
+          end
+        end
+      end
+
+      def check_broken_symlinks
+        print "  Checking for broken symlinks in #{@config.target}... "
+        broken = find_broken_symlinks(@config.target)
+        if broken.empty?
+          ok "none"
+        else
+          warning "#{broken.size} found"
+          broken.each do |link|
+            target = File.readlink(link) rescue "(deleted)"
+            @issues << "Broken symlink: #{link} -> #{target}"
+          end
+        end
+      end
+
+      def find_broken_symlinks(target)
+        broken = []
+        scan_dirs = @packages.flat_map { |repo_path, package|
+          pkg_dir = File.join(repo_path, package)
+          next [] unless Dir.exist?(pkg_dir)
+
+          Dir.children(pkg_dir).map { |child| File.join(target, child) }
+        }.uniq
+
+        scan_dirs.each do |dir|
+          next unless File.exist?(dir) || File.symlink?(dir)
+
+          if File.symlink?(dir) && !File.exist?(dir)
+            broken << dir
+            next
+          end
+
+          next unless File.directory?(dir)
+
+          Dir.glob(File.join(dir, "**", "*"), File::FNM_DOTMATCH).each do |path|
+            broken << path if File.symlink?(path) && !File.exist?(path)
+          end
+        end
+
+        broken
+      end
+    end
+  end
+end

data/lib/dotlayer/commands/install.rb

@@ -0,0 +1,113 @@
+module Dotlayer
+  module Commands
+    class Install
+      include Output
+
+      def initialize(config:, detector: nil, dry_run: false, verbose: false)
+        @config = config
+        @detector = detector || Detector.new(config: @config)
+        @dry_run = dry_run
+        @verbose = verbose
+      end
+
+      def run
+        detection = @detector.detect
+        resolver = Resolver.new(config: @config, detection: detection)
+        packages = resolver.resolve
+        stow = Stow.new(target: @config.target, dry_run: @dry_run, verbose: @verbose)
+
+        heading "Installing dotfiles (#{detection.os}/#{detection.profile})"
+        puts
+
+        packages.each do |repo_path, package|
+          restow_package(stow, repo_path, package)
+        end
+
+        install_system_files if detection.os == "linux"
+
+        puts
+        puts "Done! #{packages.size} package(s) stowed."
+      end
+
+      private
+
+      def install_system_files
+        return if @config.system_files.empty?
+
+        first_repo = @config.repos.first
+        unless first_repo
+          warning "  Skipping system files: no repos configured"
+          return
+        end
+
+        puts
+        heading "System files"
+
+        unless @dry_run
+          return unless confirm("The following files will be installed with sudo:",
+            @config.system_files.map { |e| e["dest"] })
+        end
+
+        @config.system_files.each do |entry|
+          source = File.expand_path(entry["source"], first_repo.path)
+          dest = entry["dest"]
+          mode = entry["mode"]
+
+          print "  #{dest}... "
+
+          if @dry_run
+            warning("dry-run")
+            next
+          end
+
+          unless system("sudo", "cp", source, dest)
+            error("failed")
+            next
+          end
+
+          if mode && !system("sudo", "chmod", mode, dest)
+            error("chmod failed")
+            next
+          end
+
+          ok
+        end
+
+        run_hooks("after_system_files")
+      end
+
+      def confirm(message, items)
+        puts "  #{message}"
+        items.each { |item| puts "    #{item}" }
+        print "  Continue? [y/N] "
+        if $stdin.gets&.strip&.downcase == "y"
+          true
+        else
+          warning("  Skipped.")
+          false
+        end
+      end
+
+      def run_hooks(name)
+        commands = Array(@config.hooks[name])
+        return if commands.empty?
+
+        puts
+        heading "Running #{name} hooks"
+
+        unless @dry_run
+          return unless confirm("The following commands will be executed:", commands)
+        end
+
+        commands.each do |cmd|
+          print "  #{cmd}... "
+          if @dry_run
+            warning("dry-run")
+          else
+            system(cmd) ? ok : error("failed")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dotlayer/commands/status.rb

@@ -0,0 +1,44 @@
+module Dotlayer
+  module Commands
+    class Status
+      include Output
+
+      def initialize(config:, detector: nil)
+        @config = config
+        @detector = detector || Detector.new(config: @config)
+      end
+
+      def run
+        detection = @detector.detect
+        resolver = Resolver.new(config: @config, detection: detection)
+        packages = resolver.resolve
+
+        print_detection(detection)
+        print_packages(packages)
+      end
+
+      private
+
+      def print_detection(detection)
+        heading "System Detection"
+        puts "  OS:         #{detection.os}"
+        puts "  Profile:    #{detection.profile}"
+        puts "  Distros:    #{detection.distros.empty? ? "(none)" : detection.distros.join(", ")}"
+        puts "  Groups:     #{detection.groups.empty? ? "(none)" : detection.groups.join(", ")}"
+        puts
+      end
+
+      def print_packages(packages)
+        heading "Packages to stow"
+
+        packages.each do |repo_path, package|
+          repo_name = File.basename(repo_path)
+          puts "  #{repo_name}/#{green(package)}"
+        end
+
+        puts
+        puts "  #{packages.size} package(s) total"
+      end
+    end
+  end
+end

data/lib/dotlayer/commands/update.rb

@@ -0,0 +1,64 @@
+require "open3"
+
+module Dotlayer
+  module Commands
+    class Update
+      include Output
+
+      def initialize(config:, detector: nil, dry_run: false, verbose: false)
+        @config = config
+        @detector = detector || Detector.new(config: @config)
+        @dry_run = dry_run
+        @verbose = verbose
+      end
+
+      def run
+        pull_repos
+        restow_packages
+      end
+
+      private
+
+      def pull_repos
+        heading "Pulling repos"
+
+        @config.repos.each do |repo|
+          next unless Dir.exist?(File.join(repo.path, ".git"))
+
+          print "  #{File.basename(repo.path)}... "
+
+          if @dry_run
+            warning("dry-run")
+            next
+          end
+
+          output, status = Open3.capture2e("git", "-C", repo.path, "pull", "--rebase")
+          if status.success?
+            ok
+          else
+            error("failed")
+            puts "    #{output.strip}"
+          end
+        end
+
+        puts
+      end
+
+      def restow_packages
+        detection = @detector.detect
+        resolver = Resolver.new(config: @config, detection: detection)
+        packages = resolver.resolve
+        stow = Stow.new(target: @config.target, dry_run: @dry_run, verbose: @verbose)
+
+        heading "Re-stowing packages"
+
+        packages.each do |repo_path, package|
+          restow_package(stow, repo_path, package, verb: "Restowing")
+        end
+
+        puts
+        puts "Done! #{packages.size} package(s) restowed."
+      end
+    end
+  end
+end

data/lib/dotlayer/config.rb

@@ -0,0 +1,85 @@
+require "yaml"
+
+module Dotlayer
+  Repo = Data.define(:path, :private, :packages)
+
+  class Config
+    DEFAULT_PACKAGES = %w[stow bin git zsh config].freeze
+    DEFAULT_CONFIG_PATHS = %w[
+      ~/.config/dotlayer/dotlayer.yml
+      ~/.public_dotfiles/dotlayer.yml
+      ~/.dotfiles/dotlayer.yml
+    ].freeze
+
+    attr_reader :path
+
+    def initialize(path = nil)
+      @path = path || discover_config
+      @data = load_config
+    end
+
+    def target
+      File.expand_path(@data.fetch("target", "~"))
+    end
+
+    def repos
+      @repos ||= @data.fetch("repos", [{ "path" => "~/.public_dotfiles" }]).filter_map do |entry|
+        path = entry["path"]&.to_s
+        next if path.nil? || path.empty?
+
+        Repo.new(
+          path: File.expand_path(path),
+          private: entry["private"] || false,
+          packages: entry["packages"]&.freeze
+        )
+      end.freeze
+    end
+
+    def packages
+      @packages ||= @data.fetch("packages") { DEFAULT_PACKAGES }.freeze
+    end
+
+    def profile_detect
+      @data.dig("profiles", "detect") || "hostnamectl chassis"
+    end
+
+    def profile_env
+      @data.dig("profiles", "env") || "DOTLAYER_PROFILE"
+    end
+
+    def distros
+      @data.fetch("distros", {})
+    end
+
+    def groups
+      @data.fetch("groups", {})
+    end
+
+    def system_files
+      @data.fetch("system_files", [])
+    end
+
+    def hooks
+      @data.fetch("hooks", {})
+    end
+
+    private
+
+    def load_config
+      return {} unless @path && File.exist?(@path)
+
+      data = YAML.safe_load_file(@path, permitted_classes: [Symbol]) || {}
+      return data if data.is_a?(Hash)
+
+      abort "Error: #{@path} must contain a YAML mapping, got #{data.class}"
+    rescue Psych::SyntaxError => e
+      abort "Error: invalid YAML in #{@path}: #{e.message}"
+    end
+
+    def discover_config
+      DEFAULT_CONFIG_PATHS
+        .map { |p| File.expand_path(p) }
+        .find { |p| File.exist?(p) }
+    end
+  end
+end

data/lib/dotlayer/detector.rb

@@ -0,0 +1,53 @@
+require "open3"
+
+module Dotlayer
+  Detection = Data.define(:os, :profile, :distros, :groups)
+
+  class Detector
+    def initialize(config: Config.new)
+      @config = config
+    end
+
+    def detect
+      Detection.new(os: detect_os, profile: detect_profile, distros: detect_distros, groups: detect_groups)
+    end
+
+    private
+
+    def detect_os
+      case RbConfig::CONFIG["host_os"]
+      when /darwin/ then "macos"
+      when /linux/  then "linux"
+      else "unknown"
+      end
+    end
+
+    def detect_profile
+      from_env = ENV[@config.profile_env]
+      return from_env if from_env && !from_env.empty?
+
+      if @config.profile_detect && !@config.profile_detect.empty?
+        output, status = Open3.capture2(@config.profile_detect)
+        return output.strip if status.success? && !output.strip.empty?
+      end
+
+      "desktop"
+    end
+
+    def detect_distros
+      @config.distros.select { |_name, entry| command_detected?(entry) }.keys
+    end
+
+    def detect_groups
+      @config.groups.select { |_name, entry| command_detected?(entry) }.keys
+    end
+
+    def command_detected?(entry)
+      cmd = entry["detect"]
+      return false unless cmd.is_a?(String) && !cmd.empty?
+
+      _, status = Open3.capture2e("sh", "-c", cmd)
+      status.success?
+    end
+  end
+end

data/lib/dotlayer/output.rb

@@ -0,0 +1,50 @@
+module Dotlayer
+  module Output
+    def heading(text)
+      puts "\e[1m#{text}\e[0m"
+    end
+
+    def ok(text = "ok")
+      puts "\e[32m#{text}\e[0m"
+    end
+
+    def error(text)
+      puts "\e[31m#{text}\e[0m"
+    end
+
+    def warning(text)
+      puts "\e[33m#{text}\e[0m"
+    end
+
+    def info(text)
+      puts "\e[36m#{text}\e[0m"
+    end
+
+    def green(text)
+      "\e[32m#{text}\e[0m"
+    end
+
+    def red(text)
+      "\e[31m#{text}\e[0m"
+    end
+
+    def yellow(text)
+      "\e[33m#{text}\e[0m"
+    end
+
+    def bold(text)
+      "\e[1m#{text}\e[0m"
+    end
+
+    def restow_package(stow, repo_path, package, verb: "Stowing")
+      print "  #{verb} #{green(package)}... "
+      if stow.dry_run?
+        warning("dry-run")
+      elsif stow.restow(repo_path, package)
+        ok
+      else
+        error("failed: #{stow.last_error}")
+      end
+    end
+  end
+end

data/lib/dotlayer/resolver.rb

@@ -0,0 +1,113 @@
+require "set"
+
+module Dotlayer
+  class Resolver
+    def initialize(config:, detection:)
+      @config = config
+      @detection = detection
+    end
+
+    def resolve
+      packages = []
+
+      @config.repos.each do |repo|
+        next unless Dir.exist?(repo.path)
+
+        base_packages = repo.packages || @config.packages
+        packages.concat(resolve_repo(repo, base_packages))
+      end
+
+      packages
+    end
+
+    private
+
+    def resolve_repo(repo, base_packages)
+      # Repos with explicit packages always use layered resolution,
+      # even if the directories don't exist yet
+      if repo.packages || base_packages.any? { |pkg| Dir.exist?(File.join(repo.path, pkg)) }
+        resolve_layered_repo(repo.path, base_packages)
+      else
+        resolve_all_packages(repo.path)
+      end
+    end
+
+    # Repos with base packages use layered convention matching
+    # plus standalone directories that don't match any layer pattern
+    def resolve_layered_repo(repo_path, base_packages)
+      packages = []
+
+      base_packages.each do |pkg|
+        packages << [repo_path, pkg] if Dir.exist?(File.join(repo_path, pkg))
+      end
+
+      dirs = top_level_dirs(repo_path)
+      layers, matched_dirs = resolve_layers(repo_path, base_packages, dirs)
+      packages.concat(layers)
+
+      standalone = resolve_standalone(repo_path, base_packages, matched_dirs, dirs)
+      packages.concat(standalone)
+    end
+
+    # Repos without base packages stow all top-level directories
+    def resolve_all_packages(repo_path)
+      top_level_dirs(repo_path)
+        .sort
+        .map { |d| [repo_path, d] }
+    end
+
+    def resolve_layers(repo_path, base_packages, dirs)
+      os_packages = []
+      distro_packages = []
+      distro_profile_packages = []
+      group_packages = []
+      matched_dirs = Set.new(base_packages)
+
+      dirs.each do |dir|
+        next if base_packages.include?(dir)
+
+        case dir
+        when suffix("-#{@detection.os}")
+          os_packages << [repo_path, dir]
+          matched_dirs << dir
+        when *@detection.distros.map { |d| suffix("-#{d}") }
+          distro_packages << [repo_path, dir]
+          matched_dirs << dir
+        when *@detection.distros.map { |d| suffix("-#{d}-#{@detection.profile}") }
+          distro_profile_packages << [repo_path, dir]
+          matched_dirs << dir
+        when *@detection.groups.map { |g| suffix("-#{g}") }
+          group_packages << [repo_path, dir]
+          matched_dirs << dir
+        end
+      end
+
+      layers = os_packages + distro_packages + distro_profile_packages + group_packages
+      [layers, matched_dirs]
+    end
+
+    def resolve_standalone(repo_path, base_packages, matched_dirs, dirs)
+      dirs
+        .reject { |d| matched_dirs.include?(d) || layer_variant?(d, base_packages) }
+        .sort
+        .map { |d| [repo_path, d] }
+    end
+
+    def top_level_dirs(repo_path)
+      Dir.children(repo_path)
+        .select { |d| File.directory?(File.join(repo_path, d)) }
+        .reject { |d| d.start_with?(".") }
+    end
+
+    # Returns true if dir looks like a layer variant of any base package.
+    # By convention, any <base>-<suffix> directory is a layer variant
+    # for another OS, distro, profile, or group.
+    def layer_variant?(dir, base_packages)
+      base_packages.any? { |pkg| dir.start_with?("#{pkg}-") }
+    end
+
+    def suffix(s)
+      ->(dir) { dir.end_with?(s) }
+    end
+  end
+end

data/lib/dotlayer/stow.rb

@@ -0,0 +1,36 @@
+require "open3"
+
+module Dotlayer
+  class Stow
+    attr_reader :last_error
+
+    def initialize(target: "~", dry_run: false, verbose: false)
+      @target = File.expand_path(target)
+      @dry_run = dry_run
+      @verbose = verbose
+    end
+
+    def dry_run? = @dry_run
+
+    def restow(repo_path, package)
+      args = ["stow", "-R"]
+      args << "-v" if @verbose
+      args << "-d" << repo_path
+      args << "-t" << @target
+      args << package
+
+      if @verbose || @dry_run
+        $stderr.puts "  #{args.join(" ")}"
+      end
+
+      return true if @dry_run
+
+      output, status = Open3.capture2e(*args)
+      @last_error = status.success? ? nil : output.strip
+      status.success?
+    rescue Errno::ENOENT
+      @last_error = "GNU Stow is not installed. Install it with your package manager."
+      false
+    end
+  end
+end

data/lib/dotlayer.rb

@@ -0,0 +1,20 @@
+module Dotlayer
+  VERSION = "0.2.0"
+
+  autoload :CLI, "dotlayer/cli"
+  autoload :Config, "dotlayer/config"
+  autoload :Detection, "dotlayer/detector"
+  autoload :Detector, "dotlayer/detector"
+  autoload :Output, "dotlayer/output"
+  autoload :Repo, "dotlayer/config"
+  autoload :Resolver, "dotlayer/resolver"
+  autoload :Stow, "dotlayer/stow"
+
+  module Commands
+    autoload :Adopt, "dotlayer/commands/adopt"
+    autoload :Doctor, "dotlayer/commands/doctor"
+    autoload :Install, "dotlayer/commands/install"
+    autoload :Status, "dotlayer/commands/status"
+    autoload :Update, "dotlayer/commands/update"
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: dotlayer
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Douglas Andrade
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A convention-driven CLI wrapper around GNU Stow that adds layered package
+  resolution, auto-detection, private repo overlays, and system file management.
+email:
+- douglas@51street.dev
+executables:
+- dotlayer
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/dotlayer
+- lib/dotlayer.rb
+- lib/dotlayer/cli.rb
+- lib/dotlayer/commands/adopt.rb
+- lib/dotlayer/commands/doctor.rb
+- lib/dotlayer/commands/install.rb
+- lib/dotlayer/commands/status.rb
+- lib/dotlayer/commands/update.rb
+- lib/dotlayer/config.rb
+- lib/dotlayer/detector.rb
+- lib/dotlayer/output.rb
+- lib/dotlayer/resolver.rb
+- lib/dotlayer/stow.rb
+homepage: https://github.com/douglas/dotlayer
+licenses:
+- O-SaaSy
+metadata:
+  homepage_uri: https://github.com/douglas/dotlayer
+  source_code_uri: https://github.com/douglas/dotlayer
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Layered dotfiles management with GNU Stow
+test_files: []