bunko 0.2.0

data/ROADMAP.md

@@ -0,0 +1,519 @@
+# Bunko 1.0 Roadmap
+
+**Goal:** Ship a production-ready CMS gem where a Rails developer can add `gem "bunko"`, run a couple generators, and have a working blog in under 5 minutes. Officially we are only targeting support for Rails but we are trying to keep dependencies as light as possible.
+
+**Note:** Version 0.1.0 was released as a placeholder to register the gem name. We're now building toward 1.0.0, using 0.x versions during active development.
+
+---
+
+## Development Status
+
+- [x] **Milestone 1: Post Model Behavior** - ✅ COMPLETED
+- [x] **Milestone 2: Collection Controllers** - ✅ COMPLETED
+- [x] **Milestone 3: Installation Generator** - ✅ COMPLETED
+- [x] **Milestone 4: Routing Helpers** - ✅ COMPLETED
+- [x] **Milestone 5: Post Convenience Methods** - ✅ COMPLETED
+- [x] **Milestone 6: Static Pages** - ✅ COMPLETED
+- [ ] **Milestone 7: Configuration** - 🚧 PENDING (core system exists, may need expansion)
+- [ ] **Milestone 8: Documentation** - 🚧 PENDING
+- [ ] **Milestone 9: Release** - 🚧 PENDING
+
+---
+
+## Success Criteria
+
+By 1.0, a Rails developer should be able to:
+
+1. ✅ Install Bunko and generate a working blog in < 5 minutes
+2. ✅ Add a second content collection (e.g., `/docs`) in < 2 minutes
+3. ✅ Attach the text editor of their choice to create and edit posts
+4. ✅ Schedule posts for future publication
+5. ✅ Organize content into different post types without migrations
+6. ✅ Customize views with their own HTML/CSS
+7. ✅ Automatically use slug-based URLs instead of IDs
+8. ✅ Create standalone pages (About, Contact, etc.) without full collections
+
+---
+
+## Milestone 1: Post Model Behavior
+
+**Spec:** A Post model with Bunko enabled should have all essential CMS functionality.
+
+### Required Behavior
+
+**Scopes & Queries:**
+- Developer can query `Post.published` and only see published posts with `published_at <= Time.current`
+- Developer can query `Post.draft` and only see draft posts
+- Developer can query `Post.scheduled` and only see posts scheduled for future publication
+- Developer can filter posts by type: `Post.by_post_type('blog')` or similar API
+- Default ordering shows most recent posts first
+
+**Slug Generation:**
+- When a post is created without a slug, one is auto-generated from the title
+- Slugs are URL-safe (e.g., "Hello World" becomes "hello-world")
+- Slugs are unique within their post_type
+- Developer can provide custom slug and it won't be overwritten
+
+**Publishing Workflow:**
+- Post status can be: 'draft', 'published', or 'scheduled'
+- When status changes to 'published' and `published_at` is blank, it auto-sets to current time
+- Posts with status='published' but `published_at` in future are treated as scheduled
+- Invalid status values are rejected
+
+**Reading Metrics:**
+- If post has `word_count`, developer can get estimated reading time
+- Reading time calculation is configurable (default ~250 words/minute)
+
+**Routing Support:**
+- Users should be able to route #index/#show collections of posts with a simple routes entry, eg something like "mount_bunko :case_studies" should automatically show all posts where post_type = 'case_study' (or 'case_studies'?) in the subfolder /case-studies/ with the slug for that post. Similar to if they wrote this:
+    - resources :case_studies, controller: 'case_studies', path: 'case-studies', param: :slug, only: %i[index show]
+- Users should possibly be able to route their core Posts model behind their existing admin / auth area, similar to how they mount sidekiq. This section is intended to be admin only for post editing - so full CRUD but not publicly visible. This should be optional, eg if they want to use a tool like Avo with their [Rhino editor](https://docs.avohq.io/3.0/fields/rhino.html) or [Markdown editor](https://docs.avohq.io/3.0/fields/markdown.html), they don't need to mount this section at all. https://avohq.io/
+
+```
+require "bunko/editor" # require the web UI
+
+Rails.application.routes.draw do
+  mount Bunko::Editor => "/posts" # access it at http://localhost:3000/posts
+  ...
+end
+```
+
+### Acceptance Test
+
+```ruby
+# Developer can do this:
+class Post < ApplicationRecord
+  acts_as_bunko_post
+end
+
+# And get this behavior:
+post = Post.create!(title: "Hello World", content: "...", post_type: 'blog')
+post.slug # => "hello-world"
+post.to_param # => "hello-world"
+post.status # => "draft"
+
+post.update!(status: 'published')
+post.published_at # => Time.current (auto-set)
+
+Post.published.count # => 1
+Post.draft.count # => 0
+```
+
+---
+
+## Milestone 2: Collection Controllers
+
+**Spec:** A controller should be able to serve a content collection with minimal code.
+
+### Required Behavior
+
+**Defaults**
+- If user just adds a routes, all of our standard behaviors should be observed.
+- If user chooses to generate their own controller, we should allow that.
+- If user wants to use our controllers but adjust settings through bunko.rb initializer, we should allow that.
+
+**Index Action:**
+- Shows all published posts for a given post_type
+- Does not leak other configured posts types in any way or scopes
+- Paginates results - recommend pagy but this should be adaptable? Or perhaps enable Pagy or kamanari behavior in a bunko.rb initializer
+- Allows customization of per_page, ordering, layout
+- Provides access to collection name in views
+
+**Show Action:**
+- Finds post by slug
+- Scoped to the correct  - eg you should be able to have same slug on 2 different post types
+- Returns 404 if not found (and routes doesn't take over with a 301 or something)
+- Provides access to the post in views
+
+**Multiple Post Types:**
+- Single controller can serve multiple related post types
+- Example: Resources controller serves guides, templates, checklists
+
+### Acceptance Test
+
+```ruby
+# Developer can do this:
+class BlogController < ApplicationController
+  bunko_collection :blog  # or whatever the API is
+end
+
+# And get these routes working:
+GET /blog          # => BlogController#index (lists blog posts)
+GET /blog/:slug    # => BlogController#show (shows single post)
+
+# Views have access to:
+@posts             # in index
+@post              # in show
+@collection_name   # 'blog'
+
+# Developer can customize:
+class ChangelogController < ApplicationController
+  bunko_collection :changelog, per_page: 20, layout: 'docs'
+end
+```
+
+---
+
+## Milestone 3: Installation Generator
+
+**Spec:** Running `rails bunko:install` should create everything needed for a working blog.
+
+**Implementation Note:** This milestone was implemented as a two-phase pattern:
+1. `rails bunko:install` - Creates migrations, models, and initializer
+2. `rails bunko:setup` - Generates controllers, views, and routes based on configuration
+
+This approach allows users to customize their post types in the initializer before generating the controllers/views, and makes it easy to add new collections later.
+
+### Required Behavior
+
+**Migration Creation:**
+- Detects database type (PostgreSQL, SQLite, MySQL) and generates appropriate migration
+- Creates `posts` table with essential fields:
+  - `title` (string, required)
+  - `slug` (string, required, indexed)
+  - `content` (text by default, json/jsonb with `--json-content` flag for JSON-based editors)
+  - `post_type` (references, required)
+  - `status` (string, indexed, default: 'draft') # should this be references to a post_status table?
+  - `published_at` (datetime, indexed)
+  - Timestamps for created_at and updated_at
+- Creates `post_types` table with essential fields:
+  - `name` (string, required)
+  - `slug` (string, required, indexed)
+  - Timestamps
+- Adds unique constraint on `[slug, post_type]`
+- A post should always have only one post_type, or allow nil? Never multiple though. By default we should load in Post? Or allow nil?
+- Optional fields based on flags (see Generator Options below)
+- User should be able to override our migration and add something like "acts_as_post" to the model to get the same behaviors.
+
+**Model Generation:**
+- Creates `app/models/post.rb` with Bunko enabled
+- Creates `app/models/post_type.rb` with Bunko enabled
+- Includes comments explaining customization
+
+**Controller Generation:**
+- Creates `app/controllers/blog_controller.rb`
+- Configured to serve 'blog' post type
+- Includes comments explaining how to add more collections
+
+**View Generation:**
+- Creates `app/views/blog/index.html.erb` with semantic HTML
+- Creates `app/views/blog/show.html.erb` with semantic HTML
+- No CSS, no JavaScript - just clean HTML with helpful comments
+- Shows title, content, published date, reading time
+
+**Route Generation:**
+- Adds routes for blog (index + show)
+- Uses slug as param, not ID
+
+**Initializer Generation:**
+- Creates `config/initializers/bunko.rb`
+- Includes common configuration options (commented out with examples)
+
+**Post-Install Message:**
+- Shows next steps (run migration, create first post)
+- Links to documentation
+
+### Generator Options
+
+- `--skip-seo` - Skip adding SEO fields (title_tag, meta_description)
+- `--json-content` - Use json/jsonb for content field instead of text (for JSON-based editors)
+
+### Acceptance Test
+
+```bash
+# Developer runs:
+$ rails bunko:install
+$ rails db:migrate
+
+# Result: They can visit /blog and see a working (empty) blog
+# They can create a post in console and see it at /blog/post-slug
+```
+
+---
+
+## Milestone 4: Routing Helpers
+
+**Spec:** Setting up routes for collections should be simple and conventional.
+
+### Required Behavior
+
+**Route DSL:**
+- Developer can call `bunko_collection :blog` instead of writing full resources line
+- Supports custom paths (e.g., `bunko_collection :case_study, path: 'case-studies'`)
+- Supports limiting actions (e.g., `only: [:index]` for index-only collection) # not critical
+- Supports custom controller names
+
+### Acceptance Test
+
+```ruby
+# Developer can do this in config/routes.rb:
+Rails.application.routes.draw do
+  bunko_collection :blog
+  bunko_collection :docs
+  bunko_collection :case_study, path: 'case-studies' #perhaps path should be automatically hyphenated and/or inflected/pluralized?
+end
+
+# And get these routes:
+# /blog          => blog#index
+# /blog/:slug    => blog#show
+# /docs          => docs#index
+# /docs/:slug    => docs#show
+# /case-studies      => case_study#index
+# /case-studies/:slug => case_study#show
+```
+
+---
+
+## Milestone 5: Post Convenience Methods
+
+**Spec:** Common CMS view patterns should be available as Post instance methods for clean, conflict-free usage in views.
+
+**Implementation Note:** Originally planned as view helpers, we decided to implement these as Post model methods instead. This approach:
+- Avoids namespace conflicts (no `bunko_` prefix needed for generic helper names)
+- Keeps views cleaner (`post.excerpt` vs `bunko_excerpt(post)`)
+- Works identically in index loops and show views
+
+### Required Behavior
+
+**Content Formatting:**
+- `post.excerpt(length: 160, omission: "...")` - returns truncated content, strips HTML, preserves word boundaries
+- `post.reading_time_text` - returns "X min read" string (extends existing `reading_time` integer method)
+
+**Date Formatting:**
+- `post.published_date(format = :long)` - returns formatted published_at using I18n.l
+- Supports Rails date formats: `:long`, `:short`, `:db`, custom strftime
+
+**Navigation:**
+- Not needed - routing DSL automatically generates helpers like `blog_path`, `blog_post_path(post)`
+
+### Acceptance Test
+
+```erb
+<!-- Index view: loop over posts -->
+<% @posts.each do |post| %>
+  <article>
+    <h2><%= link_to post.title, blog_post_path(post) %></h2>
+    <p class="meta">
+      <%= post.published_date %> · <%= post.reading_time_text %>
+    </p>
+    <p><%= post.excerpt %></p>
+  </article>
+<% end %>
+
+<!-- Show view: single post -->
+<article>
+  <h1><%= @post.title %></h1>
+  <p class="meta">
+    <%= @post.published_date(:long) %> · <%= @post.reading_time_text %>
+  </p>
+  <div class="content">
+    <%= @post.content %>
+  </div>
+</article>
+```
+
+---
+
+## Milestone 6: Static Pages
+
+**Spec:** Developers should be able to create standalone pages (About, Contact, Privacy Policy) without needing a full collection with an index page.
+
+### Required Behavior
+
+**Routing DSL:**
+- `bunko_page :about` creates a single route: `GET /about → pages#show`
+- Supports custom paths: `bunko_page :about, path: "about-us"`
+- Supports custom controllers: `bunko_page :contact, controller: "static_pages"`
+- Works with namespaces: `namespace :legal do bunko_page :privacy end`
+
+**PagesController:**
+- Single shared controller for all pages (no per-page controller generation)
+- Smart view resolution: checks for custom page template (e.g., `pages/about.html.erb`) first
+- Falls back to default `pages/show.html.erb` if custom template doesn't exist
+- Raises 404 if page Post not found
+
+**Configuration:**
+- Opt-out support: `config.allow_static_pages = false`
+- Reserved "pages" post_type namespace with validation error
+- Auto-generated during `rails bunko:setup` if enabled (default: true)
+
+**Architecture:**
+- Uses same Post model as collections (maintains one-model architecture)
+- Pages stored with `post_type = "pages"`
+- Slug must match route name (e.g., route `bunko_page :about` expects Post with slug "about")
+
+### Acceptance Test
+
+```ruby
+# In config/routes.rb:
+Rails.application.routes.draw do
+  bunko_page :about
+  bunko_page :contact
+  bunko_page :privacy
+end
+
+# Create page content:
+pages_type = PostType.find_by(name: "pages")
+
+Post.create!(
+  title: "About Us",
+  content: "<p>Welcome to our company...</p>",
+  post_type: pages_type,
+  slug: "about",  # Must match route name
+  status: "published"
+)
+
+# Result:
+# GET /about → renders pages/about.html.erb or pages/show.html.erb
+# GET /contact → 404 (no Post with slug "contact" exists yet)
+```
+
+---
+
+## Milestone 7: Configuration
+
+**Spec:** Bunko behavior should be customizable via initializer without modifying gem code.
+
+### Required Behavior
+
+**Configurable Options:**
+- Post model name (default: 'Post')
+- Valid post types (default: ['post'])
+- Valid statuses (default: ['draft', 'published', 'scheduled'])
+- Default status (default: 'draft')
+- Reading speed in words/minute (default: 250)
+- Excerpt length (default: 160)
+- Slug generation strategy (default: parameterize)
+
+**Configuration API:**
+- Developer uses block syntax in initializer
+- Configuration is globally accessible
+- Invalid configuration values are validated
+
+### Acceptance Test
+
+```ruby
+# Developer can configure in config/initializers/bunko.rb:
+Bunko.configure do |config|
+  config.post_type "post"
+  config.post_type "page"
+  config.post_type "doc"
+  config.post_type "tutorial"
+
+  config.reading_speed = 200
+  config.excerpt_length = 200
+  config.slug_generator = ->(title) { title.parameterize.truncate(50) }
+end
+
+# And it affects behavior:
+post = Post.create!(title: "Very Long Title...")
+# slug uses custom generator
+```
+
+---
+
+## Milestone 8: Documentation
+
+**Spec:** Documentation should be excellent, examples should be practical.
+
+### Required Deliverables
+
+**README.md:**
+- Philosophy and goals clearly stated
+- Installation instructions (add to Gemfile, run generator)
+- Quick start guide (5 minute blog)
+- Multi-collection setup example
+- Configuration options documented
+- Customization patterns explained
+- What Bunko doesn't do (auth, admin UI, etc.)
+
+**EXAMPLES.md:**
+- Basic blog setup
+- Blog + docs setup
+- Custom fields using metadata
+- Custom scopes
+- Overriding views
+- Integration with admin gems (Avo, Administrate, etc.)
+
+**Code Documentation:**
+- All public APIs have clear documentation
+- Generated code includes helpful comments
+- Configuration options explained in generated initializer
+
+**Example Apps:**
+- `examples/basic_blog` - Minimal blog
+- `examples/multi_collection` - Blog + docs + changelog
+
+### Acceptance Test
+
+New developer can:
+- Read README and understand what Bunko does in < 2 minutes
+- Follow quick start and have working blog in < 5 minutes
+- Find answer to "how do I customize X?" in documentation
+- Clone an example app and see Bunko in action
+
+---
+
+## Milestone 9: Release
+
+**Spec:** 1.0.0 is published to RubyGems and ready for production use.
+
+### Required Before Release
+
+**Compatibility:**
+- Works with Rails 8.0+ and follows Rails EOL maintenance policy
+- Works with Ruby 3.2, 3.3, 3.4 and follows Ruby EOL maintenance policy
+- Works with PostgreSQL, SQLite, MySQL
+- Test coverage > 90%
+- All Standard linter checks pass
+
+**Package:**
+- bunko.gemspec has no TODOs
+- Proper description and summary
+- Correct homepage and source URLs
+- Appropriate version number (1.0.0)
+- CHANGELOG.md updated
+
+**Documentation:**
+- README complete and accurate
+- EXAMPLES.md or docs have practical examples
+- Generated code has helpful comments
+- GitHub release notes written
+
+**Distribution:**
+- Gem builds successfully
+- Gem published to RubyGems
+- GitHub release created
+- Installation tested in fresh Rails app
+
+### Acceptance Test
+
+```bash
+# Any developer can:
+$ gem install bunko
+$ rails new myblog
+$ cd myblog
+$ bundle add bunko
+$ rails bunko:install
+$ rails db:migrate
+$ rails bunko:setup
+$ rails bunko:sample_data
+$ rails server
+
+# Visit http://localhost:3000/blog and see working blog with sample content
+```
+
+---
+
+## Out of Scope for 1.0
+
+These are excellent features but not required for initial release:
+
+- **Admin UI generator** - `rails generate bunko:admin`
+- **Seed task** - `rails bunko:seed` for sample content
+- **Custom fields DSL** - Beyond metadata jsonb
+- **Publishing callbacks** - `after_publish`, etc.
+- **Versioning support** - Draft history, rollback
+- **Multi-collection controllers** - Single controller, many types
+- **Author associations** - belongs_to :author
+- **Category/tag models** - For now, use strings or metadata

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/bunko/configuration.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Bunko
+  class Configuration
+    class PostTypeCustomizer
+      def initialize(post_type_hash)
+        @post_type_hash = post_type_hash
+      end
+
+      def title=(value)
+        @post_type_hash[:title] = value
+      end
+
+      # Future: Add more customization methods
+      # def per_page=(value)
+      #   @post_type_hash[:per_page] = value
+      # end
+    end
+
+    class CollectionCustomizer
+      def initialize(collection_hash)
+        @collection_hash = collection_hash
+      end
+
+      def title=(value)
+        @collection_hash[:title] = value
+      end
+
+      def post_types=(value)
+        # Normalize post_types to array of names (using underscores, not hyphens)
+        @collection_hash[:post_types] = Array(value).map { |pt| pt.to_s.parameterize.tr("-", "_") }
+      end
+
+      def scope=(callable)
+        @collection_hash[:scope] = callable
+      end
+
+      # Future: Add more customization methods
+      # def per_page=(value)
+      #   @collection_hash[:per_page] = value
+      # end
+    end
+
+    attr_accessor :reading_speed, :excerpt_length, :auto_update_word_count, :valid_statuses, :post_types, :collections, :allow_static_pages
+
+    def initialize
+      @reading_speed = 250 # words per minute
+      @excerpt_length = 160 # characters
+      @auto_update_word_count = true # automatically update word_count when content changes
+      @valid_statuses = %w[draft published scheduled]
+      @post_types = [] # Must be configured in initializer
+      @collections = [] # Multi-type collections
+      @allow_static_pages = true # Enable standalone pages feature by default
+    end
+
+    def post_type(name, title: nil, &block)
+      # Validate name format (must use underscores, not hyphens, for Ruby class naming)
+      name_str = name.to_s
+
+      if name_str.include?("-")
+        raise ArgumentError, "PostType name '#{name_str}' cannot contain hyphens. Use underscores instead (e.g., 'case_study'). URLs will automatically use hyphens (/case-study/)."
+      end
+
+      unless name_str.match?(/\A[a-z0-9_]+\z/)
+        raise ArgumentError, "PostType name '#{name_str}' must contain only lowercase letters, numbers, and underscores"
+      end
+
+      # Reserved name for static pages feature
+      if name_str == "pages"
+        raise ArgumentError, "PostType name 'pages' is reserved for the static pages feature. Use config.allow_static_pages to control this feature."
+      end
+
+      # Check for conflicts with existing collections
+      if collection_exists?(name_str)
+        raise ArgumentError, "PostType name '#{name_str}' conflicts with existing collection name"
+      end
+
+      # Auto-generate title from name (e.g., "case_study" → "Case Study")
+      generated_title = title || name_str.titleize
+
+      post_type = {name: name_str, title: generated_title}
+
+      # Allow customization via block (block overrides params)
+      if block_given?
+        customizer = PostTypeCustomizer.new(post_type)
+        block.call(customizer)
+      end
+
+      @post_types << post_type
+    end
+
+    def collection(name, title: nil, post_types: nil, scope: nil, &block)
+      # Validate name format (must use underscores, not hyphens)
+      name_str = name.to_s
+
+      if name_str.include?("-")
+        raise ArgumentError, "Collection name '#{name_str}' cannot contain hyphens. Use underscores instead (e.g., 'long_reads'). URLs will automatically use hyphens (/long-reads/)."
+      end
+
+      unless name_str.match?(/\A[a-z0-9_]+\z/)
+        raise ArgumentError, "Collection name '#{name_str}' must contain only lowercase letters, numbers, and underscores"
+      end
+
+      # Check for conflicts with existing post_types
+      if post_type_exists?(name_str)
+        raise ArgumentError, "Collection name '#{name_str}' conflicts with existing PostType name"
+      end
+
+      # Check for conflicts with existing collections
+      if collection_exists?(name_str)
+        raise ArgumentError, "Collection '#{name_str}' already exists"
+      end
+
+      # Require at least post_types param or block
+      unless post_types || block_given?
+        raise ArgumentError, "Collection '#{name_str}' requires either post_types parameter or a configuration block"
+      end
+
+      # Auto-generate title from name (e.g., "long_reads" → "Long Reads")
+      generated_title = title || name_str.titleize
+
+      # Normalize post_types to array of names (using underscores, not hyphens)
+      normalized_post_types = post_types ? Array(post_types).map { |pt| pt.to_s.parameterize.tr("-", "_") } : []
+
+      collection = {
+        name: name_str,
+        title: generated_title,
+        post_types: normalized_post_types,
+        scope: scope
+      }
+
+      # Allow customization via block (block overrides params)
+      if block_given?
+        customizer = CollectionCustomizer.new(collection)
+        block.call(customizer)
+      end
+
+      # Validate that post_types was set
+      if collection[:post_types].empty?
+        raise ArgumentError, "Collection '#{name_str}' must specify at least one post_type"
+      end
+
+      @collections << collection
+    end
+
+    def find_post_type(name)
+      @post_types.find { |pt| pt[:name] == name.to_s }
+    end
+
+    def find_collection(name)
+      @collections.find { |c| c[:name] == name.to_s }
+    end
+
+    private
+
+    def post_type_exists?(name)
+      @post_types.any? { |pt| pt[:name] == name.to_s }
+    end
+
+    def collection_exists?(name)
+      @collections.any? { |c| c[:name] == name.to_s }
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end