staticky 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41fa452e7c74ade67ffd58486af13cb4b121eda6cd51ffd5dc25105981cea0c2
-  data.tar.gz: c8c2a3a15bc2cf0225d7763a825e8c1a34af2a0762777091e0c6c581723d485f
+  metadata.gz: 015d7c615ec3f67937c4c6a7c26d4818f394386f8a3bc6b2b10bb834f1759fb8
+  data.tar.gz: 6e2a25655085984a6e37ace773f55a8ccfd8ffc702de127f1ec8748df391db13
 SHA512:
-  metadata.gz: ff6e8e759028df62d4ce1a9304c2b8caa7fd38c5684e9a653445d14a46ffd4b880fd3c05bb393890d055262db28d37384c47af02ff72c1ce37dafaed33842d33
-  data.tar.gz: 3aa63ca27344d93d99a92463e85f4cd75a547360da6682f6727cbd022b258c540df7dd39b4631f15f08f8f19bcb08bc21aedfe07736aab3267092d4d1db5ec9d
+  metadata.gz: ed18ccdf8f86c13249e5fbc17971ac0b5155a3d15c3760e9308c941892c9f7f488363e5d8a858ad26c67345eb7477ca7c4f2955b35d2b3fc227b5f96f1e16c15
+  data.tar.gz: '09147233cded8c538c9b2e2f86c917c94b1c8c9afc5b028cebc482c364c8586fd4efeee2157bb29cccdb7cfdcca7dda8beb6ef027aea7507b94bdf069ee1ab9b'

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
-## [0.1.0] - 2024-07-08
+## [0.2.0] - 2024-09-24
+
+- Adds plugin system akin to Roda and Sequel for `Resource` and `Router`
+- Improves initial setup
+- Adds better documentation
+- Switches from `rerun` to `filewatcher` for triggering rebuilds
+- Switches from `rackup` to `puma` for development server
+- Updates default package manager to yarn stable
+
+## [0.1.1] - 2024-08-18
+
+- Fixes nginx and Dockerfile configs for default dokku deployments
+- Improvements to site template files
+- Adds ability for `link_to` helpers to take absolute paths
+
+## [0.1.0] - 2024-08-18
 
 - Initial release

data/README.md

@@ -36,14 +36,151 @@ staticky new my_blog --url "https://example.com"
 This will generate a new site at `./my_blog`, install your dependencies and run
 `rspec` just to make sure everything got set up correctly.
 
+You can append `--help` to any commands to see info:
+
+```
+staticky new --help
+```
+
+Which outputs:
+
+```
+Command:
+  staticky new
+
+Usage:
+  staticky new PATH
+
+Description:
+  Create new site
+
+Arguments:
+  PATH                              # REQUIRED Relative path where the site will be generated
+
+Options:
+  --url=VALUE, -u VALUE             # Site URL, default: "https://example.com"
+  --title=VALUE, -t VALUE           # Site title, default: "Example"
+  --description=VALUE, -d VALUE     # Site description, default: "Example site"
+  --twitter=VALUE, -t VALUE         # Twitter handle, default: ""
+  --help, -h                        # Print this help
+```
+
+### Plugins
+
+The router and resources use the plugin
+[pattern](https://janko.io/the-plugin-system-of-sequel-and-roda/)
+found in [Sequel](https://github.com/jeremyevans/sequel) and
+[Roda](https://github.com/jeremyevans/roda).
+
+This means you can easily extend each of them with plugins to fit the specific
+content of your site.
+
+```ruby
+module MyResourcePlugin
+  module InstanceMethods
+    def component=(component)
+      @component = component
+    end
+
+    def component
+      return @component if defined?(@component)
+
+      raise ArgumentError, "component is required"
+    end
+  end
+end
+```
+
+In our own classes we can now reference our new plugin:
+
+```ruby
+class SomeResource < Staticky::Resource
+  plugin MyResourcePlugin
+end
+```
+
+Or, if we register the plugin with `register_plugin` we can just use our
+shorter symbol:
+
+```ruby
+Staticky::Resources::Plugins.register_plugin(:something, MyResourcePlugin)
+
+class SomeResource < Staticky::Resource
+  plugin :something
+end
+```
+
+This system lets you define your own specific resources by subclassing and
+extending with your own plugins.
+
+Here is an example of hooking into the output of the component
+(a string of HTML):
+
+```ruby
+module MinifyHTML
+  module InstanceMethods
+    # Calling super works because the base class has no methods, everything is
+    # a plugin including the core behavior of a resource.
+    def build
+      SomehowMinifyTheHTML.call(super)
+    end
+  end
+end
+
+Staticky::Resources::Plugins.register_plugin(:minify_html, MinifyHTML)
+
+class ApplicationResource < Staticky::Resource
+  plugin :minify_html
+end
+```
+
+Now when an `ApplicationResource` gets rendered, its final output (a string of
+HTML) will be minified.
+
+Each plugin can define modules for:
+
+|Name|Description|
+|----|-----------|
+|InstanceMethods|Get added as instance methods of the Resource|
+|ClassMethods|Get added as the class methods of the Resource|
+
+In addition you have methods you can define that let you hook into the resource
+that adds your plugins:
+
+|Name|Description|
+|----|-----------|
+|load_dependencies(plugin, ...)|Hook to load any other plugins required by this one|
+|configure(plugin, ...)|Hook for additional setup required on the class|
+
+
+### Routing
+
+Your router is a plugin system that by default only has one plugin:
+
+```ruby
+plugin :prelude
+```
+
+This gives you the `match` and `root` methods in your router. You can override
+or extend these methods yourself by redefining them (and optionally calling
+`super`) inside your own plugin or class that inherits from the router.
+
 Once your site is generated you can use the router to define how your content
 maps to routes in `config/routes.rb`:
 
 ```ruby
 Staticky.router.define do
   root to: Pages::Home
+
+  # We can pass in a phlex class
   match "404", to: Errors::NotFound
-  match "500", to: Errors::ServiceError
+  # Or an instance
+  match "500", to: Errors::ServiceError.new
+
+  # We can specify the resource type
+  match "about",
+    to: Markdown.new("content/posts/about.md"),
+    as: Resources::Markdown
 
   # Write your own logic to parse your data into components
   Site.posts.each_value do |model|
@@ -56,13 +193,139 @@ Each route takes a Phlex component (or any object that outputs a string from
 `#call`). We can either pass the class for a default initialization (we just
 call `.new`) or initialize it ourselves.
 
+The resource will be initialized with a `component` and a `url`. It is used as
+the view context for your phlex components.
+
+#### Match
+
+This works in a similar way to your Rails routes. Match takes a path and
+a component (either a class or an instance) that it will route to.
+
+```ruby
+match "404", to: Errors::NotFound, as: Resource
+```
+
+#### Root
+
+Using `match` you can define a root path like:
+
+```ruby
+match "/", to: Pages::Home
+```
+
+For convenience you can shorten this using `root`:
+
+```ruby
+root to: Pages::Home
+```
+
+### Resources
+
+They initialize the same way `ActiveModel` objects do. That is they take their
+keywords and call the setter according to the keys:
+
+```ruby
+def new(**env)
+  super().tap do |resource|
+    env.each do |key, value|
+      resource.send(:"#{key}=", value)
+    end
+  end
+end
+```
+
+The base resource has two core plugins it includes by default:
+
+```ruby
+plugin :prelude
+plugin :phlex
+```
+
+Routes define your resources, which in the end are just data objects that
+contain all the information required to produce the static file that eventually
+outputs to your `Staticky.build_path`.
+
+Lets say we had a router defined like:
+
+```ruby
+Staticky.router.define do
+  match "foo", to: Component
+  match "bar", to: Component
+end
+```
+
+Then we could view our resources:
+
+```
+(ruby) Staticky.resources
+[#<Staticky::Resource:0x0000711525d82c18
+  @component=#<Component:0x0000711525d74848>,
+  @destination=#<Pathname:/your-site-folder/build>,
+  @uri=#<URI::Generic /foo>,
+  @url="foo">,
+ #<Staticky::Resource:0x0000711525d82a88
+  @component=#<Component:0x0000711525d74208>,
+  @destination=#<Pathname:/your-site-folder/build>,
+  @uri=#<URI::Generic /bar>,
+  @url="bar">]
+```
+
+The `prelude` plugin provides the following methods:
+
+|Method|Description|
+|------|-----------|
+|`filepath`|`Pathname` of where the component's output will be written to|
+|`read`|Read the output of the resource from the file system|
+|`basename`|The file basename (e.g. `index.html`) for the resource|
+|`root?`|Whether or not the resource is the root path|
+
+While the `phlex` plugin provides:
+
+|Method|Description|
+|------|-----------|
+|`build`|Call the component and output its result as a string|
+
+These resources are used by your site builder to output the files that end up in
+the `Staticky.build_path`.
+
+Each resource needs to have a `#build` method that creates a file in your build
+folder.
+
+The `phlex` plugin will call your components with a `ViewContext` just like
+`ActionView` in Rails. But this context is tailored towards your static site.
+
+This view context is a `SimpleDelegator` to your resource with a few extra
+methods:
+
+|Method|Description|
+|------|-----------|
+|`root?`|Whether or not this resource is for the root page|
+|`current_path`|The path of the current resource being rendered|
+
+These are useful for creating pages that hide or show content depending on which
+path of the site we are building.
+
+### Linking to your routes
+
+First you need to include the view helpers somewhere in your component
+hierarchy:
+
+```ruby
+class Component < Phlex::HTML
+  include Staticky::Phlex::ViewHelpers
+end
+```
+
+This will add `link_to` to all your components which uses the router to resolve
+any URLs via their path.
+
 Here is an example of what the `Posts::Show` component might look like. We are
 using a [protos](https://github.com/inhouse-work/protos) component, but you can
 use plain old Phlex components if you like.
 
 ```ruby
 module Posts
-  class Show < Protos::Component
+  class Show < Component
     param :post, reader: false
 
     def around_template(&)
@@ -70,6 +333,13 @@ module Posts
     end
 
     def view_template
+      # Links can be resolved to component classes if they are unique:
+      link_to "Home", Pages::Home
+      # They can also resolve via their url:
+      link_to "Posts", "/posts"
+      # Absolute links are resolved as is:
+      link_to "Email", "mailto:email@example.com"
+
       render Posts::Header.new(@post)
       render Posts::Outline.new(@post, class: css[:outline])
       render Posts::Markdown.new(@post, class: css[:post])
@@ -80,25 +350,37 @@ module Posts
 
     def theme
       {
-        layout: "mr-0 lg:mr-[--sidebar-width] md:ml-[--sidebar-width]",
-        outline: %w[
-          my-md
-          md:fixed
-          md:left-0
-          md:top-[--navbar-height]
-          md:pl-[--viewport-padding]
-          md:w-[--sidebar-width]
-        ],
-        post: "prose mx-auto pb-lg"
+        layout: "bg-background",
+        outline: "border",
+        post: "max-w-prose mx-auto"
       }
     end
   end
 end
 ```
 
+The advantage of using `link_to` over plain old `a` tags is that changes to your
+routes will raise errors on invalidated links instead of silently
+linking to invalid pages.
+
+If your component is unique then you can link directly to them (if its not
+unique then it will link to the last defined `match`):
+
+```ruby
+link_to("Some link", Pages::Home)
+```
+
+Otherwise you can link to the path itself:
+
+```ruby
+link_to("Some link", "/")
+```
+
+### Building your site
+
 When you are developing your site you run `bin/dev` to start your development
-server on http://localhost:9292. This will automatically reload after a short
-period when you make changes.
+server on [http://localhost:9292](http://localhost:9292).
+This will automatically reload after a short period when you make changes.
 
 Assets are handled by Vite by default, but you can have whatever build process
 you like just by tweaking `Procfile.dev` and your `Rakefile`. You will also need
@@ -127,6 +409,14 @@ end
 
 This will output your site to `./build` by default.
 
+During building, each definition in the router is compiled and handed a special
+view context which holds information about the resource being rendered such as
+the `current_path`.
+
+These are available in your Phlex components under `helpers` (if you are using
+the site template). This matches what you might expect when using Phlex in
+Rails with `phlex-rails`.
+
 ## Configuration
 
 We can override the configuration according to the settings defined on the main
@@ -142,6 +432,76 @@ Staticky.configure do |config|
 end
 ```
 
+### Environment
+
+You can define the environment of Staticky through its config.
+
+```ruby
+Staticky.configure do |config|
+  config.env = :test
+end
+```
+
+This lets you write environment specific code:
+
+```ruby
+if Staticky.env.test?
+  # Do something test specific
+end
+```
+
+## Testing
+
+We can setup a separate testing environment by putting the following
+into your `spec/spec_helper.rb`:
+
+```ruby
+Staticky.configure do |config|
+  config.root_path = Pathname.new(__dir__).join("fixtures")
+  config.build_path = Pathname.new(__dir__).join("fixtures/build")
+  config.env = :test
+end
+```
+
+This sets up our build path to something different than our development builds.
+
+Staticky uses `Dry::System` to manage its dependencies which means you can stub
+them out if you want:
+
+```ruby
+require "dry/system/stubs"
+
+Staticky.application.enable_stubs!
+
+RSpec.configure do |config|
+  config.before do
+    Staticky.application.stub(:files, Staticky::Filesystem.test)
+  end
+end
+```
+
+This lets you test your builds using `dry-files` (actually `staticky-files`, but
+the interface is the same with additional capabilities for file folders).
+
+The advantage of this is that we can perform our builds on a temporary in memory
+file system rather than actually writing to our disk.
+
+The plugins themselves can also be stubbed:
+
+```ruby
+require "dry/system/stubs"
+
+Staticky::Resources::Plugins.enable_stubs!
+Staticky::Routing::Plugins.enable_stubs!
+
+RSpec.configure do |config|
+  config.before do
+    Staticky::Resources::Plugins.stub(:prelude, MyOwnResourcePlugin)
+    Staticky::Routing::Plugins.stub(:prelude, MyOwnRoutingPlugin)
+  end
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/lib/staticky/application.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Staticky
+  class Application < Dry::System::Container
+    # This class coordinates the booting process to add our dependencies.
+    # We use zeitwerk to autoload our constants in the lib/staticky folder.
+    #
+    # Monitoring is enabled to hook into calls to certain dependencies.
+    #
+    # ```ruby
+    # Staticky.application.monitor(:builder, methods: %i[call]) do |event|
+    #   Staticky.logger.info "Built site in #{event[:time]}ms"
+    # end
+    # ```
+
+    use :zeitwerk
+    use :monitoring
+
+    configure do |config|
+      config.root = Pathname(__dir__).join("..").join("..")
+      config.inflector = Dry::Inflector.new do |inflections|
+        inflections.acronym("CLI")
+      end
+      config.component_dirs.add "lib" do |dir|
+        dir.add_to_load_path = false
+        dir.auto_register = false
+        dir.namespaces.add "staticky", key: nil
+      end
+    end
+
+    register(:files, memoize: true) { Staticky::Filesystem.real }
+    register(:router, memoize: true) { Staticky::Router.new }
+    register(:builder, memoize: true) { Staticky::Builder.new }
+    register(:generator) { Staticky::Generator.new }
+  end
+end

data/lib/staticky/builder.rb

@@ -28,7 +28,7 @@ module Staticky
         .resources
         .each do |resource|
           publish("before_resource", resource:)
-          compile output_path(resource.filepath), resource.build
+          compile resource.filepath, resource.build
           publish("after_resource", resource:)
         end
     end

data/lib/staticky/cli/commands/build.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Staticky
+  module CLI
+    module Commands
+      class Build < Dry::CLI::Command
+        desc "Build site"
+
+        def call(*) = Staticky.builder.call
+      end
+    end
+  end
+end

data/lib/staticky/cli/commands/generate.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Staticky
+  module CLI
+    module Commands
+      class Generate < Dry::CLI::Command
+        desc "Create new site"
+
+        argument :path,
+                 required: true,
+                 desc: "Relative path where the site will be generated"
+
+        option :url,
+               default: "https://example.com",
+               desc: "Site URL",
+               aliases: ["-u"]
+        option :title,
+               default: "Example",
+               desc: "Site title",
+               aliases: ["-t"]
+        option :description,
+               default: "Example site",
+               desc: "Site description",
+               aliases: ["-d"]
+        option :twitter,
+               default: "",
+               desc: "Twitter handle",
+               aliases: ["-t"]
+
+        def call(path:, **)
+          path = Pathname.new(path).expand_path
+
+          Staticky.generator.call(path, **)
+
+          Dir.chdir(path) do
+            system("cd #{path}")
+            system("chmod +x bin/*")
+            bundle_command("install")
+            bundle_command("exec bin/setup")
+          end
+        end
+
+        def bundle_command(command, env = {})
+          puts "bundle #{command}"
+
+          # We are going to shell out rather than invoking Bundler::CLI.new(command)
+          # because `rails new` loads the Thor gem and on the other hand bundler uses
+          # its own vendored Thor, which could be a different version. Running both
+          # things in the same process is a recipe for a night with paracetamol.
+          #
+          # Thanks to James Tucker for the Gem tricks involved in this call.
+          _bundle_command = Gem.bin_path("bundler", "bundle")
+
+          require "bundler"
+          Bundler.with_original_env do
+            exec_bundle_command(_bundle_command, command, env)
+          end
+        end
+
+        def exec_bundle_command(bundle_command, command, env)
+          full_command = %("#{Gem.ruby}" "#{bundle_command}" #{command})
+          system(env, full_command)
+        end
+      end
+    end
+  end
+end

data/lib/staticky/cli/commands/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Staticky
+  module CLI
+    module Commands
+      class Version < Dry::CLI::Command
+        desc "Print version"
+
+        def call(*) = puts VERSION
+      end
+    end
+  end
+end

data/lib/staticky/cli/commands.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Staticky
+  module CLI
+    module Commands
+      extend Dry::CLI::Registry
+
+      register "version", Version
+      register "build", Build
+      register "new", Generate
+    end
+  end
+end

data/lib/staticky/cli.rb

@@ -4,66 +4,6 @@ require "dry/cli"
 
 module Staticky
   module CLI
-    module Commands
-      extend Dry::CLI::Registry
-
-      class Version < Dry::CLI::Command
-        desc "Print version"
-
-        def call(*) = puts VERSION
-      end
-
-      class Build < Dry::CLI::Command
-        desc "Build site"
-
-        def call(*) = Staticky.builder.call
-      end
-
-      class Generate < Dry::CLI::Command
-        desc "Create new site"
-
-        argument :path,
-                 required: true,
-                 desc: "Relative path where the site will be generated"
-
-        option :url,
-               default: "https://example.com",
-               desc: "Site URL",
-               aliases: ["-u"]
-        option :title,
-               default: "Example",
-               desc: "Site title",
-               aliases: ["-t"]
-        option :description,
-               default: "Example site",
-               desc: "Site description",
-               aliases: ["-d"]
-        option :twitter,
-               default: "",
-               desc: "Twitter handle",
-               aliases: ["-t"]
-
-        def call(path:, **)
-          path = Pathname.new(path).expand_path
-
-          Staticky.generator.call(path, **)
-
-          commands = [
-            "bundle install",
-            "bundle binstubs bundler rake rspec-core vite_ruby",
-            "yarn install",
-            "bin/rspec"
-          ].join(" && ")
-
-          system(commands, chdir: path) || abort("install failed")
-        end
-      end
-
-      register "version", Version
-      register "build", Build
-      register "new", Generate
-    end
-
     def self.new(...)
       Dry::CLI.new(Commands)
     end