add quickstart examples directory and link from README

7 files changed, 134 insertions, 0 deletions

diff --git a/examples/cli/config.rb b/examples/cli/config.rb
new file mode 100755
index 0000000..84fa8f1
--- /dev/null
+++ b/examples/cli/config.rb
@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# Example: Using RCM via the rcm CLI tool.
+#
+# Run with:
+#   rcm config.rb --dry                    # dry run, no changes made
+#   rcm config.rb --debug                  # verbose output
+#   rcm config.rb --hosts earth,mars       # limit to specific hosts
+#   rcm config.rb                          # apply configuration
+#
+# Requires rcm to be installed as a gem, or adjust the path below:
+#   require_relative '../../lib/dsl'
+require 'rcm'
+
+configure do
+  # Only apply the block below when running on host 'earth'.
+  given { hostname is :earth }
+
+  # Write a simple text file with static content.
+  file '/tmp/example/hello.txt' do
+    manage directory
+    'Hello from earth!'
+  end
+
+  # Create a file rendered from an inline ERB template.
+  file '/tmp/example/info.txt' do
+    from template
+    'Host: <%= `hostname`.strip %>, Date: <%= Time.now.strftime("%Y-%m-%d") %>'
+  end
+end
diff --git a/examples/gem/Gemfile b/examples/gem/Gemfile
new file mode 100644
index 0000000..b1f79ad
--- /dev/null
+++ b/examples/gem/Gemfile
@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Point at the local rcm checkout; change to gem 'rcm' once published.
+gem 'rcm', path: '../../'
diff --git a/examples/gem/Rakefile b/examples/gem/Rakefile
new file mode 100644
index 0000000..81a66d4
--- /dev/null
+++ b/examples/gem/Rakefile
@@ -0,0 +1,27 @@
+# Example: Using RCM as a gem inside a Bundler-managed project.
+#
+# Run with:
+#   bundle install
+#   bundle exec rake setup -- --dry      # dry run, no changes made
+#   bundle exec rake setup -- --debug    # verbose output
+#   bundle exec rake setup               # apply configuration
+require 'rcm'
+
+desc 'Apply system configuration'
+task :setup do
+  configure do
+    # Only run on the host named 'earth'
+    given { hostname is :earth }
+
+    # Write a WireGuard config rendered from an inline ERB template.
+    file '/tmp/example/wg0.conf' do
+      from template
+
+      <<~TEMPLATE
+        [Interface]
+        Address = <%= "10.0.0.1/24" %>
+        ListenPort = 51820
+      TEMPLATE
+    end
+  end
+end
diff --git a/examples/plain_ruby/config.rb b/examples/plain_ruby/config.rb
new file mode 100755
index 0000000..f49bd01
--- /dev/null
+++ b/examples/plain_ruby/config.rb
@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# Example: Plain Ruby script — no Rake, no bundler required.
+#
+# Run with:
+#   ruby config.rb --dry      # dry run, no changes made
+#   ruby config.rb --debug    # verbose output
+#   ruby config.rb            # apply configuration
+#
+# Requires rcm to be installed as a gem, or adjust the path below:
+#   require_relative '../../lib/dsl'
+require 'rcm'
+
+configure do
+  # Write a simple text file with static content.
+  file '/tmp/example/hello.txt' do
+    manage directory
+    'Hello, World!'
+  end
+
+  # Ensure a specific line is present in another file (idempotent).
+  file '/tmp/example/hosts.txt' do
+    line '127.0.0.1 localhost'
+  end
+
+  # Create a file from an inline ERB template.
+  file '/tmp/example/greeting.txt' do
+    from template
+    'Generated on <%= Time.now.strftime("%Y-%m-%d") %>'
+  end
+end
diff --git a/examples/rake/Gemfile b/examples/rake/Gemfile
new file mode 100644
index 0000000..b1f79ad
--- /dev/null
+++ b/examples/rake/Gemfile
@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Point at the local rcm checkout; change to gem 'rcm' once published.
+gem 'rcm', path: '../../'
diff --git a/examples/rake/Rakefile b/examples/rake/Rakefile
new file mode 100644
index 0000000..27b7e7a
--- /dev/null
+++ b/examples/rake/Rakefile
@@ -0,0 +1,36 @@
+# Example: Using RCM with Rake (from a project directory).
+#
+# Run with:
+#   rake setup -- --dry      # dry run, no changes made
+#   rake setup -- --debug    # verbose output
+#   rake setup               # apply configuration
+#
+# This example assumes rcm is available via bundler (see Gemfile),
+# or you can swap the require for: require_relative '../../lib/dsl'
+require 'rcm'
+
+desc 'Apply system configuration'
+task :setup do
+  configure do
+    # Only run on host named 'earth'
+    given { hostname is :earth }
+
+    # Create a WireGuard config from an inline ERB template.
+    # The 'manage directory' directive creates /tmp/example/wg/ if it is missing.
+    file '/tmp/example/wg/wg0.conf' do
+      manage directory
+      from template
+
+      <<~TEMPLATE
+        [Interface]
+        Address = <%= "10.0.0.1/24" %>
+        ListenPort = 51820
+      TEMPLATE
+    end
+
+    # Ensure a specific line is present in a hosts file (idempotent).
+    file '/tmp/example/hosts.txt' do
+      line '192.168.1.101 earth.local'
+    end
+  end
+end
diff --git a/examples/rake/config.toml b/examples/rake/config.toml
new file mode 100644
index 0000000..5a21958
--- /dev/null
+++ b/examples/rake/config.toml
@@ -0,0 +1,4 @@
+[hostgroups]
+
+# Define groups of hosts that share configuration
+webservers = ["earth", "mars"]