robin_cms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4fbf894e92d463a649deb5a35f5e7dbe6053c2d02b582c2a286ebed0c66b22da
+  data.tar.gz: c4e5ee5768732cedc4c0789083df8e03144a4dcd70b7d68c520547dec9d36a08
+SHA512:
+  metadata.gz: ba7ce3b355e910b330279514917ce33de24372c4659dac5706c54a3cfc92d2d1d87436818b098bf8f027eb9ae3fcb64796568f7076eef936878d1251754aaff1
+  data.tar.gz: ddfc74c1b20eae5327a37fac66ae66a1a6d1027b26a77900dad1f44b42eb445b1cf617c250dc0f302d8c531b6101f80d5e74bfb5da2d7ee62f51aee02b7683f3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Aron Lebani
+
+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,183 @@
+# Robin CMS
+
+![Robin CMS logo](./assets/robin-logo.png)
+
+Robin CMS is a minimalist flat-file CMS built with Ruby and Sinatra. It is
+designed to be used by developers for creating custom built websites where the
+client needs to be able to update content themselves. It works with any Static
+Site Generator and can also be embedded in a dynamic Sinatra app. The idea is
+that you can just drop it into your project and it gives you a completely
+customised CMS for your website.
+
+It is completely headless - it gives clients an admin interface where they can
+manage raw content, while giving the developer full control over the HTML and
+CSS. That way clients can't accidentally break layouts and design.
+
+You can define the content model of your website using a YAML file. That way
+you don't have to wrangle all your data into a "blog" post. You can choose to
+store content either as HTML (predominantly for content with rich text), or
+YAML for structured key-value data.
+
+Robin CMS is designed to keep things as simple as possible. It uses files to
+store data so you don't have to worry about managing a database. The entire CMS
+can be installed with just two files - a two line `config.ru` file and a
+`_cms.yml` configuration file.
+
+## Motivation
+
+I know, I know. Another CMS. Whilst there seems to be a plethora of options in
+PHP and JavaScript, there aren't many options for Ruby. Most of them are big
+Rails monoliths, designed either to be a full end-to-end CMS like Wordpress, or
+for the specific use-case of building a blog. I couldn't find a simple
+headless, flat-file CMS built in Ruby that met my needs. So here we are.
+
+## Features
+
+* Headless, flat file CMS
+* Define custom content model using a YAML configuration file
+* Store content as files in HTML or YAML format
+* Works with any Static Site Generator or with a dynamic Sinatra app
+* Simple to install into your website - you just need to add a `config.ru` and
+  a `_cms.yml` file
+* Self-contained - you don't need to ship any assets for the CMS admin site
+
+## Limitations
+
+In order to keep the CMS simple to maintain for your website, certain features
+that are commonly found in CMS software have been omitted.
+
+* Only supports a single user, which means you don't need to maintain a user
+  database.
+* Does not support relations between content models. This is the nature of a
+  flat-file CMS. If you need data model relations, you are probably better off
+  using an SQL database backend rather than a flat-file backend.
+* Doesn't support multiple sites. It is designed to be simple enough that you
+  can drop in a separate instance of the CMS for each website.
+* Does not have a WYSIWYG editor. It is designed purely for managing structured
+  content. You can however add richtext fields to your content models (see
+  example below).
+
+## Installation
+
+Just the usual incantation:
+
+```sh
+gem install robin_cms
+```
+
+## Usage
+
+You have a few options for using this gem in your project. Firstly, you can use
+it directly as a CMS for any Static Site Generator with the following
+`config.ru`:
+
+```ruby
+require 'robin_cms'
+map "/admin" { run RobinCMS::CMS.new }
+```
+
+Now you should be able to run `rackup`, and go to `http://localhost:9292/admin`
+in your browser.
+
+Alternatively, you can embed it into your own Sinatra project like this:
+
+```ruby
+require 'robin_cms'
+require 'sinatra'
+
+use RobinCMS::CMS
+
+get '/' do
+  'Hello, world!'
+end
+
+run Sinatra::Application.new
+```
+
+Yet another option is to use it as a [Jekyll](https://jekyllrb.com/) plugin. To
+do this, you just need to pop `robin_cms` in the `:jekyll_plugins` group of
+your `Gemfile` like so:
+
+```
+gem "jekyll"
+
+group :jekyll_plugins do
+  gem "robin_cms"
+end
+```
+
+After running `bundle exec jekyll serve`, the CMS should be available on your
+website under `/admin`.
+
+## Configuring
+
+You can define your content model in a `_cms.yml` file like this:
+
+```yml
+libraries:
+  - name: "poem"
+    label: "Poem"
+    location: "poems"
+    filetype: "html"
+    fields:
+      - { label: "Title", name; "title", type: "input" }
+      - { label: "Author", name; "author_name", type: "input" }
+      - { label: "Content", name; "content", type: "richtext" }
+  - name: "book"
+    label: "Book"
+    location: "books"
+    filetype: "yml"
+    fields:
+      - { label: "Title", name; "title", type: "input" }
+      - { label: "Author", name; "author_name", type: "input" }
+```
+
+The admin username and password needs to be set in a `.htpasswd` file in the
+root directory of the project. Obviously make sure you `.gitignore` that file.
+Also make sure your static site generator is ignoring it because you don't want
+it in your public directory! Each line of the `.htpasswd` file should follow
+the format `<username>:<password>`, but note that only a single
+username/password is supported for now. The password needs to be encrypted with
+bcrypt. You can do this in Ruby with the `bcrypt` gem:
+
+```sh
+ruby -r bcrypt -e "puts BCrypt::Password.create('mypassword')"
+```
+
+Another thing to note is that if no `.htpasswd` file is found, it will
+automatically create one with username "admin" and password "admin". This lets
+you play around with it locally without configuring a password. So make sure
+you create a `.htpasswd` file before running it in production!
+
+You'll also need to expose a `SESSION_SECRET` environment variable. If you
+don't, it will create one for you, but it creates a new secret each time
+the server starts, meaning you will have to log in again whenever you restart
+the server. It is recommended to create one via Ruby's SecureRandom package.
+
+```sh
+ruby -r securerandom -e "puts SecureRandom.hex(64)"
+```
+
+See the [examples](./examples) folder for a full example. I haven't written any
+documentation yet, but the example `_cms.yml` file is thoroughly commented to
+explain each of the fields.
+
+## Testing
+
+Unit test are written in RSpec. To run them:
+
+```
+rspec
+```
+
+## Roadmap
+
+* [ ] Support markdown content
+* [ ] Support alternative serialization formats (json, csv, tsv)
+* [ ] Filter by any "select" field type
+* [ ] Descriptions at the field level
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).

data/lib/jekyll/commands/serve.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Commands
+    class Serve < Command
+      class << self
+        private
+
+        def start_up_webrick(opts, destination)
+          @reload_reactor.start(opts) if opts["livereload"]
+
+          @server = WEBrick::HTTPServer.new(webrick_opts(opts)).tap { |o| o.unmount("") }
+          @server.mount(opts["baseurl"].to_s, Servlet, destination, file_handler_opts)
+
+          robincms_monkey_patch
+
+          Jekyll.logger.info("Server address:", server_address(@server, opts))
+          launch_browser(@server, opts) if opts["open_url"]
+          boot_or_detach(@server, opts)
+        end
+
+        def robincms_monkey_patch
+          Jekyll::External.require_with_graceful_fail("rackup")
+
+          @server.mount(
+            "/admin",
+            Rackup::Handler::WEBrick,
+            RobinCMS::CMS.new(jekyll_plugin: true)
+          )
+          Jekyll.logger.info("RobinCMS mode:", ENV["RACK_ENV"] || "production")
+        end
+      end
+    end
+  end
+end

data/lib/robin_cms/auth.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RobinCMS
+  module Auth
+    PASSWD_FILE = ".htpasswd"
+
+    def read_credentials
+      if !File.exist?(PASSWD_FILE)
+        username = "admin"
+        password = BCrypt::Password.create("admin")
+        File.write(PASSWD_FILE, "#{username}:#{password}")
+
+        [username, password]
+      else
+        htpasswd = File.readlines(PASSWD_FILE, chomp: true)
+
+        # Only support a single username/password for now
+        htpasswd.first.split(":")
+      end
+    end
+
+    def update_credentials(password)
+      username, _ = read_credentials
+      hash = BCrypt::Password.create(password)
+
+      File.write(PASSWD_FILE, "#{username}:#{hash}")
+    end
+
+    def authenticate!(username_guess, password_guess)
+      username, password = read_credentials
+      password_ok = BCrypt::Password.new(password) == password_guess
+      username_ok = username == username_guess
+
+      unless username_ok && password_ok
+        raise AuthenticationError, "Incorrect username or password"
+      end
+    end
+  end
+end

data/lib/robin_cms/cms.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module RobinCMS
+  class CMS < Sinatra::Base
+    set :logging, true
+    set :sessions, true
+    set :session_secret, ENV.fetch("SESSION_SECRET", SecureRandom.hex(64))
+
+    attr_accessor :config
+
+    def initialize(app = nil, **opts)
+      super(app)
+
+      @config = Configuration.parse(**opts)
+    end
+
+    helpers do
+      include Helpers
+      include Auth
+    end
+
+    before do
+      if %w[/login /logout].include?(request.path_info)
+        pass
+      end
+
+      redirect to("/login") unless session[:auth_user]
+    end
+
+    before(/\/libraries\/(.*).*/) do
+      kind = params[:captures].first.split("/").first
+
+      @library = @config.find_library(kind)
+      @sorted_fields = @config.sorted_fields(kind)
+
+      halt 404 unless @library
+    end
+
+    after do
+      session[:flash] = @flash.next if @flash
+    end
+
+    get "/" do
+      redirect to(home_page)
+    end
+
+    get "/login" do
+      erb :login
+    end
+
+    post "/login" do
+      authenticate!(params[:username], params[:password])
+
+      session[:auth_user] = params[:username]
+      redirect to(home_page)
+    rescue AuthenticationError
+      flash[:error] = "Incorrect username or password"
+      redirect to("/login")
+    end
+
+    get "/logout" do
+      session[:auth_user] = nil
+      redirect to("/login")
+    end
+
+    get "/profile" do
+      @username = session[:auth_user]
+
+      erb :profile
+    end
+
+    get "/change-password" do
+      erb :change_password
+    end
+
+    post "/change-password" do
+      if params[:confirm_password] != params[:new_password]
+        flash[:error] = "Passwords must match"
+        redirect to("/change-password")
+      end
+
+      authenticate!(session[:auth_user], params[:old_password])
+
+      update_credentials(params[:new_password])
+      session[:auth_user] = nil
+      flash[:success] = "Password updated succesfully. Please log in with your new credentials."
+
+      redirect to("/login")
+    rescue AuthenticationError
+      flash[:error] = "Incorrect username or password"
+      redirect to("/change-password")
+    end
+
+    get "/libraries/:kind" do
+      @items = Item.where(@library,
+        sort: params[:sort],
+        published: params[:published],
+        q: params[:q])
+
+      erb :library
+    end
+
+    get "/libraries/:kind/item" do
+      if params[:id]
+        @item = Item.find_one(@library, params[:id])
+        halt 404 unless @item
+      else
+        @item = Item.blank(@library)
+      end
+
+      erb :library_item
+    end
+
+    post "/libraries/:kind/item" do
+      if params[:id]
+        @item = Item.find_one(@library, params[:id])
+        halt 404 unless @item
+
+        if params[:image]
+          filename = params[:image][:filename]
+          tempfile = params[:image][:tempfile]
+
+          StaticItem.delete_if_exists!(@library, @item.attributes[:image_src])
+          StaticItem.create!(@library, filename, tempfile).then do |s|
+            params[:image_src] = "/" + s.filepath
+          end
+        end
+
+        @item.attributes = params
+        @item.update!
+      else
+        if params[:image]
+          filename = params[:image][:filename]
+          tempfile = params[:image][:tempfile]
+
+          StaticItem.create!(@library, filename, tempfile).then do |s|
+            params[:image_src] = "/" + s.filepath
+          end
+        end
+
+        Item.create!(@library, params)
+      end
+
+      redirect to("/libraries/#{params[:kind]}")
+    rescue ItemExistsError
+      flash[:error] = "An item with the same name already exists"
+      redirect to("/libraries/#{params[:kind]}/item")
+    end
+
+    post "/libraries/:kind/item/delete" do
+      if params[:id]
+        @item = Item.find_one(@library, params[:id])
+        halt 404 unless @item
+
+        if @item.attributes[:image_src]
+          StaticItem.delete_if_exists!(@library, @item.attributes[:image_src])
+        end
+
+        @item.delete!
+      else
+        halt 404
+      end
+
+      redirect to("/libraries/#{params[:kind]}")
+    end
+
+    post "/publish" do
+      if system(@config[:build_command])
+        flash[:success_dialog] = "Your site has been successfully published!"
+      else
+        flash[:errors] = "There was an error publishing the site"
+      end
+
+      redirect to(home_page)
+    end
+
+    not_found do
+      # This is a hack for showing previews of images uploaded in libraries.
+      # It is needed because until you publish the site, the image is not
+      # copied to the site output, and therefore requests for the file will
+      # return a 404. Note that if using it as a Jekyll plugin, this is not
+      # needed as the files will be served by Jekyll's dev server.
+
+      # Need to use `PATH_INFO` for the same reason we need to use the `url`
+      # and `to` helpers - we want the request URI relative to the path that
+      # the app is mounted at i.e. the virtual location.
+      uri = env["PATH_INFO"]
+
+      library = @config[:libraries].find do |c|
+        uri.start_with?("/#{c[:static_location]}")
+      end
+
+      if library
+        send_file(File.join(library[:static_location], File.basename(uri)))
+      else
+        pass
+      end
+    end
+  end
+end

data/lib/robin_cms/collection_item.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RobinCMS
+  class CollectionItem
+    include Itemable
+    extend Queryable
+    extend Sluggable
+
+    def self.blank(library)
+      new(nil, library)
+    end
+
+    def self.create!(library, attributes)
+      id = make_slug(attributes[:title], library[:pattern])
+      new(id, library, attributes).tap do |item|
+        item.save!
+      end
+    end
+
+    def self.find_one(library, id)
+      location = library[:location]
+      ext = library[:filetype]
+      path = File.join(location, "#{id}.#{ext}")
+
+      return unless File.exist?(path)
+
+      deserialize(library, path)
+    end
+
+    def self.all(library)
+      location = library[:location]
+      ext = library[:filetype]
+      path = File.join(location, "*.#{ext}")
+
+      Dir.glob(path).filter { |f| File.file?(f) }.map do |path|
+        deserialize(library, path)
+      end
+    end
+
+    def self.deserialize(library, path)
+      raw = File.read(path)
+      id = File.basename(path, File.extname(path))
+
+      _, frontmatter, content = raw.split("---")
+
+      attributes = YAML.load(frontmatter, symbolize_names: true)
+      attributes[:content] = content.strip
+
+      new(id, library, attributes)
+    end
+
+    private_class_method :deserialize
+
+    def filepath
+      location = @library[:location]
+      name = @id
+      ext = @library[:filetype]
+      File.join(location, "#{name}.#{ext}")
+    end
+
+    def save!
+      if File.exist?(filepath)
+        raise ItemExistsError, "An item with the same name already exists"
+      end
+
+      super
+    end
+
+    private
+
+    def serialize
+      # The Psych module (for which YAML is an alias) has a
+      # stringify_names option which does exactly this. However it was
+      # only introduced in Ruby 3.4. Using transform_keys is a workaround
+      # to support earlier versions of Ruby.
+      fm = frontmatter.to_h.transform_keys(&:to_s)
+
+      content = @attributes[:content]
+      YAML.dump(fm, stringify_names: true) << "---\n" << content
+    end
+  end
+end

data/lib/robin_cms/configuration-schema.json

@@ -0,0 +1,116 @@
+{
+	"$schema": "http://json-schema.org/draft-06/schema#",
+	"title": "RobinCMS configuration schema",
+	"type": "object",
+	"required": ["url", "libraries"],
+	"properties": {
+		"title": { "type": "string" },
+		"url": { "type": "string" },
+		"build_command": { "type": "string" },
+		"accent_color": {
+			"type": "string",
+			"pattern": "^\#{1}[a-fA-F0-9]{6}"
+		},
+		"libraries": {
+			"type": "array",
+			"items": {
+				"anyOf": [
+					{ "$ref": "#/$defs/library_schema" },
+					{ "$ref": "#/$defs/data_schema" }
+				]
+			}
+		}
+	},
+	"$defs": {
+		"options_schema": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["label", "value"],
+				"properties": {
+					"label": { "type": "string" },
+					"value": { "type": "string" }
+				}
+			}
+		},
+		"image_dimensions_schema": { "type": "string", "pattern": "^[0-9]+x[0-9]+$" },
+		"image_filetype_schema": { "type": "string", "enum": ["png", "jpg"] },
+		"library_schema": {
+			"type": "object",
+			"required": ["id", "label", "label_singular"],
+			"properties": {
+				"id": { "type": "string" },
+				"type": { "type": "string", "const": "collection" },
+				"filetype": { "type": "string", "enum": ["html"] },
+				"label": { "type": "string" },
+				"label_singular": { "type": "string" },
+				"location": { "type": "string" },
+				"static_location": { "type": "string" },
+				"description": { "type": "string" },
+				"can_create": { "type": "boolean" },
+				"can_delete": { "type": "boolean" },
+				"pattern": { "type": "string" },
+				"fields": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"required": ["id", "label"],
+						"properties": {
+							"id": { "type": "string" },
+							"label": { "type": "string" },
+							"type": {
+								"type": "string",
+								"enum": ["text", "richtext", "date", "hidden", "number", "color", "email", "url", "select", "image"]
+							},
+							"default": { "type": "string" },
+							"required": { "type": "boolean" },
+							"readonly": { "type": "boolean" },
+							"options": { "$ref": "#/$defs/options_schema" },
+							"dimensions": { "$ref": "#/$defs/image_dimensions_schema" },
+							"filetype": { "$ref": "#/$defs/image_filetype_schema" },
+							"order": { "type": "number" }
+						}
+					}
+				}
+			}
+		},
+		"data_schema": {
+			"type": "object",
+			"required": ["id", "label", "label_singular"],
+			"properties": {
+				"id": { "type": "string" },
+				"type": { "type": "string", "const": "data" },
+				"filetype": { "type": "string", "enum": ["yml"] },
+				"label": { "type": "string" },
+				"label_singular": { "type": "string" },
+				"location": { "type": "string" },
+				"static_location": { "type": "string" },
+				"description": { "type": "string" },
+				"can_create": { "type": "boolean" },
+				"can_delete": { "type": "boolean" },
+				"pattern": { "type": "string" },
+				"fields": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"required": ["id", "label"],
+						"properties": {
+							"id": { "type": "string" },
+							"label": { "type": "string" },
+							"type": {
+								"type": "string",
+								"enum": ["text", "date", "hidden", "number", "color", "email", "url", "select", "image"]
+							},
+							"default": { "type": "string" },
+							"required": { "type": "boolean" },
+							"readonly": { "type": "boolean" },
+							"options": { "$ref": "#/$defs/options_schema" },
+							"dimensions": { "$ref": "#/$defs/image_dimensions_schema" },
+							"filetype": { "$ref": "#/$defs/image_filetype_schema" }
+						}
+					}
+				}
+			}
+		}
+	}
+}