develoz-rails 0.1.0

data/lib/generators/develoz/docker/templates/docker-compose.yml.tt

@@ -0,0 +1,59 @@
+services:
+  postgres:
+    image: postgres:18
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-postgres}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
+      POSTGRES_DB: ${POSTGRES_DB:-<%= app_name %>_development}
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  selenium:
+    image: selenium/standalone-chromium:latest
+    ports:
+      - "4444:4444"
+      - "7900:7900"
+    volumes:
+      - /dev/shm:/dev/shm
+
+  mailcatcher:
+    image: schickling/mailcatcher:latest
+    ports:
+      - "1080:1080"
+      - "1025:1025"
+
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    depends_on:
+      postgres:
+        condition: service_healthy
+      selenium:
+        condition: service_started
+      mailcatcher:
+        condition: service_started
+    environment:
+      DATABASE_HOST: ${DATABASE_HOST:-postgres}
+      DATABASE_PORT: ${DATABASE_PORT:-5432}
+      DATABASE_USER: ${DATABASE_USER:-postgres}
+      DATABASE_PASSWORD: ${DATABASE_PASSWORD:-postgres}
+      SELENIUM_URL: ${SELENIUM_URL:-http://selenium:4444/wd/hub}
+      MAILCATCHER_URL: ${MAILCATCHER_URL:-http://mailcatcher:1080}
+    ports:
+      - "3000:3000"
+    volumes:
+      - .:/rails
+      - bundle_cache:/usr/local/bundle
+    command: bin/docker-entrypoint
+
+volumes:
+  postgres_data:
+  bundle_cache:

data/lib/generators/develoz/docker/templates/dockerfile_dev.tt

@@ -0,0 +1,24 @@
+FROM ruby:<%= RUBY_VERSION %>
+
+RUN apt-get update -qq && apt-get install -y \
+  build-essential \
+  libpq-dev \
+  libvips \
+  nodejs \
+  npm \
+  git \
+  curl \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /rails
+
+RUN gem install bundler
+
+COPY Gemfile Gemfile.lock ./
+RUN bundle install
+
+COPY . .
+
+EXPOSE 3000
+
+CMD ["bin/docker-entrypoint"]

data/lib/generators/develoz/docs_render/docs_render_generator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "develoz"
+
+module Develoz
+  module Generators
+    class DocsRenderGenerator < Develoz::Generators::Base
+      def self.source_root
+        File.expand_path("templates", __dir__)
+      end
+
+      def add_docs_gems
+        add_gem "redcarpet"
+        add_gem "rouge"
+      end
+
+      def create_docs_controller
+        template "app/controllers/docs_controller.rb.tt", "app/controllers/docs_controller.rb"
+      end
+
+      def create_document_model
+        template "app/models/document.rb.tt", "app/models/document.rb"
+      end
+
+      def create_docs_views
+        template "app/views/docs/show.html.erb.tt", "app/views/docs/show.html.erb"
+      end
+
+      def create_docs_javascript
+        template "app/javascript/docs.js.tt", "app/javascript/docs.js"
+      end
+
+      def create_docs_stylesheet
+        template "app/assets/stylesheets/documentation.scss.tt", "app/assets/stylesheets/documentation.scss"
+      end
+
+      def create_redcarpet_rouge_initializer
+        template "config/initializers/redcarpet_rouge.rb.tt", "config/initializers/redcarpet_rouge.rb"
+      end
+
+      def insert_docs_route
+        insert_route 'get "docs(/*id)" => "docs#show"'
+      end
+    end
+  end
+end

data/lib/generators/develoz/docs_render/templates/app/assets/stylesheets/documentation.scss.tt

@@ -0,0 +1,145 @@
+section.documentation {
+  table {
+    margin-bottom: 20px;
+
+    th,
+    td {
+      border: 1px solid #dee2e6;
+      padding: 5px;
+    }
+  }
+
+  .box-body {
+    padding: 10px 30px;
+    max-width: 1200px;
+
+    h1,
+    h2,
+    h3,
+    h4 {
+      margin-top: 40px;
+    }
+
+    pre.code-block {
+      margin-bottom: 20px;
+      padding: 16px 20px;
+      overflow-x: auto;
+      font-size: 0.875rem;
+      line-height: 1.5;
+      color: #c9d1d9;
+      background-color: #161b22;
+      border: 1px solid #30363d;
+      border-radius: 8px;
+
+      code {
+        padding: 0;
+        color: inherit;
+        white-space: pre;
+        background-color: transparent;
+        border: 0;
+      }
+    }
+
+    :not(pre) > code {
+      padding: 0.2em 0.4em;
+      font-size: 0.875em;
+      color: #24292f;
+      background-color: rgb(175 184 193 / 20%);
+      border-radius: 6px;
+
+      .dark & {
+        color: #c9d1d9;
+      }
+    }
+
+    pre.mermaid {
+      margin-bottom: 20px;
+      padding: 0;
+      text-align: center;
+      background: transparent;
+      border: 0;
+
+      &:not([data-processed="true"]) {
+        visibility: hidden;
+      }
+    }
+
+    blockquote {
+      margin: 20px 0;
+      padding: 12px 16px;
+      color: #495057;
+      background: #f8f9fa;
+      border-left: 4px solid #0d6efd;
+      border-radius: 0 6px 6px 0;
+
+      p:last-child {
+        margin-bottom: 0;
+      }
+
+      &.callout {
+        --callout-accent: #57606a;
+        --callout-background: #f6f8fa;
+        --callout-foreground: #24292f;
+
+        color: var(--callout-foreground);
+        background: var(--callout-background);
+        border-left-color: var(--callout-accent);
+
+        .dark & {
+          --callout-background: #161b22;
+          --callout-foreground: #c9d1d9;
+        }
+      }
+
+      &.callout-note {
+        --callout-accent: #0969da;
+
+        .dark & {
+          --callout-accent: #58a6ff;
+        }
+      }
+
+      &.callout-tip {
+        --callout-accent: #1a7f37;
+
+        .dark & {
+          --callout-accent: #3fb950;
+        }
+      }
+
+      &.callout-important {
+        --callout-accent: #8250df;
+
+        .dark & {
+          --callout-accent: #a371f7;
+        }
+      }
+
+      &.callout-warning {
+        --callout-accent: #9a6700;
+
+        .dark & {
+          --callout-accent: #d29922;
+        }
+      }
+
+      &.callout-caution {
+        --callout-accent: #cf222e;
+
+        .dark & {
+          --callout-accent: #f85149;
+        }
+      }
+
+      .callout-title {
+        margin-bottom: 8px;
+        font-weight: 600;
+        color: var(--callout-accent);
+
+        .fa {
+          margin-right: 6px;
+        }
+      }
+    }
+  }
+}

data/lib/generators/develoz/docs_render/templates/app/controllers/docs_controller.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class DocsController < ApplicationController
+  def show
+    @document = Document.find(params[:id] || "README")
+  end
+end

data/lib/generators/develoz/docs_render/templates/app/javascript/docs.js.tt

@@ -0,0 +1,15 @@
+import mermaid from 'mermaid'
+
+mermaid.initialize({
+  startOnLoad: false,
+  securityLevel: 'strict',
+  theme: window.darkMode ? 'dark' : 'default',
+})
+
+const renderDiagrams = () => {
+  const nodes = document.querySelectorAll('pre.mermaid:not([data-processed="true"])')
+  if (nodes.length) mermaid.run({ nodes })
+}
+
+document.addEventListener('turbo:load', renderDiagrams)
+if (document.readyState === 'complete') renderDiagrams()

data/lib/generators/develoz/docs_render/templates/app/models/document.rb.tt

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+class Document
+  include ActiveModel::Model
+
+  class RecordNotFound < StandardError; end
+
+  FOLDER_INDEX_NAMES = [ "README", "00 - Index" ].freeze
+
+  class Renderer < Redcarpet::Render::HTML
+    include ActionView::Helpers::TagHelper
+    include ActionView::Helpers::SanitizeHelper
+
+    # Obsidian wikilink: [[Note]], [[Note#Heading]], [[Note|Alias]] (and combinations).
+    WIKILINK = /\[\[([^\]#|]+)(?:#([^\]|]+))?(?:\|([^\]]+))?\]\]/
+    CALLOUT = /\A<p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\](?:<br>\s*)?/i
+    CALLOUT_ICONS = {
+      "note" => "info-circle",
+      "tip" => "lightbulb-o",
+      "important" => "exclamation-circle",
+      "warning" => "warning",
+      "caution" => "ban"
+    }.freeze
+
+    def self.render(path, base_dir: nil)
+      new(base_dir:).render(path)
+    end
+
+    def initialize(base_dir: nil, **options)
+      @base_dir = base_dir
+      super(options.merge(with_toc_data: true, hard_wrap: true))
+    end
+
+    def sanitize(html)
+      tags = ActionView::Base.sanitized_allowed_tags + %w[table thead tbody th tr td img i]
+      attributes = ActionView::Base.sanitized_allowed_attributes + %w[style colspan src alt id class aria-hidden]
+      super(html, tags:, attributes:)
+    end
+
+    def markdown
+      @markdown ||= Redcarpet::Markdown.new(
+        self,
+        fenced_code_blocks: true,
+        tables: true,
+        autolink: true,
+        strikethrough: true
+      )
+    end
+
+    def render(path)
+      sanitize(markdown.render(File.read(path)))
+    end
+
+    # Convert Obsidian wikilinks to markdown links before parsing, leaving any
+    # text inside fenced or inline code untouched.
+    def preprocess(document)
+      replace_wikilinks(document)
+    end
+
+    def block_code(code, language)
+      # Mermaid diagrams are rendered client-side: emit the raw source in a
+      # <pre class="mermaid"> for mermaid.js, never syntax-highlighted.
+      return content_tag(:pre, code, class: "mermaid") if language == "mermaid"
+
+      lexer = Rouge::Lexer.find_fancy(language.to_s, code) || Rouge::Lexers::PlainText.new
+      formatter = Rouge::Formatters::HTMLInline.new(Rouge::Themes::Github.mode(:dark).new)
+      code = formatter.format(lexer.lex(code))
+      content_tag(:pre, class: "code-block") do
+        content_tag(:code, sanitize(code), class: "language-#{lexer.tag}")
+      end
+    end
+
+    def image(link, title, alt_text)
+      tag(:img, src: link, alt: alt_text, title:, class: "img-responsive")
+    end
+
+    def block_quote(quote)
+      callout = quote.match(CALLOUT)
+
+      if callout
+        type = callout[1].downcase
+        quote = quote.sub(CALLOUT, "<p>")
+        icon = tag.i(class: "fa fa-#{CALLOUT_ICONS.fetch(type)}", aria: { hidden: true })
+        callout_title = %(<p class="callout-title">#{icon} #{type.titleize}</p>)
+
+        %(<blockquote class="callout callout-#{type}">#{callout_title}\n#{quote}</blockquote>)
+      else
+        %(<blockquote>#{quote}</blockquote>)
+      end
+    end
+
+    private
+
+    def replace_wikilinks(document)
+      in_fence = false
+
+      document.each_line.map do |line|
+        if line.start_with?("```")
+          in_fence = !in_fence
+          line
+        elsif in_fence
+          line
+        else
+          replace_wikilinks_in_line(line)
+        end
+      end.join
+    end
+
+    def replace_wikilinks_in_line(line)
+      line.split(/(`[^`]*`)/).map do |part|
+        if part.start_with?("`")
+          part
+        else
+          part.gsub(WIKILINK) do
+            wikilink_markdown(::Regexp.last_match(1), ::Regexp.last_match(2), ::Regexp.last_match(3))
+          end
+        end
+      end.join
+    end
+
+    def wikilink_markdown(name, heading, alias_text)
+      name = name.strip
+      label = alias_text&.strip
+      label ||= heading ? "#{name} > #{heading.strip}" : name
+      "[#{escape_markdown(label)}](#{wikilink_url(name, heading)})"
+    end
+
+    # Escape characters the link label would otherwise trigger as markdown
+    # (emphasis, links, code) so names like assign_preorder render literally.
+    def escape_markdown(text)
+      text.gsub(/[\\_*\[\]`]/) { |char| "\\#{char}" }
+    end
+
+    def wikilink_url(name, heading)
+      segments = [ @base_dir, name ].compact_blank
+      url = "/docs/#{segments.map { |segment| ERB::Util.url_encode(segment) }.join('/')}"
+      url += "##{heading_anchor(heading)}" if heading
+      url
+    end
+
+    # Mirror Redcarpet's with_toc_data anchor generation for [[Note#Heading]]:
+    # drop non-alphanumerics (underscores included), then collapse whitespace to "-".
+    def heading_anchor(heading)
+      heading.strip.downcase.gsub(/[^a-z0-9\s]/, "").gsub(/\s+/, "-").gsub(/\A-+|-+\z/, "")
+    end
+  end
+
+  attr_reader :id, :name, :path
+
+  class << self
+    def where(folder: nil, name: nil)
+      glob = folder ? "docs/#{folder}/" : "{docs/**/,}"
+      Rails.root.glob("#{glob}#{name || "*"}.md").sort.map { |path| new(path) }
+    end
+
+    alias all where
+    delegate :first, :last, to: :where
+
+    def find(name)
+      document = where(name:).first
+      document ||= FOLDER_INDEX_NAMES.lazy.filter_map { |index| where(folder: name, name: index).first }.first
+
+      return document if document
+
+      raise RecordNotFound, "Couldn't find document #{name}"
+    end
+  end
+
+  def initialize(path)
+    @path = path
+    relative_path = Pathname(path).relative_path_from(Rails.root).to_s
+    @id = relative_path.match(%r{\A(?:docs/)?(?<id>.*)\.md\z})&.[](:id)
+    @name = File.basename(path, ".md")
+  end
+
+  def render
+    Renderer.render(path, base_dir: File.dirname(id).then { |dir| dir == "." ? nil : dir })
+  end
+
+  def title
+    name.titleize
+  end
+
+  def breadcrumbs
+    parts = id.split("/")
+
+    parts.each_with_index.map { |part, i| { name: part.titleize, path: "/docs/#{parts[0..i].join('/')}" } }
+  end
+end

data/lib/generators/develoz/docs_render/templates/app/views/docs/show.html.erb.tt

@@ -0,0 +1,7 @@
+<%% content_for :head do %>
+  <%%= javascript_include_tag 'docs', 'data-turbo-track': 'reload' %>
+<%% end %>
+
+<section class="content documentation">
+  <%%= @document.render %>
+</section>

data/lib/generators/develoz/docs_render/templates/config/initializers/redcarpet_rouge.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Redcarpet and Rouge configuration for documentation rendering.
+#
+# The Document model (app/models/document.rb) creates its own
+# Redcarpet::Markdown instance with the required extensions
+# (fenced_code_blocks, tables, autolink, strikethrough) and uses
+# Rouge::Formatters::HTMLInline with the Github dark theme for syntax
+# highlighting of fenced code blocks.
+#
+# Mermaid diagrams are rendered client-side by app/javascript/docs.js,
+# which imports the mermaid package and processes <pre class="mermaid">
+# elements after each Turbo navigation.
+#
+# To use Mermaid, pin it in config/importmap.rb:
+#   pin "mermaid", to: "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs"

data/lib/generators/develoz/frontend_core/frontend_core_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "develoz"
+
+module Develoz
+  module Generators
+    class FrontendCoreGenerator < Develoz::Generators::Base
+      def self.source_root
+        File.expand_path("templates", __dir__)
+      end
+
+      class_option :skip_pagy, type: :boolean, default: false
+
+      def add_frontend_gems
+        add_gem "importmap-rails"
+        add_gem "annotaterb", group: :development
+      end
+
+      def add_pagy_gem
+        return if options[:skip_pagy]
+
+        add_gem "pagy"
+      end
+
+      def create_importmap_config
+        template "config/importmap.rb.tt", "config/importmap.rb"
+      end
+
+      def create_pagy_initializer
+        return if options[:skip_pagy]
+
+        template "config/initializers/pagy.rb.tt", "config/initializers/pagy.rb"
+      end
+
+      def create_annotaterb_config
+        template ".annotaterb.yml.tt", ".annotaterb.yml"
+      end
+    end
+  end
+end

data/lib/generators/develoz/frontend_core/templates/.annotaterb.yml.tt

@@ -0,0 +1,16 @@
+---
+:models: true
+:routes: false
+:active_admin: false
+:additional_file_patterns: []
+:exclude_tests: true
+:exclude_fixtures: true
+:exclude_factories: true
+:exclude_serializers: true
+:exclude_controllers: true
+:exclude_helpers: true
+:exclude_scaffolds: true
+:classified_sort: true
+:show_indexes: true
+:show_foreign_keys: true
+:position: after

data/lib/generators/develoz/frontend_core/templates/config/importmap.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Pin npm packages by running ./bin/importmap
+
+pin "application"
+pin "@hotwired/turbo-rails", to: "turbo.min.js"
+pin "@hotwired/stimulus", to: "stimulus.min.js"
+pin "@hotwired/stimulus-loading", to: "stimulus-loading.js"
+pin "trix", to: "https://esm.sh/trix@2.1.18" # @2.1.18
+pin "@rails/actiontext", to: "@rails--actiontext.js" # @8.1.100
+pin "@rails/activestorage", to: "activestorage.esm.js"
+pin_all_from "app/javascript/controllers", under: "controllers"

data/lib/generators/develoz/frontend_core/templates/config/initializers/pagy.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Pagy initializer file
+# See https://ddnexus.github.io/pagy/resources/initializer/
+
+# Default items per page
+Pagy::OPTIONS[:limit] = 25
+
+# When you are done setting your own default freeze it
+Pagy::OPTIONS.freeze

data/lib/generators/develoz/install/install_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "develoz"
+
+module Develoz
+  module Generators
+    class InstallGenerator < Develoz::Generators::Base
+      class_option :api, type: :boolean, default: false
+      class_option :auth, type: :boolean, default: false
+      class_option :pwa, type: :boolean, default: false
+      class_option :push, type: :boolean, default: false
+      class_option :active_resource, type: :boolean, default: false
+      class_option :admin, type: :boolean, default: false
+      class_option :ui, type: :boolean, default: false
+      class_option :kamal, type: :boolean, default: false
+      class_option :docker, type: :boolean, default: false
+      class_option :db_backup, type: :boolean, default: false
+      class_option :skip_pagy, type: :boolean, default: false
+
+      def install
+        develoz_options = build_options
+        Develoz::Manifest.for(develoz_options).each do |entry|
+          invoke_generator(entry.name, develoz_options.to_h)
+        end
+      end
+
+      private
+
+      OPTION_FLAGS = %i[api auth pwa push active_resource admin ui kamal docker db_backup skip_pagy].freeze
+      private_constant :OPTION_FLAGS
+
+      def build_options
+        flags = OPTION_FLAGS.index_with { |flag| options[flag] }
+        Develoz::Options.new(**flags, app_name: app_name)
+      end
+
+      def invoke_generator(name, generator_options)
+        require "generators/develoz/#{name}/#{name}_generator"
+        klass = Develoz::Generators.const_get("#{name.camelize}Generator")
+        gen = klass.new([], generator_options, destination_root: destination_root)
+        klass.public_instance_methods(false).each { |method| gen.public_send(method) }
+      rescue LoadError
+        say "generator develoz:#{name} not yet available", :yellow
+      rescue NameError => e
+        raise unless e.name.to_s == "#{name.camelize}Generator"
+
+        say "generator develoz:#{name} not yet available", :yellow
+      end
+    end
+  end
+end