fluid_cli 0.1.8 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95f54f4f147815bbde7b9477dde64b103a41bfa721e0c88b1cdd98a526421b2a
-  data.tar.gz: 61151c84b36ec0ff0566e61e9503b36df20f560df7f4f1a3b46a7650b55f7fac
+  metadata.gz: 84ff5fea48f57756d085af8e58148aec8b8b98161b152f5c7e95252f51e2348b
+  data.tar.gz: 0b65b1eccfcf8e095961e4518eb9c5e73cb4b6884b029f12074bfe477b1dc40a
 SHA512:
-  metadata.gz: a81fc2e51ad5e6d26de123c83cfe854405cf1b574fcb4d8e834220d2af36e5b62afa269063f4d9f9c05cfb277fb5dd0dd3a1e56ba67565226c3fe794cf252708
-  data.tar.gz: 1e7e62ba1049194533c5559c87394fedab9d11c20bcd437f98c3820d1723236aa4221be85e3d774fb5ab13de7bd9ff840356cbefe2710c81932d570c84464ba0
+  metadata.gz: a951d7bfafd5ce072e8b2b8e91f308878021a13697848f0eb6fa294f09e5e0d2118a02339530914fa3dcd0647b2c7e7f29bf36bc4d2f89adcfebaf3e3b225937
+  data.tar.gz: 1031eb13ffbfb6025e7adbea17dca9bc76d7ab220840e3a8e5782422ba2edba49ee8dc8ccbc7a631e244e04aca5d62718db9f1d85043ec4ad5770008c00e2533

data/README.md

@@ -1 +1,185 @@
-# fluid_cli
+# Fluid CLI
+
+The official command-line interface for the [Fluid](https://fluid.app) e-commerce platform. Build, preview, and deploy themes for your Fluid storefront directly from the terminal.
+
+## Installation
+
+### Prerequisites
+
+- Ruby >= 3.1.0
+- Bundler
+
+### From Source
+
+```sh
+git clone https://github.com/fluid-commerce/fluid-cli.git
+cd fluid-cli
+bundle install
+```
+
+### As a Gem
+
+```sh
+gem install fluid_cli
+```
+
+## Quick Start
+
+```sh
+# Authenticate with your Fluid account
+fluid login
+
+# Initialize a new theme from the base template
+fluid theme init
+
+# Start the local development server
+fluid theme dev
+
+# Push your theme to Fluid
+fluid theme push
+```
+
+## Authentication
+
+Fluid CLI uses OAuth2 for authentication. Running `fluid login` will open your browser and redirect you to the Fluid authentication page. Once authenticated, your session is stored locally.
+
+```sh
+# Log in to your Fluid account
+fluid login
+
+# Log in to a specific company
+fluid login --company=my-store
+
+# Check who you're logged in as
+fluid whoami
+
+# Switch between companies
+fluid switch --company=another-store
+
+# Log out
+fluid logout
+```
+
+You can also authenticate via environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `FLUID_AUTH_TOKEN` | Bearer token for API authentication |
+| `FLUID_COMPANY` | Default company subdomain |
+
+## Commands
+
+### `fluid login`
+
+Authenticate with your Fluid account via the browser.
+
+| Flag | Description |
+|------|-------------|
+| `-c, --company=COMPANY` | Specify the company to log in to |
+
+### `fluid logout`
+
+Clear stored authentication tokens.
+
+### `fluid whoami`
+
+Display the currently authenticated company.
+
+### `fluid switch`
+
+Switch between companies on your account.
+
+| Flag | Description |
+|------|-------------|
+| `-c, --company=COMPANY` | Specify the company to switch to |
+
+### `fluid theme init`
+
+Initialize a new theme by cloning the base template into your current directory.
+
+| Flag | Description |
+|------|-------------|
+| `-u, --clone-url=URL` | Custom Git URL to clone from |
+
+### `fluid theme dev`
+
+Start a local development server with hot reload. The dev server proxies requests to your Fluid storefront and injects local theme files, enabling a fast development workflow.
+
+| Flag | Description |
+|------|-------------|
+| `--host=HOST` | Host to bind the dev server to |
+| `--port=PORT` | Port to bind the dev server to |
+| `--poll` | Use polling instead of filesystem events for file watching |
+| `--live-reload=MODE` | Reload mode: `full-page` or `hot-reload` |
+| `-t, --theme=THEME_ID` | Use a specific theme |
+| `-f, --force` | Force create a new development theme |
+| `--overwrite-json` | Overwrite remote JSON files with local versions |
+| `--navigate` | Open the interactive route/resource navigator |
+
+### `fluid theme push`
+
+Upload your local theme files to Fluid.
+
+| Flag | Description |
+|------|-------------|
+| `-n, --nodelete` | Don't delete remote files that are missing locally |
+| `-t, --theme=THEME_ID` | Push to a specific theme |
+| `-u, --unpublished` | Push to a new unpublished theme |
+| `-j, --json` | Include JSON settings files |
+| `-a, --allow-live` | Allow pushing to the live theme |
+| `-p, --publish` | Publish the theme after pushing |
+| `-f, --force` | Skip confirmation prompts |
+
+### `fluid theme pull`
+
+Download theme files from Fluid to your local directory.
+
+| Flag | Description |
+|------|-------------|
+| `-t, --theme=THEME_ID` | Pull from a specific theme |
+
+### `fluid theme navigate`
+
+Launch an interactive navigator to browse routes and resources for your storefront.
+
+| Flag | Description |
+|------|-------------|
+| `--host=HOST` | Host for the navigator server |
+| `--port=PORT` | Port for the navigator server |
+| `-t, --theme=THEME_ID` | Theme to navigate |
+
+## `.fluidignore`
+
+You can create a `.fluidignore` file in your theme's root directory to exclude files and directories from all theme operations (dev, push, pull, and file watching). The syntax is identical to `.gitignore`:
+
+```gitignore
+# Ignore node_modules
+node_modules/
+
+# Ignore all log files
+*.log
+
+# Ignore a specific directory
+tmp/
+
+# Negate a pattern (re-include a previously ignored file)
+!important.log
+```
+
+## Development
+
+After cloning the repository:
+
+```sh
+bundle install
+
+# Run the CLI locally
+bundle exec fluid
+
+# Run tests
+bundle exec rake test
+```
+
+## License
+
+This project is available under the [MIT License](LICENSE.txt).

data/lib/fluid_cli/commands/theme/dev.rb

@@ -24,6 +24,7 @@ module FluidCLI
           parser.on("-t", "--theme=NAME_OR_ID") { |theme| flags[:theme] = theme }
           parser.on("-f", "--force") { flags[:force] = true }
           parser.on("--overwrite-json") { flags[:overwrite_json] = true }
+          parser.on("--navigate") { flags[:navigate] = true }
         end
 
         def call(_args, name)

data/lib/fluid_cli/commands/theme/navigate.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "fluid_cli"
+
+module FluidCLI
+  module Commands
+    class Theme
+      class Navigate < FluidCLI::Command
+        DEFAULT_HTTP_HOST = "127.0.0.1"
+        DEFAULT_PORT = 9292
+
+        options do |parser, flags|
+          parser.on("--host=HOST") { |host| flags[:host] = host.to_s }
+          parser.on("--port=PORT") { |port| flags[:port] = port.to_i }
+          parser.on("-t", "--theme=NAME_OR_ID") { |theme| flags[:theme] = theme }
+        end
+
+        def call(_args, _name)
+          valid_authentication_method!
+
+          flags = options.flags.dup
+          host = flags[:host] || DEFAULT_HTTP_HOST
+          port = flags[:port] || DEFAULT_PORT
+          address = "http://#{host}:#{port}"
+
+          theme_id = resolve_theme_id(flags[:theme])
+
+          FluidCLI::Theme::Navigation::RouteNavigator.new(@ctx, address, theme_id).navigate
+        end
+
+        def self.help
+          "Interactively select a route and resource to navigate to in the theme dev server."
+        end
+
+        private
+
+        def valid_authentication_method!
+          if FluidCLI::Environment.auth_token.nil? && FluidCLI::DB.get(:jwt).nil?
+            FluidCLI::Context.abort("Auth token is missing", "Please login using 'fluid login' command.")
+          end
+        end
+
+        def resolve_theme_id(theme_identifier)
+          if theme_identifier
+            theme = FluidCLI::Theme::Theme.find_by_identifier(@ctx, root: ".", identifier: theme_identifier)
+            @ctx.abort("Theme not found: #{theme_identifier}") unless theme
+            theme.id
+          else
+            id = FluidCLI::DB.get(:development_theme_id)
+            @ctx.abort("No active development theme found. Run 'fluid theme dev' first, or specify a theme with --theme.") unless id
+            id
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fluid_cli/commands/theme/push.rb

@@ -22,7 +22,7 @@ module FluidCLI
           parser.on("-j", "--json") { flags[:json] = true }
           parser.on("-a", "--allow-live") { flags[:allow_live] = true }
           parser.on("-p", "--publish") { flags[:publish] = true }
-          # parser.on("-f", "--force") { flags[:force] = true }
+          parser.on("-f", "--force") { flags[:force] = true }
           # parser.on("--development-theme-id=DEVELOPMENT_THEME_ID") do |development_theme_id|
           #   flags[:development_theme_id] = development_theme_id.to_i
           # end
@@ -45,7 +45,7 @@ module FluidCLI
           #   return unless CLI::UI::Prompt.confirm(question)
           # end
 
-          syncer = FluidCLI::Theme::Syncer.new(@ctx, theme: theme)
+          syncer = FluidCLI::Theme::Syncer.new(@ctx, theme: theme, force: options.flags[:force])
           begin
             syncer.start_threads
             if options.flags[:json]

data/lib/fluid_cli/commands/theme.rb

@@ -3,10 +3,11 @@ require "fluid_cli"
 module FluidCLI
   module Commands
     class Theme < FluidCLI::Command
-      subcommand :Dev,  'dev',  'fluid_cli/commands/theme/dev'
-      subcommand :Init, 'init', 'fluid_cli/commands/theme/init'
-      subcommand :Pull, 'pull', 'fluid_cli/commands/theme/pull'
-      subcommand :Push, 'push', 'fluid_cli/commands/theme/push'
+      subcommand :Dev,      'dev',      'fluid_cli/commands/theme/dev'
+      subcommand :Init,     'init',     'fluid_cli/commands/theme/init'
+      subcommand :Navigate, 'navigate', 'fluid_cli/commands/theme/navigate'
+      subcommand :Pull,     'pull',     'fluid_cli/commands/theme/pull'
+      subcommand :Push,     'push',     'fluid_cli/commands/theme/push'
 
       def call(*args)
         self.class.help(*args)

data/lib/fluid_cli/file_system_listener.rb

@@ -6,11 +6,14 @@ module FluidCLI
   class FileSystemListener
     include Observable
 
-    def initialize(root:, force_poll:)
+    def initialize(root:, force_poll:, ignore_pattern: nil)
       @root = root
       @force_poll = force_poll
 
-      @listener = Listen.to(@root, force_polling: @force_poll) do |updated, added, removed|
+      listen_opts = { force_polling: @force_poll }
+      listen_opts[:ignore] = ignore_pattern if ignore_pattern
+
+      @listener = Listen.to(@root, **listen_opts) do |updated, added, removed|
         changed
         notify_observers(updated, added, removed)
       end

data/lib/fluid_cli/theme/dev_server/watcher.rb

@@ -15,7 +15,13 @@ module FluidCLI
           @ctx = ctx
           @theme = theme
           @syncer = syncer
-          @listener = FileSystemListener.new(root: @theme.root, force_poll: poll)
+
+          ignore_pattern = @theme.fluid_ignore.to_listen_regexp
+          @listener = FileSystemListener.new(
+            root: @theme.root,
+            force_poll: poll,
+            ignore_pattern: ignore_pattern
+          )
 
           add_observer(self, :upload_files_when_changed)
         end

data/lib/fluid_cli/theme/dev_server.rb

@@ -28,8 +28,8 @@ module FluidCLI
     class DevServer
       include Singleton
 
-      attr_reader :app, :stopped, :ctx, :root, :host, :theme_identifier, :port, :poll, :editor_sync, :mode,
-        :block, :includes, :ignores
+      attr_reader :app, :stopped, :ctx, :root, :host, :theme_identifier, :port, :poll, :editor_sync, :force, :mode,
+        :block, :includes, :ignores, :navigate
 
       class << self
         def start(
@@ -40,7 +40,9 @@ module FluidCLI
           port: 9292,
           poll: false,
           editor_sync: false,
+          force: false,
           overwrite_json: false,
+          navigate: false,
           mode: ReloadMode.default,
           includes: nil,
           ignores: nil,
@@ -54,7 +56,9 @@ module FluidCLI
             port,
             poll,
             editor_sync,
+            force,
             overwrite_json,
+            navigate,
             mode,
             includes,
             ignores,
@@ -77,7 +81,9 @@ module FluidCLI
         port,
         poll,
         editor_sync,
+        force,
         overwrite_json,
+        navigate,
         mode,
         includes,
         ignores,
@@ -90,7 +96,9 @@ module FluidCLI
         @port = port
         @poll = poll
         @editor_sync = editor_sync
+        @force = force
         @overwrite_json = overwrite_json
+        @navigate = navigate
         @mode = mode
         @includes = includes
         @ignores = ignores
@@ -175,10 +183,12 @@ module FluidCLI
           return if stopped
 
           ctx.puts(serving_theme_message)
-          
+
           ctx.puts(browser_open_message)
 
           ctx.puts(preview_message)
+
+          navigate_to_resource if @navigate
         end
       end
 
@@ -195,7 +205,8 @@ module FluidCLI
         @syncer ||= Syncer.new(
           ctx,
           theme: theme,
-          overwrite_json: !editor_sync || @overwrite_json
+          overwrite_json: !editor_sync || @overwrite_json,
+          force: @force
         )
       end
 
@@ -238,6 +249,10 @@ module FluidCLI
         @address ||= "http://#{host}:#{port}"
       end
 
+      def navigate_to_resource
+        FluidCLI::Theme::Navigation::RouteNavigator.new(ctx, address, theme.id).navigate
+      end
+
       # Messages
 
       def ensure_user_message

data/lib/fluid_cli/theme/file.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 require_relative "mime_type"
+require_relative "schema_validator"
 
 module FluidCLI
   module Theme
@@ -7,6 +8,11 @@ module FluidCLI
       attr_accessor :remote_checksum
       attr_writer :warnings
 
+      TEMPLATE_TYPES = %w[
+        product medium enrollment_pack shop_page library category_page collection_page cart_page
+        home_page join_page page collection post category post_page navbar footer
+      ].freeze
+
       def initialize(path, root)
         super(Pathname.new(path))
 
@@ -71,7 +77,7 @@ module FluidCLI
       end
 
       def template?
-        relative_path.start_with?("templates/")
+        TEMPLATE_TYPES.any? { |type| relative_path.start_with?(type) }
       end
 
       def checksum
@@ -100,6 +106,25 @@ module FluidCLI
       def warnings
         @warnings || []
       end
+
+      def validate_schema
+        return [] if !liquid?
+
+        FluidCLI::Theme::SchemaValidator
+        .new(self, blocks_schema_type: template? ? "object" : "array")
+        .validate
+      end
+
+      def validate_schema_and_raise
+        diags = validate_schema
+        return if diags.empty?
+
+        message = "Schema validation errors in #{relative_path}:\n"
+        diags.each do |diag|
+          message += "- [#{diag[:severity]}] #{diag[:message]}\n"
+        end
+        raise FluidCLI::Theme::SchemaValidationError, message
+      end
     end
   end
 end

data/lib/fluid_cli/theme/fluid_ignore.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module FluidCLI
+  module Theme
+    class FluidIgnore
+      IGNORE_FILE = ".fluidignore"
+
+      attr_reader :patterns
+
+      def initialize(root)
+        @root = root
+        @patterns = parse(ignore_file_path)
+      end
+
+      # Returns true if the given relative path should be ignored.
+      # Last matching pattern wins (supports negation with !).
+      def ignore?(relative_path)
+        relative_path = relative_path.to_s
+        result = false
+        @patterns.each do |negated, pattern|
+          if match?(pattern, relative_path)
+            result = !negated
+          end
+        end
+        result
+      end
+
+      # Returns a Regexp suitable for Listen.to(ignore: ...).
+      # Returns nil if there are no positive patterns.
+      def to_listen_regexp
+        positive_patterns = @patterns.reject(&:first).map(&:last)
+        return nil if positive_patterns.empty?
+
+        parts = positive_patterns.map { |pat| fnmatch_to_regex(pat) }
+        Regexp.new(parts.join("|"))
+      end
+
+      def any?
+        @patterns.any?
+      end
+
+      private
+
+      def ignore_file_path
+        ::File.join(@root.to_s, IGNORE_FILE)
+      end
+
+      def parse(path)
+        return [] unless ::File.exist?(path)
+
+        ::File.readlines(path, chomp: true).filter_map do |line|
+          line = line.strip
+          next if line.empty? || line.start_with?("#")
+
+          negated = line.start_with?("!")
+          line = line[1..] if negated
+
+          # Leading slash means relative to root — strip it for fnmatch
+          line = line[1..] if line.start_with?("/")
+
+          [negated, line]
+        end
+      end
+
+      def match?(pattern, path)
+        if pattern.end_with?("/")
+          # Directory pattern — match anything under this directory
+          path.start_with?(pattern) || path == pattern.chomp("/")
+        elsif pattern.include?("/")
+          # Path pattern — match against the full relative path
+          ::File.fnmatch(pattern, path, ::File::FNM_PATHNAME | ::File::FNM_DOTMATCH)
+        else
+          # Basename pattern — match against both full path and basename
+          ::File.fnmatch(pattern, path, ::File::FNM_PATHNAME | ::File::FNM_DOTMATCH) ||
+            ::File.fnmatch(pattern, ::File.basename(path), ::File::FNM_DOTMATCH)
+        end
+      end
+
+      def fnmatch_to_regex(pattern)
+        if pattern.end_with?("/")
+          # Directory pattern — match the directory and anything under it
+          Regexp.escape(pattern) + ".*"
+        else
+          re = Regexp.escape(pattern)
+          re.gsub("\\*\\*", "DOUBLE_STAR")
+            .gsub("\\*", "[^/]*")
+            .gsub("DOUBLE_STAR", ".*")
+            .gsub("\\?", "[^/]")
+        end
+      end
+    end
+  end
+end

data/lib/fluid_cli/theme/navigation/resource_fetcher.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FluidCLI
+  module Theme
+    module Navigation
+      class ResourceFetcher
+        def initialize(ctx, theme_id)
+          @ctx = ctx
+          @theme_id = theme_id
+        end
+
+        def fetch(themeable_type)
+          _status, body = FluidCLI::API.new(@ctx).get(
+            path: "application_themes/#{@theme_id}/available_themeables",
+            query: URI.encode_www_form(themeable: themeable_type, per_page: 50),
+          )
+          body["available_themeables"] || []
+        rescue FluidCLI::API::APIRequestError => e
+          @ctx.debug("Failed to fetch #{themeable_type} themeables: #{e.message}")
+          []
+        end
+      end
+    end
+  end
+end

data/lib/fluid_cli/theme/navigation/route_navigator.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module FluidCLI
+  module Theme
+    module Navigation
+      class RouteNavigator
+        STATIC_ROUTES = [
+          { label: "Home",              path: "/home" },
+          { label: "Shop",              path: "/home/shop" },
+          { label: "Join / Sign Up",    path: "/home/join" },
+          { label: "Cart",              path: "/cart" },
+          { label: "Blog",              path: "/home/blog" },
+          { label: "Categories (all)",  path: "/home/categories" },
+          { label: "Collections (all)", path: "/home/collections" },
+        ].freeze
+
+        RESOURCE_ROUTES = [
+          { label: "Category",        themeable_type: "category",        path_template: "/home/categories/%<id>s", fallback_path: "/home/categories" },
+          { label: "Collection",      themeable_type: "collection",      path_template: "/home/collections/%<id>s", fallback_path: "/home/collections" },
+          { label: "Product",         themeable_type: "product",         path_template: "/home/products/%<id>s",          fallback_path: "/home/shop" },
+          { label: "Library",         themeable_type: "library",         path_template: "/home/libraries/%<id>s",         fallback_path: "/home/libraries" },
+          { label: "Post",            themeable_type: "post",            path_template: "/home/posts/%<id>s",             fallback_path: "/home/blog" },
+          { label: "Media",           themeable_type: "medium",          path_template: "/home/media/%<id>s",             fallback_path: "/home/media" },
+          { label: "Enrollment Pack", themeable_type: "enrollment_pack", path_template: "/home/enrollments/%<id>s",  fallback_path: "/home/join" },
+        ].freeze
+
+        def initialize(ctx, address, theme_id)
+          @ctx = ctx
+          @address = address
+          @theme_id = theme_id
+        end
+
+        def navigate
+          path = select_destination
+          return unless path
+
+          url = "#{@address}#{path}"
+          @ctx.puts("\n{{bold:Navigate to: {{green:#{url}}}}}\n")
+          open_browser(url)
+        rescue => e
+          @ctx.debug("Navigation error: #{e.message}")
+        end
+
+        private
+
+        def select_destination
+          all_options = STATIC_ROUTES.map { |r| [:static, r] } + RESOURCE_ROUTES.map { |r| [:resource, r] }
+          type, data = CLI::UI::Prompt.ask("Select a route to navigate to") do |handler|
+            all_options.each { |t, r| handler.option(option_label(t, r)) { [t, r] } }
+          end
+          type == :static ? data[:path] : resolve_resource_path(data)
+        end
+
+        def option_label(type, data)
+          type == :static ? data[:label] : "#{data[:label]} (select specific)"
+        end
+
+        def resolve_resource_path(route)
+          resources = ResourceFetcher.new(@ctx, @theme_id).fetch(route[:themeable_type])
+
+          if resources.empty?
+            @ctx.puts("{{yellow:No #{route[:label].downcase} resources found, navigating to listing page.}}")
+            return route[:fallback_path]
+          end
+
+          resource = CLI::UI::Prompt.ask("Select a #{route[:label].downcase}") do |handler|
+            resources.each { |r| handler.option(display_name(r)) { r } }
+          end
+
+          format(route[:path_template], id: resource["slug"])
+        end
+
+        def display_name(resource)
+          resource["title"] || resource["id"].to_s
+        end
+
+        def open_browser(url)
+          case RbConfig::CONFIG["host_os"]
+          when /darwin/             then system("open", url)
+          when /linux/              then system("xdg-open", url)
+          when /mswin|mingw|cygwin/ then system("start", "", url)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fluid_cli/theme/root.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 require_relative "file"
+require_relative "fluid_ignore"
 require "pathname"
 
 module FluidCLI
@@ -24,11 +25,16 @@ module FluidCLI
         glob("**/*.json")
       end
 
+      def fluid_ignore
+        @fluid_ignore ||= FluidIgnore.new(root)
+      end
+
       def glob(pattern, raise_on_dir: false)
         root
           .glob(pattern)
           .select { |path| file?(path, raise_on_dir) }
           .map { |path| File.new(path, root) }
+          .reject { |file| fluid_ignore.ignore?(file.relative_path) }
       end
 
       def static_asset_file?(file)

data/lib/fluid_cli/theme/schema_validator.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FluidCLI
+  module Theme
+
+    class SchemaValidator
+      Diagnostic = Struct.new(:severity, :message, keyword_init: true)
+
+      VALID_SETTING_TYPES = %w[
+        text rich_text richtext textarea range select checkbox color text_alignment
+        color_background radio url image image_picker video_picker font_picker html
+        html_textarea link_list header blog posts posts_list products products_list
+        product product_list forms collections collections_list collection
+        collection_list categories categories_list category category_list enrollments
+        enrollments_list enrollment_pack enrollment enrollment_list
+      ].freeze
+
+      def initialize(file, blocks_schema_type: "unknown")
+        @file = file
+        @blocks_schema_type = blocks_schema_type
+      end
+
+      def validate
+        text = @file.read.to_s
+        diagnostics = []
+
+        match = text.match(/{% schema %}([\s\S]*?){% endschema %}/)
+
+        return diagnostics.map(&:to_h) unless match
+
+        json_text = match[1] || ""
+
+        schema = nil
+        begin
+          schema = JSON.parse(json_text)
+        rescue JSON::ParserError => e
+          diagnostics << Diagnostic.new(severity: "error", message: "Invalid JSON:\n #{e.message}")
+          return diagnostics.map(&:to_h)
+        end
+
+        scan = JsonTokenScan.scan(json_text)
+
+        scan.duplicate_blocks_key_tokens.each do
+          diagnostics << Diagnostic.new(
+            severity: "error",
+            message: "Error in blocks: duplicate 'blocks' key in the same object"
+          )
+        end
+
+        if schema.is_a?(Hash) && schema["settings"].is_a?(Array)
+          diagnostics.concat(validate_settings(schema["settings"]))
+        end
+
+        if @blocks_schema_type == "object" && !schema["blocks"].is_a?(Hash)
+          scan.blocks_array_value_tokens.each do
+            diagnostics << Diagnostic.new(
+              severity: "error",
+              message: "Error in blocks: expected an object ({})"
+            )
+          end
+        end
+
+        if schema.is_a?(Hash) && schema.key?("blocks")
+          blocks = schema["blocks"]
+
+          case @blocks_schema_type
+          when "array"
+            if !blocks.is_a?(Array)
+              diagnostics << Diagnostic.new(
+                severity: "error",
+                message: "Error in blocks: expected an array ([])"
+              )
+            else
+              diagnostics.concat(validate_blocks(blocks))
+            end
+          when "object"
+            unless blocks.is_a?(Hash)
+              diagnostics << Diagnostic.new(
+                severity: "error",
+                message: "Error in blocks: expected an object ({})"
+              )
+            end
+          else # "unknown"
+            diagnostics.concat(validate_blocks(blocks)) if blocks.is_a?(Array)
+          end
+        end
+
+        diagnostics.map(&:to_h)
+      end
+
+      private
+
+      def validate_settings(settings)
+        diagnostics = []
+        ids = {}
+
+        settings.each_with_index do |setting, index|
+          setting ||= {}
+          setting = {} unless setting.is_a?(Hash)
+
+          id = setting["id"]
+          type = setting["type"]
+
+          if id.is_a?(String) && id.strip.empty?
+            diagnostics << Diagnostic.new(
+              severity: "error",
+              message: "Error in settings: id cannot be empty"
+            )
+          elsif id && ids.key?(id)
+            diagnostics << Diagnostic.new(
+              severity: "error",
+              message: "Error in settings: duplicate id '#{id}' found"
+            )
+          elsif id
+            ids[id] = true
+          end
+
+          if !type
+            diagnostics << Diagnostic.new(
+              severity: "error",
+              message: "Error in setting '#{id || index}': missing required field 'type'"
+            )
+          elsif !VALID_SETTING_TYPES.include?(type)
+            diagnostics << Diagnostic.new(
+              severity: "error",
+              message: "Invalid settings type: '#{type}'"
+            )
+          end
+        end
+
+        diagnostics
+      end
+
+      def validate_blocks(blocks)
+        diagnostics = []
+        types = {}
+
+        blocks.each_with_index do |block, index|
+          block ||= {}
+          block = {} unless block.is_a?(Hash)
+
+          type = block["type"]
+          name = block["name"]
+
+          if !type
+            diagnostics << Diagnostic.new(
+              severity: "error",
+              message: "Error in blocks at index #{index}: missing required field 'type'"
+            )
+          elsif types.key?(type)
+            diagnostics << Diagnostic.new(
+              severity: "warning",
+              message: "Warning in blocks: duplicate type '#{type}' found"
+            )
+          else
+            types[type] = true
+          end
+
+          if !name
+            diagnostics << Diagnostic.new(
+              severity: "error",
+              message: "Error in block '#{type || index}': missing required field 'name'"
+            )
+          end
+
+          if block["settings"].is_a?(Array)
+            diagnostics.concat(validate_settings(block["settings"]))
+          end
+        end
+
+        diagnostics
+      end
+
+      # Minimal token scanner:
+      # - detects duplicate "blocks" keys inside the same object
+      # - detects when "blocks" value starts with an array ([)
+      class JsonTokenScan
+        Token = Struct.new(:value)
+
+        attr_reader :duplicate_blocks_key_tokens, :blocks_array_value_tokens
+
+        def initialize
+          @duplicate_blocks_key_tokens = []
+          @blocks_array_value_tokens = []
+        end
+
+        def self.scan(json_text)
+          new.tap { |s| s.scan!(json_text) }
+        end
+
+        def scan!(s)
+          stack = []
+          pending_key = nil
+          i = 0
+
+          while i < s.length
+            ch = s.getbyte(i)
+
+            if whitespace?(ch)
+              i += 1
+              next
+            end
+
+            case ch
+            when 0x7B # {
+              stack << { type: :object, keys: {}, expecting_key: true }
+              pending_key = nil
+              i += 1
+            when 0x7D # }
+              stack.pop
+              pending_key = nil
+              i += 1
+            when 0x5B # [
+              if pending_key == "blocks"
+                @blocks_array_value_tokens << Token.new("blocks-array")
+              end
+              pending_key = nil
+              stack << { type: :array }
+              i += 1
+            when 0x5D # ]
+              stack.pop
+              pending_key = nil
+              i += 1
+            when 0x3A # :
+              # after colon, we are reading a value next
+              i += 1
+            when 0x2C # ,
+              if stack.last&.dig(:type) == :object
+                stack.last[:expecting_key] = true
+              end
+              pending_key = nil
+              i += 1
+            when 0x22 # "
+              str, i = read_string(s, i)
+
+              if stack.last&.dig(:type) == :object && stack.last[:expecting_key]
+                # this string is a key
+                if str == "blocks" && stack.last[:keys][str]
+                  @duplicate_blocks_key_tokens << Token.new(str)
+                end
+                stack.last[:keys][str] = true
+                stack.last[:expecting_key] = false
+                pending_key = str
+              else
+                pending_key = nil
+              end
+            else
+              # literals / numbers / etc.
+              pending_key = nil
+              i += 1
+            end
+          end
+        end
+
+        def read_string(s, start)
+          i = start + 1
+          while i < s.length
+            break if s.getbyte(i) == 0x22 && s.getbyte(i - 1) != 0x5C
+            i += 1
+          end
+          [s[start + 1...i], i + 1]
+        end
+
+        def whitespace?(ch)
+          ch == 0x20 || ch == 0x0A || ch == 0x0D || ch == 0x09
+        end
+      end
+    end
+
+    class SchemaValidationError < StandardError; end
+  end
+end

data/lib/fluid_cli/theme/syncer.rb

@@ -31,10 +31,11 @@ module FluidCLI
 
       def_delegators :@error_reporter, :has_any_error?
 
-      def initialize(ctx, theme:, overwrite_json: true)
+      def initialize(ctx, theme:, overwrite_json: true, force: false)
         @ctx = ctx
         @theme = theme
         @overwrite_json = overwrite_json
+        @force = force
         @error_reporter = ErrorReporter.new(ctx)
         @standard_reporter = StandardReporter.new(ctx)
         @reporters = [@error_reporter, @standard_reporter]
@@ -230,12 +231,15 @@ module FluidCLI
           else
             JSON.parse(response&.body)
           end
-        end
-
-        errors = parsed_body.dig("errors") # either nil or another type
-        errors = errors.dig("asset") if errors&.is_a?(Hash)
+          errors = parsed_body.dig("errors") # either nil or another type
+          errors = errors.dig("asset") if errors&.is_a?(Hash)
 
-        ["#{parsed_body['error_message']}\n#{errors}"]
+          ["#{parsed_body['error_message']}\n#{errors}"]
+        elsif exception.respond_to?(:message)
+          [exception.message]
+        else
+          ["An unknown error occurred while syncing the asset #{file}"]
+        end
       rescue JSON::ParserError
         [exception.message]
       rescue StandardError => e
@@ -310,6 +314,10 @@ module FluidCLI
         path = "application_themes/#{@theme.id}/resources"
         
         if file.text?
+          if file.liquid? && !@force
+            file.validate_schema_and_raise
+          end
+
           application_theme_resource[:content] = file.read
             _status, body, response = api_client.put(
             path: path,

data/lib/fluid_cli/version.rb

@@ -1,3 +1,3 @@
 module FluidCLI
-  VERSION = "0.1.8"
+  VERSION = "0.2.0"
 end

data/lib/fluid_cli.rb

@@ -32,6 +32,11 @@ module FluidCLI
     module UI
       autoload(:SyncProgressBar, 'fluid_cli/theme/ui/sync_progress_bar')
     end
+
+    module Navigation
+      autoload(:RouteNavigator, 'fluid_cli/theme/navigation/route_navigator')
+      autoload(:ResourceFetcher, 'fluid_cli/theme/navigation/resource_fetcher')
+    end
   end
 
   def self.cache_dir

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fluid_cli
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.0
 platform: ruby
 authors:
 - Fluid
 bindir: exe
 cert_chain: []
-date: 2026-01-28 00:00:00.000000000 Z
+date: 2026-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bugsnag
@@ -105,6 +105,7 @@ files:
 - lib/fluid_cli/commands/theme/dev.rb
 - lib/fluid_cli/commands/theme/help.rb
 - lib/fluid_cli/commands/theme/init.rb
+- lib/fluid_cli/commands/theme/navigate.rb
 - lib/fluid_cli/commands/theme/pull.rb
 - lib/fluid_cli/commands/theme/push.rb
 - lib/fluid_cli/commands/whoami.rb
@@ -141,11 +142,15 @@ files:
 - lib/fluid_cli/theme/dev_server/web_server.rb
 - lib/fluid_cli/theme/development_theme.rb
 - lib/fluid_cli/theme/file.rb
+- lib/fluid_cli/theme/fluid_ignore.rb
 - lib/fluid_cli/theme/forms/select.rb
 - lib/fluid_cli/theme/mime_type.rb
+- lib/fluid_cli/theme/navigation/resource_fetcher.rb
+- lib/fluid_cli/theme/navigation/route_navigator.rb
 - lib/fluid_cli/theme/presenters/theme_presenter.rb
 - lib/fluid_cli/theme/presenters/themes_presenter.rb
 - lib/fluid_cli/theme/root.rb
+- lib/fluid_cli/theme/schema_validator.rb
 - lib/fluid_cli/theme/syncer.rb
 - lib/fluid_cli/theme/syncer/checksums.rb
 - lib/fluid_cli/theme/syncer/downloader.rb