shopify_theme_builder 0.1.0.pre → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3868bd423f21a11b7fb217d43f048207b5a6a27f24c42d490e7795ec29e23fe8
-  data.tar.gz: 02da9250406cd995cdd801f409dff1a44209163e56277792fec2f7fc409e5de3
+  metadata.gz: de0bb008961c3b947c4496bd5605d24144073d22d4c721587b3f529073ed1096
+  data.tar.gz: 4e494faa701e5bd4dd47c9b609155626bab03438d85cc7a3603bd9e42e5a0ca3
 SHA512:
-  metadata.gz: 766760501bc75616d5b0fa5c924b06886e775b2366d214bad868d2ee65b8a9e10068b776073f61ef92271e9992c95a616d08b22357ca1b2c8de0308674d05c9a
-  data.tar.gz: 3ca2f5bf072e15aeafdd9d63f0ed83bfba9c73b519d197877a7ac958cf5fb0acf5a7292fcbb2af9543804c18a9ec197b9c522e2e6a1d53850f692174dd157914
+  metadata.gz: bd5f70a0f803adcef6eba571c822f8d7d1b45de0c24aa0360c84bc4c19c431357426d53c471c7735e3e3fdd72d1f7774d2f9d141b90409f59402e52d6f6f8cf4
+  data.tar.gz: 94d70495fd131b5201586e2035c0d4c1ca862718547a112afb755c88b20eb3d34ba3658995c30c252de369dd60010221a213a0cd6d6d600c682a4e34adf60c9c

data/AGENTS.md

@@ -0,0 +1,121 @@
+# AGENTS.md
+
+This document provides guidance for AI agents working on the ShopifyThemeBuilder Ruby gem.
+
+## Project Overview
+
+ShopifyThemeBuilder is a Ruby gem that provides an opinionated builder for Shopify themes with the following key features:
+- Component-based nested folder structure
+- Tailwind CSS integration
+- Stimulus framework support
+- Streamlined Shopify theme development workflow
+
+## Project Structure
+
+```
+shopify_theme_builder/
+├── lib/
+│   ├── shopify_theme_builder.rb          # Main gem entry point
+│   └── shopify_theme_builder/
+│       └── version.rb                     # Gem version definition
+├── spec/                                  # Test files
+├── bin/                                   # Executable scripts
+├── sig/                                   # RBS type signatures
+├── Gemfile                               # Dependencies
+├── Rakefile                              # Rake tasks
+├── shopify_theme_builder.gemspec         # Gem specification
+└── README.md                             # Project documentation
+```
+
+## Key Information
+
+- **Language**: Ruby (>= 3.2.0 required)
+- **Purpose**: Shopify theme development tooling
+- **Architecture**: Component-based approach with modern frontend tools
+- **License**: MIT
+- **Authors**: Massimiliano Lattanzio, Nebulab Team
+
+## Development Guidelines
+
+### Ruby Standards
+- Follow Ruby style conventions
+- Maintain compatibility with Ruby 3.2+
+- Follow semantic versioning for releases
+- Follow Rubocop linting rules (run with `bin/rubocop`)
+
+### Testing
+- Use RSpec for testing (run with `bin/rspec`)
+- Ensure all new features have corresponding tests
+- Test files are located in the `spec/` directory
+
+### Code Structure
+- Main functionality should be in `lib/shopify_theme_builder/`
+- Keep the main entry point (`lib/shopify_theme_builder.rb`) clean
+- Use proper module namespacing under `ShopifyThemeBuilder`
+
+### Dependencies
+- Minimize external dependencies
+- Consider the impact on Shopify theme development workflow
+- Ensure compatibility with Tailwind CSS and Stimulus
+
+## Common Tasks
+
+### Adding New Features
+1. Create corresponding spec files in `spec/`
+2. Implement functionality in `lib/shopify_theme_builder/`
+3. Update version in `lib/shopify_theme_builder/version.rb` if needed
+4. Run tests with `bin/rspec`
+5. Update documentation if necessary
+
+### Development Setup
+- Run `bin/setup` to install dependencies
+- Use `bin/console` for interactive testing
+- Install locally with `bundle exec rake install`
+
+### Release Process
+1. Run `bin/release <version>` (e.g., `bin/release 0.1.0`)
+2. This will create a git commit updating version in `lib/shopify_theme_builder/version.rb`, create git tags and push to RubyGems
+
+## Context for AI Agents
+
+When working on this project:
+
+1. **Focus Area**: This gem is specifically for Shopify theme development, so consider:
+   - Shopify Liquid templating
+   - Theme file structure requirements
+   - Asset compilation and optimization
+   - Component organization patterns
+
+2. **Target Users**: Developers building Shopify themes who want:
+   - Better code organization
+   - Modern CSS framework integration (Tailwind)
+   - JavaScript framework integration (Stimulus)
+   - Streamlined build processes
+
+3. **Integration Points**: Consider how this gem interacts with:
+   - Shopify CLI and development tools
+   - Tailwind CSS build processes
+   - Stimulus controller organization
+   - Component-based architecture
+
+4. **Best Practices**: 
+   - Maintain backward compatibility
+   - Provide clear error messages
+   - Support different Shopify theme structures
+   - Optimize for developer experience
+
+## Repository Information
+
+- **GitHub**: https://github.com/nebulab/shopify_theme_builder
+- **Owner**: nebulab
+- **Main Branch**: main
+- **License**: MIT
+- **Documentation**: https://github.com/nebulab/shopify_theme_builder#readme
+- **Bug Reports**: https://github.com/nebulab/shopify_theme_builder/issues
+
+## Notes
+
+- This is currently in pre-release (version 0.1.0.pre)
+- Usage instructions are still being developed
+- The gem focuses on modern frontend tooling for Shopify themes
+- Component-based architecture is a core principle

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 Massimiliano Lattanzio
+Copyright (c) 2025 Nebulab
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,31 +1,96 @@
 # ShopifyThemeBuilder
 
-An opinionated builder for Shopify themes using:
-- component-based nested folders
-- Tailwind CSS
-- Stimulus
+![Gem Version](https://img.shields.io/gem/v/shopify_theme_builder?logo=rubygems)
+![GitHub branch check runs](https://img.shields.io/github/check-runs/nebulab/shopify_theme_builder/main?logo=github)
+![Codecov](https://img.shields.io/codecov/c/github/nebulab/shopify_theme_builder)
+![Libraries.io dependency status for latest release](https://img.shields.io/librariesio/release/rubygems/shopify_theme_builder)
+![Gem Total Downloads](https://img.shields.io/gem/dt/shopify_theme_builder)
+![GitHub License](https://img.shields.io/github/license/nebulab/shopify_theme_builder)
+
+ShopifyThemeBuilder is a Ruby gem that facilitates the development of Shopify themes by enabling the use of a components folder where you can organize your files and separate liquid, JSON, CSS, JavaScript, comment and doc into a dedicated file. It watches for changes in your component folder and automatically compiles all files into Shopify-compatible Liquid templates.
+
+## What problem does it solve?
+
+Shopify themes have a specific structure where different types of files are stored in designated folders. For example:
+- Sections: Contains Liquid files that define the structure and layout of different sections of the theme.
+- Blocks: Contains reusable Liquid files that can be included in sections.
+- Snippets: Contains reusable Liquid files that can be included in other files.
+
+All these files are stored in the `sections`, `blocks`, and `snippets` folders respectively and cannot be organized in subfolders.
+
+Additionally, all files can include JSON, comments, docs, CSS and JavaScript code, which must be included in the main Liquid file, resulting in large and hard-to-maintain files.
+
+## How does it work?
+
+ShopifyThemeBuilder allows you to create a `components` folder (default is `_components`) where you can organize your theme files in a more modular way. Each component can have its own comments, docs, Liquid, JSON, CSS, and JavaScript files. When you run the watcher, it monitors changes in the components folder and automatically compiles the files into the appropriate Shopify theme structure. Example:
+
+```
+_components/
+  button/
+    comment.txt
+    doc.txt
+    block.liquid
+    schema.json
+    style.css
+    index.js
+blocks/
+  button.liquid
+```
+
+All files inside the `button` folder will be compiled into a single `button.liquid` file in the `blocks` folder, combining the comment, doc, Liquid, JSON, CSS, and JavaScript code.
+
 
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add shopify_theme_builder
+bundle add shopify_theme_builder --group "development"
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+To watch for changes in the default components folder and build the theme, run:
+
+```bash
+bundle exec theme-watcher
+```
+
+You can customize the components folder by passing options:
+
+```bash
+bundle exec theme-watcher my_components
+```
+
+If you prefer, you can import the watcher executable locally using:
+
+```bash
+bundle binstubs shopify_theme_builder
+```
+
+It will create a `bin/theme-watcher` file that you can run with:
+
+```bash
+bin/theme-watcher
+```
+
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, run `bin/release VERSION`, which will update the version file, create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## TODO
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- [ ] Run the tailwind build process automatically.
+- [ ] Check if stimulus controllers are loaded correctly in Shopify themes.
+- [ ] Create a command to build an example component with all the files.
+- [ ] Decompile existing Shopify files into components structure (?).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/MassimilianoLattanzio/shopify_theme_builder.
+Bug reports and pull requests are welcome on GitHub at https://github.com/nebulab/shopify_theme_builder.
 
 ## License
 

data/exe/theme-watcher

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "shopify_theme_builder"
+
+$stdout.sync = true
+
+if ARGV.empty?
+  ShopifyThemeBuilder.watch
+else
+  ShopifyThemeBuilder.watch(folders_to_watch: ARGV)
+end

data/lib/shopify_theme_builder/builder.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ShopifyThemeBuilder
+  # Builder is responsible for building Shopify theme files
+  # by delegating processing to appropriate classes based on file types.
+  class Builder
+    def initialize(files_to_process:)
+      @files_to_process = files_to_process
+      @processed_files = []
+    end
+
+    def build
+      puts "Processing #{@files_to_process.count} files..."
+
+      @files_to_process.each do |file|
+        @processed_files << ShopifyThemeBuilder::LiquidProcessor.new(file).process
+      end
+
+      puts "Built #{@processed_files.count} files." if @processed_files.any?
+    end
+  end
+end

data/lib/shopify_theme_builder/liquid_processor.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module ShopifyThemeBuilder
+  # LiquidProcessor is responsible for processing Liquid files
+  # by combining various related files (Liquid, schema, CSS, JS, doc, comment)
+  # into a single compiled Liquid file suitable for Shopify themes.
+  # It supports specific Liquid file types and organizes the output
+  # into designated folders based on the file type.
+  # Requirements:
+  # - The current folder must contain one Liquid file named: section.liquid, snippet.liquid, or block.liquid.
+  # - Blocks must have a schema.json file.
+  # - Schema file must be named schema.json.
+  # - CSS file must be named style.css.
+  # - JS file must be named index.js.
+  # - Documentation file must be named doc.txt.
+  # - Comment file must be named comment.txt.
+  class LiquidProcessor
+    LIQUID_FILE_TYPES = %w[section snippet block].freeze
+    SUPPORTED_FILES = {
+      comment: "comment.txt",
+      doc: "doc.txt",
+      liquid: LIQUID_FILE_TYPES.map { |type| "#{type}.liquid" },
+      schema: "schema.json",
+      stylesheet: "style.css",
+      javascript: "index.js"
+    }.freeze
+    SUPPORTED_VALUES = SUPPORTED_FILES.values.flatten.freeze
+
+    def initialize(file)
+      @file = file
+      @contents = +""
+      @logger = Logger.new($stdout)
+    end
+
+    def process
+      return unless processable?
+
+      compile_content
+
+      File.write(compiled_filename, @contents.lstrip)
+
+      compiled_filename
+    end
+
+    private
+
+    # Returns true if the file is processable, false otherwise.
+    def processable?
+      supported? && correct_liquid_file? && correct_filename?
+    end
+
+    # Checks if the file is in the list of supported files.
+    def supported?
+      unless SUPPORTED_VALUES.include?(file_name)
+        @logger.error "Skipping unsupported file: #{@file}"
+        return false
+      end
+
+      true
+    end
+
+    # Checks if there is exactly one liquid file in the directory.
+    def correct_liquid_file?
+      if liquid_files.empty?
+        @logger.error "No liquid file found in #{file_dir}"
+        return false
+      end
+
+      if liquid_files.size > 1
+        @logger.error "Multiple liquid files found in #{file_dir}"
+        return false
+      end
+
+      true
+    end
+
+    # Checks if the compiled filename is valid.
+    def correct_filename?
+      if compiled_filename.nil?
+        @logger.error(
+          "Invalid file name for file: #{@file}\nProbably because the file is directly under the components folder."
+        )
+
+        return false
+      end
+
+      true
+    end
+
+    def file_name
+      @file_name ||= File.basename(@file)
+    end
+
+    def file_dir
+      @file_dir ||= File.dirname(@file)
+    end
+
+    # Returns an array of liquid files in the directory.
+    def liquid_files
+      @liquid_files ||= Dir.glob(LIQUID_FILE_TYPES.map { |type| "#{file_dir}/#{type}.liquid" })
+    end
+
+    def liquid_file
+      @liquid_file ||= liquid_files.first
+    end
+
+    def liquid_file_type
+      @liquid_file_type ||= File.basename(liquid_file, ".liquid")
+    end
+
+    # Returns the compiled filename based on the component name and liquid file type.
+    # Example: _folder_to_watch/button/section.liquid -> sections/button.liquid
+    def compiled_filename
+      filename_arr = file_dir.split(File::SEPARATOR) # Split the directory path into an array.
+      filename_arr = filename_arr.drop(1) # Remove the base components folder from the path. E.g., _components
+      filename_arr -= LIQUID_FILE_TYPES # Remove liquid file types from the path. E.g., section, snippet, block
+      filename_arr -= LIQUID_FILE_TYPES.map { |type| "#{type}s" } # Remove pluralized liquid file types from the path.
+      filename = filename_arr.join("--") # Join remaining parts with '--'. E.g., button--subbutton
+
+      return nil if filename.empty?
+
+      "#{liquid_file_type}s/#{filename}.liquid"
+    end
+
+    # Compiles the content by aggregating various related files.
+    def compile_content
+      SUPPORTED_FILES.each_key do |key|
+        @contents << formatted_content(key)
+      end
+    end
+
+    # Returns the formatted content for a given content type.
+    # For liquid, it returns the raw content.
+    # For others, it wraps the content in appropriate Liquid tags.
+    # E.g., {% schema %}...{% endschema %}
+    # If the file does not exist, it returns an empty string.
+    # If there is a default content method defined, it includes that content as well.
+    # E.g., for comment, it includes a default comment about the source file.
+    def formatted_content(content_type)
+      content_type_file = content_type == :liquid ? liquid_file : "#{file_dir}/#{SUPPORTED_FILES[content_type]}"
+
+      content = respond_to?("default_#{content_type}", true) ? send("default_#{content_type}") : ""
+      content += file_content(content_type_file) if File.exist?(content_type_file)
+
+      return "" if content.empty?
+      return content if content_type == :liquid
+
+      "\n{% #{content_type} %}#{content}{% end#{content_type} %}\n"
+    end
+
+    def file_content(file)
+      content = File.read(file).strip
+      content.empty? ? "" : "\n#{content}\n"
+    end
+
+    def default_comment
+      "\n------------------------------------------------------------\n\
+IMPORTANT: The contents of this file are auto-generated.\n\
+Avoid editing this file directly.\n\n\
+Compiled from #{liquid_file}\n\
+------------------------------------------------------------\n"
+    end
+  end
+end

data/lib/shopify_theme_builder/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ShopifyThemeBuilder
-  VERSION = "0.1.0.pre"
+  VERSION = "0.2.0"
 end

data/lib/shopify_theme_builder/watcher.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "filewatcher"
+
+module ShopifyThemeBuilder
+  # Watcher class for ShopifyThemeBuilder.
+  # It wraps the Filewatcher functionality to monitor file changes.
+  # It delegates method calls to the underlying Filewatcher instance.
+  # Check: https://github.com/filewatcher/filewatcher
+  class Watcher
+    def initialize(...)
+      @filewatcher = Filewatcher.new(...)
+    end
+
+    def method_missing(name, ...)
+      if @filewatcher.respond_to?(name)
+        @filewatcher.send(name, ...)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private)
+      @filewatcher.respond_to?(name) || super
+    end
+  end
+end

data/lib/shopify_theme_builder.rb

@@ -1,8 +1,52 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "logger"
 require_relative "shopify_theme_builder/version"
+require_relative "shopify_theme_builder/watcher"
+require_relative "shopify_theme_builder/liquid_processor"
+require_relative "shopify_theme_builder/builder"
 
+# The main module for ShopifyThemeBuilder.
 module ShopifyThemeBuilder
-  class Error < StandardError; end
-  # Your code goes here...
+  class << self
+    def watch(folders_to_watch: ["_components"])
+      create_folders(folders_to_watch)
+
+      initial_build(folders_to_watch)
+
+      watch_folders(folders_to_watch)
+    end
+
+    private
+
+    def create_folders(folders_to_watch)
+      puts "Creating necessary folders..."
+
+      FileUtils.mkdir_p(folders_to_watch)
+      FileUtils.mkdir_p("sections")
+      FileUtils.mkdir_p("blocks")
+      FileUtils.mkdir_p("snippets")
+    end
+
+    def initial_build(folders_to_watch)
+      puts "Doing an initial build..."
+
+      folders_to_watch.each do |folder|
+        Builder.new(files_to_process: Dir.glob("#{folder}/**/*.*")).build
+      end
+    end
+
+    def watch_folders(folders_to_watch)
+      puts "Watching for changes in '#{folders_to_watch.join(", ")}' folders..."
+
+      Watcher.new(folders_to_watch).watch do |changes|
+        changes.each_key do |filename|
+          relative_filename = filename.gsub("#{Dir.pwd}/", "")
+
+          Builder.new(files_to_process: [relative_filename]).build if relative_filename.start_with?(*folders_to_watch)
+        end
+      end
+    end
+  end
 end

metadata

@@ -1,35 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: shopify_theme_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre
+  version: 0.2.0
 platform: ruby
 authors:
 - Massimiliano Lattanzio
+- Nebulab Team
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: filewatcher
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 email:
 - massimiliano.lattanzio@gmail.com
-executables: []
+executables:
+- theme-watcher
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- exe/theme-watcher
 - lib/shopify_theme_builder.rb
+- lib/shopify_theme_builder/builder.rb
+- lib/shopify_theme_builder/liquid_processor.rb
 - lib/shopify_theme_builder/version.rb
+- lib/shopify_theme_builder/watcher.rb
 - sig/shopify_theme_builder.rbs
-homepage: https://github.com/massimilianolattanzio/shopify_theme_builder?tab=readme-ov-file#readme
+homepage: https://github.com/nebulab/shopify_theme_builder?tab=readme-ov-file#readme
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  bug_tracker_uri: https://github.com/massimilianolattanzio/shopify_theme_builder/issues
-  homepage_uri: https://github.com/massimilianolattanzio/shopify_theme_builder?tab=readme-ov-file#readme
-  source_code_uri: https://github.com/massimilianolattanzio/shopify_theme_builder
-  changelog_uri: https://github.com/MassimilianoLattanzio/shopify_theme_toolkit/releases
+  bug_tracker_uri: https://github.com/nebulab/shopify_theme_builder/issues
+  homepage_uri: https://github.com/nebulab/shopify_theme_builder?tab=readme-ov-file#readme
+  source_code_uri: https://github.com/nebulab/shopify_theme_builder
+  changelog_uri: https://github.com/nebulab/shopify_theme_builder/releases
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib