boreal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d5546aed483aa7a5dbee66b8e8acf78047fc38e7d0f435260935531361b9232a
+  data.tar.gz: 8ee439a58d722f3c63db99b3ee19abdb92395924f11be5b7a5859935be3e1c9d
+SHA512:
+  metadata.gz: a95e738c9dd6129520217fea2d58082ce7e8ff228dd296fcdf831111617013f8ea1b1b5e4e4085e2e76f5ca626e32df677298c7ec29f0b153910b9c2150ace73
+  data.tar.gz: 2eed82022fe83149f534081d22fbb5b158e2cb5f453aad7c57cafb975a152f9d138474ffd7884cd6d7960dc979d3dfd143f045790e24d8e2be300bcc67c38589

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,170 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy thereof.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 The Pleme Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/Rakefile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/boreal.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'boreal/version'
+
+Gem::Specification.new do |spec|
+  spec.name                  = 'boreal'
+  spec.version               = Boreal::VERSION
+  spec.authors               = ['Luis Zayas']
+  spec.email                 = ['drzthslnt@gmail.com']
+  spec.summary               = 'Nord-themed CLI look-and-feel for Ruby'
+  spec.description           = 'True 24-bit Nord palette theming for CLI tools. Wraps TTY components (box, table, spinner, progress) with unified Nord styling via the Paint gem.'
+  spec.homepage              = 'https://github.com/pleme-io/boreal'
+  spec.license               = 'Apache-2.0'
+  spec.require_paths         = ['lib']
+  spec.required_ruby_version = '>= 3.3.0'
+
+  spec.files = Dir['lib/**/*.rb'] + %w[boreal.gemspec Gemfile LICENSE Rakefile]
+
+  # Core — true 24-bit color
+  spec.add_dependency 'paint', '~> 2.3'
+
+  # TTY components (the gem's value is pre-themed wrappers)
+  spec.add_dependency 'tty-box', '~> 0.7'
+  spec.add_dependency 'tty-table', '~> 0.12'
+  spec.add_dependency 'tty-spinner', '~> 0.9'
+  spec.add_dependency 'tty-progressbar', '~> 0.18'
+
+  # Compat layer (TTY internals use Pastel for style: hashes)
+  spec.add_dependency 'pastel', '~> 0.8'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/boreal/compat.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'pastel'
+
+module Boreal
+  # Compatibility bridge between Boreal roles and Pastel symbols.
+  #
+  # Two purposes:
+  # 1. Map Boreal semantic roles to the closest Pastel symbol for TTY gems
+  #    that accept symbol-based `style:` hashes (TTY::Box, TTY::Logger).
+  # 2. Map raw Pastel symbols (`:bright_cyan`, `:green`) to Nord hex values
+  #    for callers migrating incrementally.
+  module Compat
+    # Boreal role → closest Pastel symbol (for TTY style: hashes)
+    PASTEL_MAP = {
+      success:   :green,
+      error:     :red,
+      warning:   :yellow,
+      info:      :blue,
+      debug:     :bright_black,
+      create:    :green,
+      update:    :yellow,
+      delete:    :red,
+      replace:   :magenta,
+      import:    :blue,
+      refresh:   :cyan,
+      primary:   :cyan,
+      secondary: :blue,
+      muted:     :bright_black,
+      text:      :white,
+      bright:    :bright_white,
+      border:    :cyan,
+      separator: :bright_black,
+      added:     :green,
+      removed:   :red,
+      changed:   :yellow,
+      pending:   :cyan
+    }.freeze
+
+    # Pastel symbol → Nord hex (for incremental migration)
+    HEX_MAP = {
+      green:          Palette::GREEN,
+      bright_green:   Palette::GREEN,
+      red:            Palette::RED,
+      bright_red:     Palette::RED,
+      yellow:         Palette::YELLOW,
+      bright_yellow:  Palette::YELLOW,
+      blue:           Palette::FROST2,
+      bright_blue:    Palette::FROST2,
+      cyan:           Palette::FROST1,
+      bright_cyan:    Palette::FROST1,
+      magenta:        Palette::PURPLE,
+      bright_magenta: Palette::PURPLE,
+      white:          Palette::SNOW0,
+      bright_white:   Palette::SNOW2,
+      black:          Palette::NIGHT0,
+      bright_black:   Palette::NIGHT3
+    }.freeze
+
+    class << self
+      # Return the Pastel symbol for a Boreal role.
+      def pastel_sym(role)
+        PASTEL_MAP.fetch(role) { raise ArgumentError, "No Pastel mapping for role: #{role}" }
+      end
+
+      # Return the Nord hex for a Pastel symbol, or nil if unknown.
+      def hex_for(pastel_sym)
+        HEX_MAP[pastel_sym]
+      end
+
+      # Build a Pastel-compatible color hash for TTY::Box `style: { border: { color: } }`.
+      def border_style(role = :border)
+        { color: pastel_sym(role) }
+      end
+
+      # Return a shared Pastel instance for TTY internals that require one.
+      # Consumers should prefer Boreal.paint over this.
+      def pastel
+        @pastel ||= Pastel.new
+      end
+    end
+  end
+end

data/lib/boreal/components/banner.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'tty-box'
+
+module Boreal
+  module Components
+    # ASCII art framing with Nord-themed borders and colors.
+    class Banner
+      include Base
+
+      # Render framed ASCII art with Nord border characters.
+      def art(content, width: 70, align: :center)
+        TTY::Box.frame(
+          content,
+          width: width,
+          align: align,
+          border: :thick,
+          style: { border: border_chars(:primary) }
+        )
+      end
+
+      # Compact command header line.
+      def header(title, subtitle: nil)
+        line = paint(title, :primary)
+        line += " #{paint(subtitle, :muted)}" if subtitle
+        separator = paint('─' * 50, :muted)
+        "#{line}\n#{separator}"
+      end
+
+      # Full-width section divider.
+      def divider(width: 60, role: :primary)
+        paint('━' * width, role)
+      end
+
+      # Success banner with dividers.
+      def success_banner(message, width: 60)
+        d = divider(width: width, role: :success)
+        text = bold("#{icon(:success)} #{message}", :success)
+        "\n#{d}\n#{text}\n#{d}\n"
+      end
+
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        %i[art header divider success_banner].each do |method|
+          define_method(method) { |*args, **kwargs| instance.send(method, *args, **kwargs) }
+        end
+      end
+    end
+  end
+end

data/lib/boreal/components/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Boreal
+  module Components
+    # Shared behavior for all themed components.
+    module Base
+      private
+
+      def paint(text, role_or_hex)
+        Renderer.paint(text, role_or_hex)
+      end
+
+      def bold(text, role_or_hex = nil)
+        Renderer.bold(text, role_or_hex)
+      end
+
+      def icon(role)
+        Renderer.icon(role)
+      end
+
+      def border_chars(role = :border)
+        hex = role.is_a?(Symbol) ? Theme.hex(role) : role
+        {
+          top:          Paint['─', hex],
+          bottom:       Paint['─', hex],
+          left:         Paint['│', hex],
+          right:        Paint['│', hex],
+          top_left:     Paint['╭', hex],
+          top_right:    Paint['╮', hex],
+          bottom_left:  Paint['╰', hex],
+          bottom_right: Paint['╯', hex]
+        }
+      end
+    end
+  end
+end

data/lib/boreal/components/box.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'tty-box'
+
+module Boreal
+  module Components
+    # TTY::Box wrapper with Nord-themed borders and convenience methods.
+    class Box
+      include Base
+
+      # Render a framed box with painted Nord border characters.
+      def frame(content, width: 60, align: :left, role: :border, border: :light, title: nil, padding: 1)
+        options = {
+          width: width,
+          align: align,
+          border: border,
+          padding: padding,
+          style: { border: border_chars(role) }
+        }
+        options[:title] = { top_left: title } if title
+
+        TTY::Box.frame(content.to_s.strip, **options)
+      end
+
+      # Pre-themed status boxes
+      def success(title, details = nil)
+        content = "#{paint('✅', :success)} #{paint(title, :success)}"
+        content += "\n#{paint(details, :muted)}" if details
+        frame(content, role: :success, width: [title.to_s.length + 16, 60].max)
+      end
+
+      def error(title, details = nil, suggestions: [])
+        content = "#{paint('❌', :error)} #{paint(title, :error)}"
+        content += "\n\n#{paint(details, :text)}" if details
+
+        if suggestions.any?
+          content += "\n\n#{bold('💡 Suggestions:', :warning)}"
+          suggestions.each { |s| content += "\n  #{paint('•', :warning)} #{paint(s, :text)}" }
+        end
+
+        frame(content, role: :error, width: 70, border: :thick)
+      end
+
+      def warning(title, details = nil)
+        content = "#{paint('⚠️', :warning)} #{paint(title, :warning)}"
+        content += "\n#{paint(details, :text)}" if details
+        frame(content, role: :warning, width: [title.to_s.length + 16, 60].max)
+      end
+
+      def info(title, items = {})
+        content = "#{paint("ℹ️  #{title}", :primary)}\n\n"
+        items.each { |k, v| content += "#{bold(k.to_s.ljust(15), :bright)}: #{paint(v, :text)}\n" }
+        frame(content, role: :primary, width: 70)
+      end
+
+      # Class-level convenience
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        %i[frame success error warning info].each do |method|
+          define_method(method) { |*args, **kwargs| instance.send(method, *args, **kwargs) }
+        end
+      end
+    end
+  end
+end

data/lib/boreal/components/logger.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Boreal
+  module Components
+    # Structured log output with Nord role colors.
+    class Logger
+      include Base
+
+      # Log styles compatible with TTY::Logger (uses Pastel symbols).
+      LOG_STYLES = {
+        info:    { symbol: 'ℹ',  label: 'info',    color: Compat::PASTEL_MAP[:info],    levelpad: 1 },
+        success: { symbol: '✓', label: 'success', color: Compat::PASTEL_MAP[:success], levelpad: 0 },
+        error:   { symbol: '✗', label: 'error',   color: Compat::PASTEL_MAP[:error],   levelpad: 1 },
+        warn:    { symbol: '⚠',  label: 'warning', color: Compat::PASTEL_MAP[:warning], levelpad: 0 },
+        debug:   { symbol: '•', label: 'debug',   color: Compat::PASTEL_MAP[:debug],   levelpad: 1 }
+      }.freeze
+
+      # Action styles for resource operations.
+      ACTION_STYLES = {
+        create:  { symbol: '◉', role: :create },
+        update:  { symbol: '◎', role: :update },
+        delete:  { symbol: '◯', role: :delete },
+        replace: { symbol: '⧗', role: :replace },
+        import:  { symbol: '⬇', role: :import },
+        refresh: { symbol: '↻', role: :refresh },
+        default: { symbol: '●', role: :text }
+      }.freeze
+
+      STATUS_INDICATORS = {
+        success: ' ✓',
+        error:   ' ✗',
+        warning: ' ⚠',
+        pending: ' ⧖'
+      }.freeze
+
+      TEMPLATE_ICONS = {
+        compiling:  '⚙️',
+        compiled:   '✅',
+        failed:     '❌',
+        validating: '🔍',
+        validated:  '✅',
+        default:    '📄'
+      }.freeze
+
+      class << self
+        def log_styles
+          LOG_STYLES
+        end
+
+        def action_styles
+          ACTION_STYLES
+        end
+
+        def status_indicators
+          STATUS_INDICATORS
+        end
+
+        def template_icons
+          TEMPLATE_ICONS
+        end
+      end
+    end
+  end
+end

data/lib/boreal/components/progress.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'tty-progressbar'
+
+module Boreal
+  module Components
+    # TTY::ProgressBar wrapper with Nord-themed bar characters.
+    class Progress
+      include Base
+
+      def single(title, total:)
+        bar = create_bar(title, total)
+        begin
+          yield(bar)
+        ensure
+          bar.finish
+        end
+      end
+
+      def multi(title, &block)
+        TTY::ProgressBar::Multi.new(title, &block)
+      end
+
+      def transfer(title, total_bytes:)
+        TTY::ProgressBar.new(
+          "#{title} [:bar] :percent :current_byte/:total_byte :rate/s :eta",
+          total: total_bytes,
+          bar_format: :block,
+          clear: true,
+          width: 30
+        )
+      end
+
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        %i[single multi transfer].each do |method|
+          define_method(method) { |*args, **kwargs, &block| instance.send(method, *args, **kwargs, &block) }
+        end
+      end
+
+      private
+
+      def create_bar(title, total)
+        TTY::ProgressBar.new(
+          "#{title} [:bar] :percent :current/:total :elapsed",
+          total: total,
+          bar_format: :block,
+          clear: true,
+          width: 30,
+          complete: paint('█', :success),
+          incomplete: paint('░', :muted),
+          head: paint('█', :update)
+        )
+      end
+    end
+  end
+end

data/lib/boreal/components/spinner.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'tty-spinner'
+
+module Boreal
+  module Components
+    # TTY::Spinner wrapper with Nord-themed marks and colors.
+    class Spinner
+      include Base
+
+      def initialize(message = nil, format: :dots, clear: false, interval: 10)
+        spinner_format = "[:spinner] #{paint(message, :text)}"
+
+        @spinner = TTY::Spinner.new(
+          spinner_format,
+          format: format,
+          hide_cursor: true,
+          success_mark: paint('✅', :success),
+          error_mark: paint('❌', :error),
+          clear: clear,
+          interval: interval
+        )
+        @start_time = nil
+      end
+
+      def start
+        @start_time = Time.now
+        @spinner.start
+      end
+
+      def stop
+        @spinner.stop
+      end
+
+      def success(message = nil)
+        formatted = if message && @start_time
+                      duration = Time.now - @start_time
+                      "#{paint(message, :success)} #{paint("(#{format_duration(duration)})", :muted)}"
+                    else
+                      message
+                    end
+        @spinner.success(formatted)
+      end
+
+      def error(message = nil)
+        @spinner.error(message ? paint(message, :error) : nil)
+      end
+
+      def warning(message = nil)
+        @spinner.success("⚠️  #{message ? paint(message, :warning) : nil}")
+      end
+
+      def update(message)
+        @spinner.update(title: "[:spinner] #{paint(message, :text)}")
+      end
+
+      def spin
+        start
+        result = yield
+        success
+        result
+      rescue StandardError => e
+        error(e.message)
+        raise
+      ensure
+        stop
+      end
+
+      private
+
+      def format_duration(seconds)
+        case seconds
+        when 0...1 then "#{(seconds * 1000).round}ms"
+        when 1...60 then "#{seconds.round(1)}s"
+        else
+          minutes, remaining = seconds.divmod(60)
+          "#{minutes.floor}m #{remaining.round}s"
+        end
+      end
+    end
+  end
+end

data/lib/boreal/components/table.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'tty-table'
+
+module Boreal
+  module Components
+    # TTY::Table wrapper with Nord-themed borders and header colors.
+    class Table
+      include Base
+
+      BORDER_CHARS = %w[─ ─ │ │ ┌ ┐ └ ┘ ┬ ─ ├ ┤ ┼ ┴].freeze
+      BORDER_SYMS  = %i[top bottom left right top_left top_right bottom_left bottom_right
+                        top_mid mid mid_left mid_right mid_mid bottom_mid].freeze
+
+      def initialize(headers = nil, rows = [], **options)
+        @headers = headers
+        @rows = rows
+        @options = default_options.merge(options)
+      end
+
+      def render
+        colored_headers = @headers&.map { |h| bold(h, :bright) }
+        table = TTY::Table.new(colored_headers, @rows)
+        table.render(:unicode, **@options)
+      end
+
+      def add_row(row)
+        @rows << row
+      end
+
+      def to_s
+        render
+      end
+
+      class << self
+        def render_table(headers:, rows:)
+          new(headers, rows).render
+        end
+
+        def simple(headers, rows, title: nil)
+          result = render_table(headers: headers, rows: rows)
+          if title
+            title_line = Renderer.paint(title, :primary)
+            separator  = Renderer.paint('─' * title.length, :primary)
+            result = "#{title_line}\n#{separator}\n#{result}"
+          end
+          result
+        end
+      end
+
+      private
+
+      def default_options
+        painted_border = BORDER_SYMS.zip(
+          BORDER_CHARS.map { |c| paint(c, :border) }
+        ).to_h
+
+        {
+          padding: [0, 1],
+          resize: true,
+          multiline: true,
+          style: { border: painted_border }
+        }
+      end
+    end
+  end
+end

data/lib/boreal/palette.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Boreal
+  # The canonical Nord 16-color palette.
+  # Source: arcticicestudio/nord — https://www.nordtheme.com
+  module Palette
+    # Polar Night — dark backgrounds and surfaces
+    NIGHT0 = '#2E3440'
+    NIGHT1 = '#3B4252'
+    NIGHT2 = '#434C5E'
+    NIGHT3 = '#4C566A'
+
+    # Snow Storm — light text and foregrounds
+    SNOW0 = '#D8DEE9'
+    SNOW1 = '#E5E9F0'
+    SNOW2 = '#ECEFF4'
+
+    # Frost — blue accents
+    FROST0 = '#8FBCBB'
+    FROST1 = '#88C0D0'
+    FROST2 = '#81A1C1'
+    FROST3 = '#5E81AC'
+
+    # Aurora — status and action colors
+    RED    = '#BF616A'
+    ORANGE = '#D08770'
+    YELLOW = '#EBCB8B'
+    GREEN  = '#A3BE8C'
+    PURPLE = '#B48EAD'
+
+    # All colors as a frozen hash for iteration
+    ALL = {
+      night0: NIGHT0, night1: NIGHT1, night2: NIGHT2, night3: NIGHT3,
+      snow0: SNOW0, snow1: SNOW1, snow2: SNOW2,
+      frost0: FROST0, frost1: FROST1, frost2: FROST2, frost3: FROST3,
+      red: RED, orange: ORANGE, yellow: YELLOW, green: GREEN, purple: PURPLE
+    }.freeze
+  end
+end

data/lib/boreal/renderer.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'paint'
+
+module Boreal
+  # Paint-based true-color text rendering engine.
+  # Replaces Pastel for all user-visible text coloring.
+  module Renderer
+    module_function
+
+    # Paint text using a semantic role or raw hex color.
+    #
+    #   Boreal::Renderer.paint("ok", :success)   # => green bold
+    #   Boreal::Renderer.paint("ok", '#88C0D0')  # => raw hex
+    def paint(text, role_or_hex)
+      return text.to_s unless Terminal.color_enabled?
+
+      if role_or_hex.is_a?(Symbol)
+        paint_role(text, role_or_hex)
+      else
+        Paint[text.to_s, role_or_hex]
+      end
+    end
+
+    # Paint with explicit hex color.
+    def hex(text, hex_color)
+      return text.to_s unless Terminal.color_enabled?
+
+      Paint[text.to_s, hex_color]
+    end
+
+    # Paint with bold + role color (ignores role's default styles).
+    def bold(text, role_or_hex = nil)
+      return text.to_s unless Terminal.color_enabled?
+
+      if role_or_hex
+        color = role_or_hex.is_a?(Symbol) ? Theme.hex(role_or_hex) : role_or_hex
+        Paint[text.to_s, color, :bold]
+      else
+        Paint[text.to_s, :bold]
+      end
+    end
+
+    # Return the icon string for a role.
+    def icon(role)
+      Theme.icon(role) || ''
+    end
+
+    # Render "icon text" in the role's color.
+    def status(role, text)
+      ic = icon(role)
+      prefix = ic.empty? ? '' : "#{ic} "
+      paint("#{prefix}#{text}", role)
+    end
+
+    # Decorate text with a Pastel-compatible symbol (for TTY internals).
+    # Falls back to Paint hex when possible.
+    def decorate(text, color_sym)
+      return text.to_s unless Terminal.color_enabled?
+
+      if Theme::ROLES.key?(color_sym)
+        paint(text, color_sym)
+      else
+        # Pastel symbol — use Compat mapping
+        mapped_hex = Compat.hex_for(color_sym)
+        mapped_hex ? Paint[text.to_s, mapped_hex] : Paint[text.to_s, color_sym]
+      end
+    end
+
+    # --- private helpers ---
+
+    def paint_role(text, role)
+      r = Theme.role(role)
+      args = [text.to_s, r.hex, *r.styles]
+      Paint[*args]
+    end
+    private_class_method :paint_role
+  end
+end

data/lib/boreal/terminal.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Boreal
+  # TTY capability detection: true color, NO_COLOR, CI environments.
+  module Terminal
+    module_function
+
+    def true_color?
+      return false if no_color?
+
+      colorterm = ENV['COLORTERM'].to_s.downcase
+      return true if colorterm == 'truecolor' || colorterm == '24bit'
+
+      term = ENV['TERM'].to_s
+      return true if term.include?('24bit') || term.include?('truecolor')
+
+      # Most modern terminals support true color even without advertising it
+      term_program = ENV['TERM_PROGRAM'].to_s
+      %w[iTerm.app WezTerm Hyper vscode kitty alacritty ghostty].any? { |t| term_program.include?(t) }
+    end
+
+    def no_color?
+      ENV.key?('NO_COLOR')
+    end
+
+    def ci?
+      ENV.key?('CI') || ENV.key?('GITHUB_ACTIONS') || ENV.key?('GITLAB_CI')
+    end
+
+    def color_enabled?
+      !no_color?
+    end
+  end
+end

data/lib/boreal/theme.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Boreal
+  # Semantic role → palette mappings with optional styles and icons.
+  # Maps ecosystem conventions (starship, fzf, neovim, terraform) to Nord colors.
+  module Theme
+    Role = Data.define(:hex, :styles, :icon)
+
+    ROLES = {
+      # Status
+      success:   Role.new(hex: Palette::GREEN,  styles: [:bold], icon: '✓'),
+      error:     Role.new(hex: Palette::RED,    styles: [:bold], icon: '✗'),
+      warning:   Role.new(hex: Palette::ORANGE, styles: [],      icon: '⚠'),
+      info:      Role.new(hex: Palette::FROST2, styles: [],      icon: 'ℹ'),
+      debug:     Role.new(hex: Palette::NIGHT3, styles: [],      icon: '•'),
+
+      # Actions (terraform-style)
+      create:    Role.new(hex: Palette::GREEN,  styles: [:bold], icon: '+'),
+      update:    Role.new(hex: Palette::YELLOW, styles: [],      icon: '~'),
+      delete:    Role.new(hex: Palette::RED,    styles: [:bold], icon: '-'),
+      replace:   Role.new(hex: Palette::PURPLE, styles: [],      icon: '±'),
+      import:    Role.new(hex: Palette::FROST2, styles: [],      icon: '⬇'),
+      refresh:   Role.new(hex: Palette::FROST1, styles: [],      icon: '↻'),
+
+      # Emphasis
+      primary:   Role.new(hex: Palette::FROST1, styles: [:bold], icon: nil),
+      secondary: Role.new(hex: Palette::FROST3, styles: [],      icon: nil),
+      muted:     Role.new(hex: Palette::NIGHT3, styles: [],      icon: nil),
+      text:      Role.new(hex: Palette::SNOW0,  styles: [],      icon: nil),
+      bright:    Role.new(hex: Palette::SNOW2,  styles: [],      icon: nil),
+
+      # Structural
+      border:    Role.new(hex: Palette::FROST1, styles: [],      icon: nil),
+      separator: Role.new(hex: Palette::NIGHT3, styles: [],      icon: nil),
+
+      # Diff
+      added:     Role.new(hex: Palette::GREEN,  styles: [],      icon: '+'),
+      removed:   Role.new(hex: Palette::RED,    styles: [],      icon: '-'),
+      changed:   Role.new(hex: Palette::YELLOW, styles: [],      icon: '~'),
+
+      # Pending
+      pending:   Role.new(hex: Palette::FROST1, styles: [],      icon: '⧖')
+    }.freeze
+
+    # Extended icons for domain-specific contexts (templates, resources, etc.)
+    ICONS = {
+      success: '✓', error: '✗', warning: '⚠', info: 'ℹ', pending: '⧖',
+      create: '+', update: '~', delete: '-', replace: '±', import: '⬇', refresh: '↻',
+      template: '📄', resource: '🏗️', provider: '☁️', backend: '🔧', namespace: '🏷️',
+      workspace: '📁', config: '⚙️', summary: '📊', plan: '📋', output: '📤',
+      state: '📈', diff: '🔄', security: '🔒', network: '🌐', database: '🗄️',
+      compute: '💻', storage: '💾', compiling: '⚙️', compiled: '✅', failed: '❌',
+      validating: '🔍', validated: '✅', applying: '🚀', destroying: '💥', initializing: '🔧'
+    }.freeze
+
+    class << self
+      def role(name)
+        ROLES.fetch(name) { raise ArgumentError, "Unknown role: #{name}" }
+      end
+
+      def hex(name)
+        role(name).hex
+      end
+
+      def icon(name)
+        ICONS[name] || ROLES.dig(name, :icon)
+      end
+
+      def styles(name)
+        role(name).styles
+      end
+    end
+  end
+end

data/lib/boreal/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Boreal
+  VERSION = '0.1.0'
+end

data/lib/boreal.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'boreal/version'
+require_relative 'boreal/palette'
+require_relative 'boreal/theme'
+require_relative 'boreal/terminal'
+require_relative 'boreal/renderer'
+require_relative 'boreal/compat'
+require_relative 'boreal/components/base'
+require_relative 'boreal/components/box'
+require_relative 'boreal/components/table'
+require_relative 'boreal/components/spinner'
+require_relative 'boreal/components/progress'
+require_relative 'boreal/components/banner'
+require_relative 'boreal/components/logger'
+
+module Boreal
+  class << self
+    # Paint text using a semantic role or raw hex color.
+    #   Boreal.paint("ok", :success)   # => green bold via Paint
+    #   Boreal.paint("ok", '#88C0D0')  # => raw hex
+    def paint(text, role_or_hex)
+      Renderer.paint(text, role_or_hex)
+    end
+
+    # Paint with explicit hex color.
+    def hex(text, hex_color)
+      Renderer.hex(text, hex_color)
+    end
+
+    # Paint with bold + role color.
+    def bold(text, role_or_hex = nil)
+      Renderer.bold(text, role_or_hex)
+    end
+
+    # Return the icon string for a role.
+    def icon(role)
+      Renderer.icon(role)
+    end
+
+    # Render "icon text" in the role's color.
+    def status(role, text)
+      Renderer.status(role, text)
+    end
+
+    # Decorate text using a Pastel-compatible symbol name.
+    def decorate(text, color_sym)
+      Renderer.decorate(text, color_sym)
+    end
+  end
+end

metadata

@@ -0,0 +1,172 @@
+--- !ruby/object:Gem::Specification
+name: boreal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Luis Zayas
+bindir: bin
+cert_chain: []
+date: 2026-02-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: paint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: tty-box
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: tty-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: tty-spinner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: tty-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: True 24-bit Nord palette theming for CLI tools. Wraps TTY components
+  (box, table, spinner, progress) with unified Nord styling via the Paint gem.
+email:
+- drzthslnt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- Rakefile
+- boreal.gemspec
+- lib/boreal.rb
+- lib/boreal/compat.rb
+- lib/boreal/components/banner.rb
+- lib/boreal/components/base.rb
+- lib/boreal/components/box.rb
+- lib/boreal/components/logger.rb
+- lib/boreal/components/progress.rb
+- lib/boreal/components/spinner.rb
+- lib/boreal/components/table.rb
+- lib/boreal/palette.rb
+- lib/boreal/renderer.rb
+- lib/boreal/terminal.rb
+- lib/boreal/theme.rb
+- lib/boreal/version.rb
+homepage: https://github.com/pleme-io/boreal
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.6
+specification_version: 4
+summary: Nord-themed CLI look-and-feel for Ruby
+test_files: []