omagem 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e330b39968b7711d9f1cf9f46232efec3c2f342b207ba65a772c48a5a6cac1d7
-  data.tar.gz: dae10b20eb9dc463ca7be29c358b0f2f858cf12196604f56a67a5bd4638b1d54
+  metadata.gz: 0bc981fccab22219589e1c2c9ecc6cc32ddb00747e5d6de7fa8bfe0d21bb985d
+  data.tar.gz: c2accf94983f574ae949c2fd80edf33bde1c585827e78436dfe16eb8c68b24eb
 SHA512:
-  metadata.gz: 7867469319e28f0f4174bb131f83808865650a561ebf375342a438b8363b201401a66722a20e21494c48878e79e4bfaf569fb3cf6529bca38d43ce7fa9083cf5
-  data.tar.gz: f9ea24917b880e554f016b459201ea7151eb95c4f14fe52e84419a1a508faeeeb654122123030aa6707df209838dccf9242fcf5adf6ab4126d972efe44235606
+  metadata.gz: 89f09a6abf18ae0eb2b9ce38bfbcc1adec5a5e096b9d02d36cef53767bdc3864e68ce94e01e8d61f77171ab984b09bef8f0cd7b41b619ff8965b433b586489df
+  data.tar.gz: e26b908126dba3e76cf832eac257a2ff0a1818da938fd43024fe384899c928e85f5214ccd391b1fca9ba407fd3ec6e1be8352ed3a648a68da9591f152a901169

data/README.md

@@ -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,22 +19,61 @@ 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
@@ -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
@@ -192,6 +245,75 @@ 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
 
 - `OmaGem::CommandFailed` — a command exited non-zero (set `ignore_errors: true` in `OmaGem.run` to raise nothing and keep going).

data/lib/omagem/config.rb

@@ -82,6 +82,7 @@ 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'
@@ -92,6 +93,7 @@ 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/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/omagem/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omagem
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  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.
@@ -23,6 +23,7 @@ files:
 - 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