omagem 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2344de2cc3f80a70f3d4b6a11ebb165bee0889404128750aa48ea8ee405b2b4f
-  data.tar.gz: ccd3fc5c8bd1520787c27fd15936ffc289de0efd9e3451abb73554c11d6cc4c0
+  metadata.gz: 0bc981fccab22219589e1c2c9ecc6cc32ddb00747e5d6de7fa8bfe0d21bb985d
+  data.tar.gz: c2accf94983f574ae949c2fd80edf33bde1c585827e78436dfe16eb8c68b24eb
 SHA512:
-  metadata.gz: e4fff8c4af197d669db31d245cf82309ff5ceccf96073a94d6892d333f9feb10b25efdfff9b26fceb42e55163bb0427b6977b8db8c69bf69058d7a6152c61f9f
-  data.tar.gz: a5a0e991ac167211d827f38d5734a1fde76f3c37a0405749202ab94d788d24b906b3b9a74bb6edecf4feaecfd3b2c9e0cc57d821f7c965a3431561df8ccfd1c3
+  metadata.gz: 89f09a6abf18ae0eb2b9ce38bfbcc1adec5a5e096b9d02d36cef53767bdc3864e68ce94e01e8d61f77171ab984b09bef8f0cd7b41b619ff8965b433b586489df
+  data.tar.gz: e26b908126dba3e76cf832eac257a2ff0a1818da938fd43024fe384899c928e85f5214ccd391b1fca9ba407fd3ec6e1be8352ed3a648a68da9591f152a901169

data/README.md

@@ -1,4 +1,4 @@
-# Omarchy
+# OmaGem
 
 [![CI](https://github.com/azzenabidi/OmaGem/actions/workflows/ci.yml/badge.svg)](https://github.com/azzenabidi/OmaGem/actions/workflows/ci.yml)
 [![Gem Version](https://img.shields.io/gem/v/omagem)](https://rubygems.org/gems/omagem)
@@ -6,8 +6,9 @@
 
 A small Ruby DSL for configuring and managing [Omarchy](https://omarchy.org/)
 Linux systems: themes, backgrounds, packages, services, the shell bar,
-plugins, toggles, snapshots, and system operations. It wraps the single
-`omarchy` CLI, so it stays in sync with the real command surface.
+plugins, toggles, snapshots, git-installed software, and system operations.
+It wraps the single `omarchy` CLI, so it stays in sync with the real command
+surface.
 
 Designed to be used both in scripts and inside a Rails application.
 
@@ -18,30 +19,69 @@ Designed to be used both in scripts and inside a Rails application.
 
 ## Installation
 
+### As a dependency (Bundler)
+
 Add this line to your application's Gemfile:
 
 ```ruby
 gem "omagem"
 ```
 
+Then execute:
+
+```bash
+bundle install
+```
+
 Or install directly from the repository:
 
 ```ruby
 gem "omagem", github: "azzenabidi/OmaGem", branch: "main"
 ```
 
-And then execute:
+### Standalone (scripts and one-off use)
+
+If you just want the DSL in a plain Ruby script or from the terminal:
 
 ```bash
-bundle install
+gem install omagem
+```
+
+Verify the gem is installed and loadable:
+
+```bash
+ruby -e 'require "omagem"; puts OmaGem::VERSION'
+```
+
+## Uninstalling
+
+### Remove from a Bundler project
+
+```bash
+bundle remove omagem
+```
+
+(Or delete the `gem "omagem"` line from your Gemfile and run
+`bundle install`.)
+
+### Uninstall the gem
+
+```bash
+gem uninstall omagem
+```
+
+To remove it from every RubyGems environment on the machine:
+
+```bash
+gem uninstall omagem --all
 ```
 
 ## Usage
 
 ```ruby
-require "omarchy"
+require "omagem"
 
-Omarchy.run do
+OmaGem.run do
   theme "catppuccin"
   background "/home/me/Pictures/forest.png"
 
@@ -62,11 +102,11 @@ Omarchy.run do
 end
 ```
 
-Every method is documented on `Omarchy::Config`. The block is evaluated
+Every method is documented on `OmaGem::Config`. The block is evaluated
 against a fresh `Config`, so you can call any DSL method directly:
 
 ```ruby
-config = Omarchy.run do
+config = OmaGem.run do
   theme "catppuccin"
   add_packages "git"
 end
@@ -161,6 +201,19 @@ bar_visible :toggle
 notification_silencing       # do-not-disturb
 ```
 
+### Git-installed software
+
+```ruby
+valid_git_url? "https://...git" # true when git can clone the URL
+git_themes                      # names of user themes cloned from git
+git_plugins                     # IDs of third-party plugins added from git
+
+update_git_installs             # pull every git theme + plugin (yes: true skips prompts)
+update_git_installs(yes: false) # keep the plugin update confirmation prompt
+```
+
+Everything installed through the DSL from a git URL — `install_theme`, `add_plugin` — is already captured in `config.executed`. The Git methods above track what is currently git-managed and keep it up to date.
+
 ### Misc
 
 ```ruby
@@ -173,12 +226,12 @@ focus_app "org.mozilla.firefox"
 
 ## From a Rails app
 
-Because `Omarchy.run` returns the `Config` (and records every executed
+Because `OmaGem.run` returns the `Config` (and records every executed
 command), you can invoke it from a controller, job, or service and inspect
 the results:
 
 ```ruby
-result = Omarchy.run { theme params[:theme] }
+result = OmaGem.run { theme params[:theme] }
 flash[:notice] = result.current_theme
 ```
 
@@ -187,16 +240,85 @@ flash[:notice] = result.current_theme
 Pass a fake (recording) client to build a config without touching the system:
 
 ```ruby
-config = Omarchy::Config.new(client: Omarchy::Client::Fake.new)
+config = OmaGem::Config.new(client: OmaGem::Client::Fake.new)
 config.theme "catppuccin"
 config.executed # => [["theme", "set", "catppuccin"]]
 ```
 
+## Use cases
+
+### 1. Machine bootstrap / dotfiles as code
+
+Declare the desired state of a fresh Omarchy install in a single script you
+can re-run on any machine:
+
+```ruby
+OmaGem.run do
+  theme "catppuccin"
+  add_packages "docker", "git", "lazygit"
+  add_packages "yay-bin", aur: true
+  install_service "tailscale"
+  default_terminal "kitty"
+  update(yes: true)
+end
+```
+
+### 2. Rails admin panel
+
+Expose theme, package, and service management through a web UI. Because
+`OmaGem.run` returns the `Config`, controllers apply an operation and
+immediately inspect the result:
+
+```ruby
+class ThemesController < ApplicationController
+  def update
+    result = OmaGem.run { theme params[:theme] }
+    render json: { current: result.current_theme }
+  end
+end
+```
+
+### 3. Scheduled automation
+
+Drive background jobs — switches your environment on a schedule or keeps the
+system up to date without touching the terminal:
+
+```ruby
+class NightlightJob < ApplicationJob
+  def perform(on:)
+    OmaGem.run { nightlight(on ? :on : :off) }
+  end
+end
+```
+
+### 4. Dry-run / preview
+
+Preview exactly which commands a config would run, without mutating the
+system, using the recording fake client (see
+[Reusable, non-destructive configuration](#reusable-non-destructive-configuration)):
+
+```ruby
+config = OmaGem::Config.new(client: OmaGem::Client::Fake.new)
+config.theme "tokyo-night"
+config.add_packages "docker"
+config.executed
+# => [["theme", "set", "tokyo-night"], ["pkg", "add", "docker"]]
+```
+
+### 5. Remote management
+
+Ship an apply script to an Omarchy box and run it over SSH:
+
+```bash
+scp apply.rb omarchy-box:
+ssh omarchy-box "ruby apply.rb"
+```
+
 ## Errors
 
-- `Omarchy::CommandFailed` — a command exited non-zero (set `ignore_errors: true` in `Omarchy.run` to raise nothing and keep going).
-- `Omarchy::CommandNotFound` — the `omarchy` binary isn't on `PATH` (`ensure_command!`).
-- `Omarchy::ArgumentError` — an invalid enum value (e.g. an unknown terminal).
+- `OmaGem::CommandFailed` — a command exited non-zero (set `ignore_errors: true` in `OmaGem.run` to raise nothing and keep going).
+- `OmaGem::CommandNotFound` — the `omarchy` binary isn't on `PATH` (`ensure_command!`).
+- `OmaGem::ArgumentError` — an invalid enum value (e.g. an unknown terminal).
 
 ## Development
 
@@ -208,4 +330,4 @@ bundle exec rubocop
 
 ## License
 
-MIT
+MIT

data/lib/{omarchy → omagem}/client.rb

@@ -2,13 +2,13 @@
 
 require 'open3'
 
-module Omarchy
+module OmaGem
   # Wraps the `omarchy` CLI. It shells out to the single `omarchy` binary and
   # exposes the resulting output, whether the command succeeded, and the exit
   # status. Errors raised by the command are captured rather than thrown.
   #
   # The class is designed to be subclassed or stubbed in tests (see
-  # Omarchy::Client::Fake) so the DSL can be exercised without a live system.
+  # OmaGem::Client::Fake) so the DSL can be exercised without a live system.
   class Client
     Result = Struct.new(:success, :stdout, :stderr, :status, keyword_init: true) do
       def success?

data/lib/{omarchy → omagem}/config.rb

@@ -3,7 +3,7 @@
 require_relative 'client'
 require_relative 'errors'
 
-module Omarchy
+module OmaGem
   # The DSL surface. A Config instance exposes all the management methods
   # (theme, package, service, system, ...). The methods are defined in
   # feature modules mixed in below, so the DSL is easy to extend and keep
@@ -14,7 +14,7 @@ module Omarchy
   class Config
     attr_reader :client
 
-    def initialize(client: Omarchy::Client.new, ignore_errors: false)
+    def initialize(client: OmaGem::Client.new, ignore_errors: false)
       @client = client
       @ignore_errors = ignore_errors
       @executed = []
@@ -24,7 +24,7 @@ module Omarchy
     # argument array.
     attr_reader :executed
 
-    # Run an Omarchy command and return the Omarchy::Client::Result.
+    # Run an Omarchy command and return the OmaGem::Client::Result.
     # Records the call and validates the exit status unless ignore_errors.
     def run(*args)
       @executed << args
@@ -67,7 +67,7 @@ module Omarchy
       client.run('theme', 'list').stdout.lines.map(&:strip).reject(&:empty?)
     end
 
-    # Raise Omarchy::ArgumentError unless value is in the allowed list.
+    # Raise OmaGem::ArgumentError unless value is in the allowed list.
     def validate_in!(value, allowed, label)
       return if allowed.include?(value.to_s)
 
@@ -82,16 +82,18 @@ require_relative 'dsl/service'
 require_relative 'dsl/system'
 require_relative 'dsl/bar'
 require_relative 'dsl/plugin'
+require_relative 'dsl/git'
 require_relative 'dsl/toggle'
 require_relative 'dsl/snapshot'
 require_relative 'dsl/misc'
 
-Omarchy::Config.include(Omarchy::DSL::Theme)
-Omarchy::Config.include(Omarchy::DSL::Package)
-Omarchy::Config.include(Omarchy::DSL::Service)
-Omarchy::Config.include(Omarchy::DSL::System)
-Omarchy::Config.include(Omarchy::DSL::Bar)
-Omarchy::Config.include(Omarchy::DSL::Plugin)
-Omarchy::Config.include(Omarchy::DSL::Toggle)
-Omarchy::Config.include(Omarchy::DSL::Snapshot)
-Omarchy::Config.include(Omarchy::DSL::Misc)
+OmaGem::Config.include(OmaGem::DSL::Theme)
+OmaGem::Config.include(OmaGem::DSL::Package)
+OmaGem::Config.include(OmaGem::DSL::Service)
+OmaGem::Config.include(OmaGem::DSL::System)
+OmaGem::Config.include(OmaGem::DSL::Bar)
+OmaGem::Config.include(OmaGem::DSL::Plugin)
+OmaGem::Config.include(OmaGem::DSL::Git)
+OmaGem::Config.include(OmaGem::DSL::Toggle)
+OmaGem::Config.include(OmaGem::DSL::Snapshot)
+OmaGem::Config.include(OmaGem::DSL::Misc)

data/lib/{omarchy → omagem}/dsl/bar.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Omarchy
+module OmaGem
   module DSL
     # The status bar: which bar and widget layout is used, plus widget layout.
     module Bar

data/lib/omagem/dsl/git.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module OmaGem
+  module DSL
+    # Track and update software installed from git: user themes cloned from a
+    # repository and shell plugins added from a git URL.
+    module Git
+      # True when the URL names a repository git can clone.
+      def valid_git_url?(url)
+        client.run('git', 'url', 'check', url).success?
+      end
+
+      # Names of the user-installed themes that came from a git clone.
+      def git_themes
+        paths = client.run('theme', 'extras').stdout.lines.map(&:strip).reject(&:empty?)
+        paths.map { |path| File.basename(path) }
+      end
+
+      # IDs of the installed third-party shell plugins (those added from git).
+      def git_plugins
+        JSON.parse(client.run('plugin', 'list', '--json').stdout)
+            .select { |plugin| plugin['firstParty'] == false }
+            .map { |plugin| plugin['id'] }
+      end
+
+      # Update every theme and plugin installed from git. yes: true (default)
+      # skips the confirmation prompt, as scripts cannot answer it.
+      def update_git_installs(yes: true)
+        run('theme', 'update')
+        args = %w[plugin update]
+        args << '--yes' if yes
+        run(*args)
+      end
+    end
+  end
+end

data/lib/{omarchy → omagem}/dsl/misc.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Omarchy
+module OmaGem
   module DSL
     # Misc: reminders, screen capture, launch app, focus app, default agent.
     module Misc

data/lib/{omarchy → omagem}/dsl/package.rb

@@ -2,7 +2,7 @@
 
 require_relative '../errors'
 
-module Omarchy
+module OmaGem
   module DSL
     # Package management: add / drop Arch and AUR packages, plus queries.
     module Package

data/lib/{omarchy → omagem}/dsl/plugin.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Omarchy
+module OmaGem
   module DSL
     # Shell plugin and bar-widget management.
     module Plugin

data/lib/{omarchy → omagem}/dsl/service.rb

@@ -2,7 +2,7 @@
 
 require_relative '../errors'
 
-module Omarchy
+module OmaGem
   module DSL
     # Install/manage optional software, services, apps, browsers, editors,
     # terminals, development environments, and gaming.

data/lib/{omarchy → omagem}/dsl/snapshot.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Omarchy
+module OmaGem
   module DSL
     # System snapshots via snapper.
     module Snapshot

data/lib/{omarchy → omagem}/dsl/system.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Omarchy
+module OmaGem
   module DSL
     # System-level operations: updates, reboot/shutdown/lock, default apps,
     # font, snapshots, and diagnostics.

data/lib/{omarchy → omagem}/dsl/theme.rb

@@ -2,7 +2,7 @@
 
 require_relative '../errors'
 
-module Omarchy
+module OmaGem
   module DSL
     # Theme management: apply, list, install, remove, refresh, backgrounds.
     module Theme

data/lib/{omarchy → omagem}/dsl/toggle.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Omarchy
+module OmaGem
   module DSL
     # Toggle Omarchy features on/off: nightlight, touchpad, Bluetooth, etc.
     module Toggle

data/lib/{omarchy → omagem}/errors.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-module Omarchy
-  # Base class for all Omarchy::DSL errors.
+module OmaGem
+  # Base class for all OmaGem::DSL errors.
   class Error < StandardError; end
 
   # Raised when the `omarchy` CLI is not available on the system.

data/lib/{omarchy → omagem}/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module Omarchy
-  VERSION = '0.1.0'
+module OmaGem
+  VERSION = '0.2.0'
 end

data/lib/omagem.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'omagem/version'
+require_relative 'omagem/errors'
+require_relative 'omagem/client'
+require_relative 'omagem/config'
+
+# OmaGem is a Ruby DSL for configuring and managing Omarchy Linux systems.
+#
+#   require "omagem"
+#
+#   OmaGem.run do
+#     theme "catppuccin"
+#     add_packages "docker", "git"
+#     install_service "tailscale"
+#     nightlight :on
+#   end
+#
+# The block is evaluated against an OmaGem::Config, which exposes every
+# DSL method. See OmaGem::Config for the full list.
+module OmaGem
+  class << self
+    # Execute a DSL block against a fresh OmaGem::Config. Returns the config
+    # so the caller can inspect what ran via config.executed / config.client.
+    #
+    #   config = OmaGem.run { theme "catppuccin" }
+    def run(client: OmaGem::Client.new, ignore_errors: false, &block)
+      config = Config.new(client: client, ignore_errors: ignore_errors)
+      config.instance_eval(&block) if block
+      config
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omagem
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - azzen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies: []
 description: A tiny Ruby DSL that wraps the `omarchy` CLI so you can manage themes,
   packages, services, the shell bar, and more from Ruby or a Rails application.
@@ -19,20 +19,21 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- lib/omarchy.rb
-- lib/omarchy/client.rb
-- lib/omarchy/config.rb
-- lib/omarchy/dsl/bar.rb
-- lib/omarchy/dsl/misc.rb
-- lib/omarchy/dsl/package.rb
-- lib/omarchy/dsl/plugin.rb
-- lib/omarchy/dsl/service.rb
-- lib/omarchy/dsl/snapshot.rb
-- lib/omarchy/dsl/system.rb
-- lib/omarchy/dsl/theme.rb
-- lib/omarchy/dsl/toggle.rb
-- lib/omarchy/errors.rb
-- lib/omarchy/version.rb
+- lib/omagem.rb
+- lib/omagem/client.rb
+- lib/omagem/config.rb
+- lib/omagem/dsl/bar.rb
+- lib/omagem/dsl/git.rb
+- lib/omagem/dsl/misc.rb
+- lib/omagem/dsl/package.rb
+- lib/omagem/dsl/plugin.rb
+- lib/omagem/dsl/service.rb
+- lib/omagem/dsl/snapshot.rb
+- lib/omagem/dsl/system.rb
+- lib/omagem/dsl/theme.rb
+- lib/omagem/dsl/toggle.rb
+- lib/omagem/errors.rb
+- lib/omagem/version.rb
 homepage: https://github.com/azzenabidi/OmaGem
 licenses:
 - MIT

data/lib/omarchy.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'omarchy/version'
-require_relative 'omarchy/errors'
-require_relative 'omarchy/client'
-require_relative 'omarchy/config'
-
-# Omarchy is a Ruby DSL for configuring and managing Omarchy Linux systems.
-#
-#   require "omarchy"
-#
-#   Omarchy.run do
-#     theme "catppuccin"
-#     add_packages "docker", "git"
-#     install_service "tailscale"
-#     nightlight :on
-#   end
-#
-# The block is evaluated against an Omarchy::Config, which exposes every
-# DSL method. See Omarchy::Config for the full list.
-module Omarchy
-  class << self
-    # Execute a DSL block against a fresh Omarchy::Config. Returns the config
-    # so the caller can inspect what ran via config.executed / config.client.
-    #
-    #   config = Omarchy.run { theme "catppuccin" }
-    def run(client: Omarchy::Client.new, ignore_errors: false, &block)
-      config = Config.new(client: client, ignore_errors: ignore_errors)
-      config.instance_eval(&block) if block
-      config
-    end
-  end
-end