shill 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c856b97b9e77c751f97f81f2b4ccf1d4bab2d939ad808d86cd86703bbe7616ae
+  data.tar.gz: 2aee215e4a54aed30f179e7da637a3ede554e3a689bc36690f39d7251b1941e0
+SHA512:
+  metadata.gz: 7d7abda12e3b7d075e20cce210951639a814379542537cc922cc216178f39e2f6fbbc55ed6ff2bee8973890758f8ff71965d1c87cb128b70ef3757a561ba37a7
+  data.tar.gz: 4dd8770a375b40f3d2440ca5a51859abbd3447306cf1bc8e9df136cbebc1f38daeca369962510fe6865715a349f21bd37fee15a8463cb03ca1871e85217f7427

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-05-15
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Marc Köhlbrugge
+
+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:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+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,148 @@
+# Shill
+
+A tiny, dependency-free Ruby gem that fetches and exposes a list of projects from a remote JSON endpoint.
+
+* Fetch once, cache in memory.
+* Pick a random project with one call.
+* Zero external dependencies (uses Net::HTTP & JSON from Ruby stdlib).
+* Rails-friendly configuration via `Shill.configure`.
+
+---
+
+## Installation
+
+Add the gem to your project:
+
+```ruby
+gem "shill", github: "marckohlbrugge/shill"   # until published on RubyGems
+gem "shill"                                   # once published
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+### Rails
+
+Create `config/initializers/shill.rb`:
+
+```ruby
+Shill.configure do |config|
+  config.endpoint_url = "https://marc.io/shill.json"
+end
+```
+
+### Plain Ruby
+
+```ruby
+require "shill"
+
+Shill.endpoint_url = "https://marc.io/shill.json"
+```
+
+---
+
+## JSON format
+
+The endpoint must return an **array of objects** with these keys:
+
+* **url** – required
+* **description** – required
+* **name** – required
+* **logo_url** – optional
+
+Example:
+
+```json
+[
+  {
+    "name": "BetaList",
+    "url": "https://betalist.com",
+    "description": "Startup discovery platform"
+  },
+  {
+    "name": "Room AI",
+    "url": "https://roomai.com",
+    "description": "Generate interior design with AI",
+    "logo_url": "https://roomai.com/logo.png"
+  }
+]
+```
+
+---
+
+## Usage
+
+```ruby
+# All projects (memoised)
+projects = Shill.projects
+
+# A single random project (memoised list reused)
+featured = Shill.random_project
+
+puts featured.name        # => "Room AI"
+puts featured.url         # => "https://roomai.com"
+```
+
+Need fresh data? Pass `refresh: true`:
+
+```ruby
+Shill.projects(refresh: true)
+```
+
+---
+
+## Error handling
+
+Every exception is wrapped in `Shill::Error` with a helpful message, e.g.:
+
+* endpoint not configured
+* invalid JSON
+* missing required keys
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/marckohlbrugge/shill.git
+cd shill
+bundle install
+bundle exec rake test    # runs the Minitest suite
+```
+
+---
+
+## Contributing
+
+Pull requests are very welcome. Please include tests for any change.
+
+---
+
+## License
+
+Shill is released under the MIT License. See `LICENSE.txt` for details.
+
+---
+
+## Caching
+
+By default Shill caches the fetched payload in memory. If you're running inside a Rails application (with `Rails.cache` configured), it will automatically use that instead. You can also set your own cache store:
+
+```ruby
+Shill.configure do |c|
+  c.cache_store = MyCustomCache.new   # must respond to fetch(key) { ... } and delete(key)
+end
+```
+
+Force a reload at any time:
+
+```ruby
+Shill.projects(refresh: true)   # bypasses cache and stores fresh data
+```
+
+---

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/shill/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Shill
+  VERSION = "0.1.0"
+end

data/lib/shill.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative "shill/version"
+
+module Shill
+  class Error < StandardError; end
+  # Your code goes here...
+
+  # Simple value-object that stores all configurable options.
+  class Configuration
+    # URL that returns a JSON array of project objects.
+    attr_accessor :endpoint_url
+
+    # Custom cache store (defaults to Rails.cache when available or a lightweight in-memory store).
+    # The store should respond to `fetch(key, **options) { ... }` and `delete(key)`.
+    attr_accessor :cache_store
+  end
+
+  # Simple value object representing a single project.
+  Project = Struct.new(:name, :url, :description, :logo_url, keyword_init: true)
+
+  class << self
+    # Access the global configuration object.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the gem inside an initializer or plain Ruby
+    # Example (Rails):
+    #   Shill.configure do |config|
+    #     config.endpoint_url = "https://example.com/projects.json"
+    #   end
+    def configure
+      yield(configuration) if block_given?
+    end
+
+    # Convenience getter/setter so existing `Shill.endpoint_url =` still works.
+    def endpoint_url
+      configuration.endpoint_url
+    end
+
+    def endpoint_url=(value)
+      configuration.endpoint_url = value
+    end
+
+    # Choose the cache store. Priority:
+    # 1. Explicitly configured via `Shill.configure { |c| c.cache_store = ... }`
+    # 2. Rails.cache if Rails is loaded
+    # 3. A simple in-process memory cache
+    def cache_store
+      configuration.cache_store || default_cache_store
+    end
+
+    def cache_store=(store)
+      configuration.cache_store = store
+    end
+
+    # Return all projects fetched from the configured endpoint.
+    # Results are memoised – pass `refresh: true` to force a new HTTP request.
+    def projects(refresh: false)
+      clear_cache if refresh
+
+      cache_store.fetch("shill_projects") { fetch_projects }
+    end
+
+    # Return a single random project (or nil if none present).
+    def random_project(refresh: false)
+      projects(refresh: refresh).sample
+    end
+
+    # Remove cached payload.
+    def clear_cache
+      if cache_store.respond_to?(:delete)
+        cache_store.delete("shill_projects")
+      end
+    end
+
+    private
+
+    # Fetch and parse the projects JSON from the endpoint.
+    def fetch_projects
+      raise Error, "Shill.endpoint_url must be configured" unless endpoint_url && !endpoint_url.empty?
+
+      require "json"
+      require "uri"
+      require "net/http"
+
+      uri = URI.parse(endpoint_url)
+
+      response_body = Net::HTTP.get(uri)
+
+      begin
+        parsed = JSON.parse(response_body, symbolize_names: true)
+      rescue JSON::ParserError => e
+        raise Error, "Invalid JSON received from #{endpoint_url}: #{e.message}"
+      end
+
+      validate_projects!(parsed)
+      # Return an array of Project objects for nicer dot-notation access.
+      parsed.map { |attrs| Project.new(attrs) }
+    rescue StandardError => e
+      # Re-wrap into Shill::Error to keep API consistent
+      raise Error, e.message unless e.is_a?(Error)
+    end
+
+    # Ensure we have an array of hashes with required keys.
+    def validate_projects!(obj)
+      unless obj.is_a?(Array)
+        raise Error, "Projects JSON must be an array"
+      end
+
+      obj.each_with_index do |proj, idx|
+        unless proj.is_a?(Hash)
+          raise Error, "Project at index #{idx} must be an object"
+        end
+
+        required_keys = %i[name url description]
+
+        missing = required_keys.reject { |k| proj.key?(k) }
+
+        unless missing.empty?
+          raise Error, "Project at index #{idx} is missing keys: #{missing.join(", ")}"
+        end
+      end
+    end
+
+    # Determine the default cache store based on environment.
+    def default_cache_store
+      if defined?(Rails) && Rails.respond_to?(:cache) && Rails.cache
+        Rails.cache
+      else
+        @memory_cache ||= MemoryCache.new
+      end
+    end
+
+    # Minimal in-process cache that exposes `fetch`/`delete` to mimic ActiveSupport::Cache API.
+    class MemoryCache
+      def initialize
+        @data = {}
+      end
+
+      def fetch(key)
+        return @data[key] if @data.key?(key)
+        @data[key] = yield
+      end
+
+      def delete(key)
+        @data.delete(key)
+      end
+    end
+  end
+end

data/sig/shill.rbs

@@ -0,0 +1,4 @@
+module Shill
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: shill
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Marc Köhlbrugge
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-05-15 00:00:00.000000000 Z
+dependencies: []
+description: A tiny dependency-free gem that fetches a remote JSON file containing
+  projects and exposes helper methods to list or randomly select them.
+email:
+- subscriptions@marckohlbrugge.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/shill.rb
+- lib/shill/version.rb
+- sig/shill.rbs
+homepage: https://github.com/example/shill
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/example/shill
+  source_code_uri: https://github.com/example/shill
+  changelog_uri: https://github.com/example/shill/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Fetch and promote your projects via JSON endpoint.
+test_files: []