ace-b36ts 0.13.0

data/lib/ace/b36ts/atoms/format_specs.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Ace
+  module B36ts
+    module Atoms
+      # Format specifications for granular timestamp encoding.
+      #
+      # Defines 7 format types with varying precision and length:
+      # - 2sec (6 chars, ~1.85s precision) - default
+      # - month (2 chars, month precision)
+      # - week (3 chars, week precision)
+      # - day (3 chars, day precision)
+      # - 40min (4 chars, 40-minute block precision)
+      # - 50ms (7 chars, ~50ms precision)
+      # - ms (8 chars, ~1.4ms precision)
+      #
+      # Day/week disambiguation (3-char formats):
+      # - Day format: 3rd character in 0-30 range
+      # - Week format: 3rd character in 31-35 range
+      #
+      # @example Access format specifications
+      #   FormatSpecs::FORMATS[:"2sec"]  # => FormatSpec for 6-char IDs
+      #   FormatSpecs::FORMATS[:month]   # => FormatSpec for 2-char IDs
+      #
+      module FormatSpecs
+        # Immutable value object defining a timestamp format specification
+        FormatSpec = Data.define(:name, :length, :precision_desc, :pattern)
+
+        # All supported format specifications
+        FORMATS = {
+          "2sec": FormatSpec.new(
+            name: :"2sec",
+            length: 6,
+            precision_desc: "~1.85s",
+            pattern: /\A[0-9a-z]{6}\z/i
+          ),
+          month: FormatSpec.new(
+            name: :month,
+            length: 2,
+            precision_desc: "month",
+            pattern: /\A[0-9a-z]{2}\z/i
+          ),
+          week: FormatSpec.new(
+            name: :week,
+            length: 3,
+            precision_desc: "week",
+            pattern: /\A[0-9a-z]{3}\z/i
+          ),
+          day: FormatSpec.new(
+            name: :day,
+            length: 3,
+            precision_desc: "day",
+            pattern: /\A[0-9a-z]{3}\z/i
+          ),
+          "40min": FormatSpec.new(
+            name: :"40min",
+            length: 4,
+            precision_desc: "40min",
+            pattern: /\A[0-9a-z]{4}\z/i
+          ),
+          "50ms": FormatSpec.new(
+            name: :"50ms",
+            length: 7,
+            precision_desc: "~50ms",
+            pattern: /\A[0-9a-z]{7}\z/i
+          ),
+          ms: FormatSpec.new(
+            name: :ms,
+            length: 8,
+            precision_desc: "~1.4ms",
+            pattern: /\A[0-9a-z]{8}\z/i
+          )
+        }.freeze
+
+        # Day/week disambiguation for 3-char formats
+        # Day format: 3rd char (day value) is 0-30
+        # Week format: 3rd char (week value) is 31-35
+        DAY_FORMAT_MAX = 30
+        WEEK_FORMAT_MIN = 31
+        WEEK_FORMAT_MAX = 35
+        SPLIT_LEVELS = %i[month week day block].freeze
+
+        class << self
+          # Get format specification by name
+          #
+          # @param name [Symbol] Format name (:"2sec", :month, :week, :day, :"40min", :"50ms", :ms)
+          # @return [FormatSpec, nil] Format specification or nil if not found
+          def get(name)
+            FORMATS[name]
+          end
+
+          # Check if format name is valid
+          #
+          # @param name [Symbol] Format name to check
+          # @return [Boolean] True if format is supported
+          def valid_format?(name)
+            FORMATS.key?(name)
+          end
+
+          # Get all format names
+          #
+          # @return [Array<Symbol>] List of supported format names
+          def all_formats
+            FORMATS.keys
+          end
+
+          # Get all supported lengths
+          #
+          # @return [Array<Integer>] List of supported ID lengths
+          def all_lengths
+            FORMATS.values.map(&:length).uniq.sort
+          end
+
+          # Validate split level ordering and hierarchy
+          #
+          # @param levels [Array<Symbol>] Split levels to validate
+          # @return [Boolean] True if split levels are valid
+          def valid_split_levels?(levels)
+            return false unless levels.is_a?(Array)
+            return false if levels.empty?
+            return false unless levels.all? { |level| SPLIT_LEVELS.include?(level) }
+            return false unless levels.uniq.length == levels.length
+            return false unless levels.first == :month
+
+            indices = levels.map { |level| SPLIT_LEVELS.index(level) }
+            return false unless indices == indices.sort
+            return false if levels.include?(:block) && !levels.include?(:day)
+
+            true
+          end
+
+          # Detect format from ID string
+          # For 3-char IDs, uses the 3rd character value to distinguish day vs week
+          #
+          # @param encoded_id [String] The encoded ID string
+          # @param alphabet [String] Base36 alphabet
+          # @return [Symbol, nil] Detected format name or nil if invalid
+          def detect_from_id(encoded_id, alphabet: CompactIdEncoder::DEFAULT_ALPHABET)
+            return nil if encoded_id.nil? || encoded_id.empty?
+
+            # Validate all characters are in the alphabet
+            # Use Set for faster character validation (O(1) vs O(n))
+            alphabet_set = (alphabet == CompactIdEncoder::DEFAULT_ALPHABET) ? CompactIdEncoder::DEFAULT_ALPHABET_SET : alphabet.chars.to_set
+            return nil unless encoded_id.downcase.chars.all? { |c| alphabet_set.include?(c) }
+
+            length = encoded_id.length
+
+            case length
+            when 2
+              :month
+            when 3
+              # Disambiguate day vs week by 3rd character value
+              third_char_value = alphabet.index(encoded_id[2].downcase)
+              return nil if third_char_value.nil?
+
+              if third_char_value <= DAY_FORMAT_MAX
+                :day
+              elsif third_char_value <= WEEK_FORMAT_MAX
+                :week
+              end
+              # Note: With base36 (values 0-35), day covers 0-30 and week covers 31-35,
+              # so all valid values are handled. This branch implicitly returns nil
+              # only if alphabet validation fails (which is caught earlier).
+            when 4
+              :"40min"
+            when 6
+              :"2sec"
+            when 7
+              :"50ms"
+            when 8
+              :ms
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/b36ts/atoms/formats.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "format_specs"
+
+module Ace
+  module B36ts
+    module Atoms
+      # Detects and validates timestamp format types.
+      #
+      # Supports multiple compact ID formats:
+      # - :"2sec" - 6-character Base36 compact ID (e.g., "i50jj3")
+      # - :month - 2-character Base36 month ID (e.g., "i5")
+      # - :week - 3-character Base36 week ID (e.g., "i5v")
+      # - :day - 3-character Base36 day ID (e.g., "i50")
+      # - :"40min" - 4-character Base36 40min block ID (e.g., "i50j")
+      # - :"50ms" - 7-character Base36 high-precision ID (e.g., "i50jj3z")
+      # - :ms - 8-character Base36 high-precision ID (e.g., "i50jj3zz")
+      # - :timestamp - 14-character timestamp format (e.g., "20250101-120000")
+      #
+      # @example Detect format
+      #   Formats.detect("i50jj3")         # => :"2sec"
+      #   Formats.detect("i5")             # => :month
+      #   Formats.detect("i5v")            # => :week (3rd char 31-35)
+      #   Formats.detect("i50")            # => :day (3rd char 0-30)
+      #   Formats.detect("i50j")           # => :"40min"
+      #   Formats.detect("i50jj3z")        # => :"50ms"
+      #   Formats.detect("i50jj3zz")       # => :ms
+      #   Formats.detect("20250101-120000") # => :timestamp
+      #   Formats.detect("invalid")         # => nil
+      #
+      module Formats
+        # Regex patterns for format detection
+        MONTH_PATTERN = /\A[0-9a-z]{2}\z/i
+        DAY_WEEK_PATTERN = /\A[0-9a-z]{3}\z/i  # Disambiguate by 3rd char value
+        HOUR_PATTERN = /\A[0-9a-z]{4}\z/i
+        COMPACT_PATTERN = /\A[0-9a-z]{6}\z/i
+        HIGH_7_PATTERN = /\A[0-9a-z]{7}\z/i
+        HIGH_8_PATTERN = /\A[0-9a-z]{8}\z/i
+        TIMESTAMP_PATTERN = /\A\d{8}-\d{6}\z/
+
+        class << self
+          # Detect the format type of a timestamp string
+          #
+          # For 3-character IDs, uses the 3rd character value to distinguish day vs week:
+          # - Day format: 3rd char in 0-30 range
+          # - Week format: 3rd char in 31-35 range
+          #
+          # @param value [String] The timestamp string to analyze
+          # @return [Symbol, nil] :"2sec", :month, :week, :day, :"40min", :"50ms", :ms, :timestamp, or nil if unrecognized
+          def detect(value)
+            return nil unless value.is_a?(String)
+
+            # For compact ID formats, delegate to FormatSpecs for proper detection
+            # including day/week disambiguation
+            if FormatSpecs::FORMATS.values.any? { |spec| spec.pattern.match?(value) }
+              FormatSpecs.detect_from_id(value)
+            elsif TIMESTAMP_PATTERN.match?(value)
+              :timestamp
+            end
+          end
+
+          # Check if value is a valid compact ID format
+          #
+          # @param value [String] The string to check
+          # @return [Boolean] true if valid compact format
+          def compact?(value)
+            detect(value) == :"2sec"
+          end
+
+          # Check if value is a valid timestamp format
+          #
+          # @param value [String] The string to check
+          # @return [Boolean] true if valid timestamp format
+          def timestamp?(value)
+            detect(value) == :timestamp
+          end
+
+          # Parse a timestamp format string to Time
+          #
+          # @param value [String] Timestamp in "YYYYMMDD-HHMMSS" format
+          # @return [Time] Parsed time in UTC
+          # @raise [ArgumentError] If format is invalid
+          def parse_timestamp(value)
+            unless timestamp?(value)
+              raise ArgumentError, "Invalid timestamp format: #{value} (expected YYYYMMDD-HHMMSS)"
+            end
+
+            year = value[0..3].to_i
+            month = value[4..5].to_i
+            day = value[6..7].to_i
+            hour = value[9..10].to_i
+            minute = value[11..12].to_i
+            second = value[13..14].to_i
+
+            Time.utc(year, month, day, hour, minute, second)
+          end
+
+          # Format a Time object to timestamp format
+          #
+          # @param time [Time] The time to format
+          # @return [String] Timestamp in "YYYYMMDD-HHMMSS" format
+          def format_timestamp(time)
+            time = time.utc if time.respond_to?(:utc)
+            time.strftime("%Y%m%d-%H%M%S")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/b36ts/cli/commands/config.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../../commands/config_command"
+
+module Ace
+  module B36ts
+    module CLI
+      module Commands
+        # Show current configuration
+        class Config < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Show current configuration"
+
+          option :verbose, type: :boolean, aliases: ["-v"], desc: "Show verbose output"
+
+          example [
+            "           # Show basic config",
+            "--verbose  # Show full config with sources"
+          ]
+
+          def call(**options)
+            Ace::B36ts::Commands::ConfigCommand.execute(options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/b36ts/cli/commands/decode.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../../commands/decode_command"
+
+module Ace
+  module B36ts
+    module CLI
+      module Commands
+        # Decode a compact ID to a timestamp
+        class Decode < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Decode a compact ID (2-8 characters) to a timestamp"
+
+          argument :compact_id, required: true, desc: "2-8 character compact ID to decode (auto-detects format)"
+          option :year_zero, type: :integer, aliases: ["-y"], desc: "Base year for decoding (default: 2000)"
+          option :format, type: :string, aliases: ["-f"], desc: "Output format (readable, iso, timestamp)"
+          option :split, type: :boolean, desc: "Force hierarchical split decoding"
+          option :quiet, type: :boolean, aliases: ["-q"], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: ["-v"], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: ["-d"], desc: "Show debug output"
+
+          example [
+            "i5                        # Decode 2-char month ID",
+            "i5v                       # Decode 3-char week ID (3rd char 31-35)",
+            "i50                       # Decode 3-char day ID (3rd char 0-30)",
+            "i50j                      # Decode 4-char 40min ID",
+            "i50jj3                    # Decode 6-char 2sec ID",
+            "i50jj3z                   # Decode 7-char 50ms ID",
+            "i50jj3zz                  # Decode 8-char ms ID",
+            "i50jj3 --format iso       # Decode to ISO format",
+            "i50jj3 --format timestamp # Decode to YYYYMMDD-HHMMSS",
+            "i5/1/5/j/j3               # Decode split path (auto-detect separators)",
+            "i515jj3 --split           # Decode split full string"
+          ]
+
+          def call(compact_id:, **options)
+            # Convert numeric options from strings to integers
+            coerce_types(options, year_zero: :integer)
+
+            Ace::B36ts::Commands::DecodeCommand.execute(compact_id, options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/b36ts/cli/commands/encode.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../../commands/encode_command"
+
+module Ace
+  module B36ts
+    module CLI
+      module Commands
+        # Encode a timestamp to a 6-character compact ID
+        class Encode < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Encode a timestamp to a compact ID (2-8 characters)"
+
+          argument :timestamp, required: false, desc: "Timestamp to encode (ISO, readable, 'now', or empty for current time)"
+          option :format, type: :string, aliases: ["-f"], desc: "Output format: 2sec (default), month, week, day, 40min, 50ms, ms"
+          option :count, type: :integer, aliases: ["-n"], desc: "Generate N sequential IDs starting from timestamp"
+          option :split, type: :string, desc: "Split levels for hierarchical output (month,week,day,block)"
+          option :path_only, type: :boolean, desc: "Output only the split path"
+          option :json, type: :boolean, desc: "Output split data as JSON (works with --split or --count)"
+          option :year_zero, type: :integer, aliases: ["-y"], desc: "Base year for encoding (default: 2000)"
+          option :quiet, type: :boolean, aliases: ["-q"], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: ["-v"], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: ["-d"], desc: "Show debug output"
+
+          example [
+            "'2025-01-06 12:30:00'    # Encode readable timestamp",
+            "now                       # Encode current time",
+            "--format day '2025-01-06' # Encode to day format",
+            "--format month now        # Encode to month format",
+            "--format 40min now        # Encode to 40min format",
+            "--format 50ms now         # Encode to 50ms format",
+            "--count 10 --format ms now      # Generate 10 sequential ms-precision IDs",
+            "-n 5 --format day now           # Generate 5 consecutive day IDs",
+            "--count 3 --format 2sec --json now  # Generate 3 IDs as JSON array",
+            "--split month,week now    # Encode to hierarchical split output",
+            "--split month,week now --path-only  # Output only the path",
+            "--split month,day now --json        # Output JSON split data",
+            "--year-zero 2025 '2025-01-06'  # Encode with custom base year"
+          ]
+
+          def call(timestamp: nil, **options)
+            # Convert numeric options from strings to integers
+            coerce_types(options, year_zero: :integer, count: :integer)
+
+            Ace::B36ts::Commands::EncodeCommand.execute(timestamp, options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/b36ts/cli.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "cli/commands/encode"
+require_relative "cli/commands/decode"
+require_relative "cli/commands/config"
+require_relative "version"
+
+module Ace
+  module B36ts
+    # CLI interface for ace-b36ts using ace-support-cli
+    #
+    # This follows the Hanami pattern with all commands in CLI::Commands:: namespace.
+    #
+    # @example Encode a timestamp
+    #   $ ace-b36ts encode "2025-01-06 12:30:00"
+    #   i50jj3
+    #
+    # @example Decode a compact ID
+    #   $ ace-b36ts decode i50jj3
+    #   2025-01-06 12:30:00 UTC
+    #
+    # @example Show configuration
+    #   $ ace-b36ts config
+    #   year_zero: 2000
+    #   alphabet: 0123456789abcdefghijklmnopqrstuvwxyz
+    #
+    module CLI
+      extend Ace::Support::Cli::RegistryDsl
+
+      PROGRAM_NAME = "ace-b36ts"
+
+      REGISTERED_COMMANDS = [
+        ["encode", "Encode timestamp to compact ID"],
+        ["decode", "Decode compact ID to timestamp"],
+        ["config", "Show current configuration"]
+      ].freeze
+
+      HELP_EXAMPLES = [
+        "ace-b36ts encode                          # Generate ID from now",
+        "ace-b36ts encode 2024-01-15T10:30:00Z     # Encode specific time",
+        "ace-b36ts decode abc123                   # Decode ID to timestamp"
+      ].freeze
+
+      # Register commands (Hanami pattern: CLI::Commands::*)
+      register "encode", Commands::Encode
+      register "decode", Commands::Decode
+      register "config", Commands::Config
+
+      # Version command
+      version_cmd = Ace::Support::Cli::VersionCommand.build(
+        gem_name: "ace-b36ts",
+        version: Ace::B36ts::VERSION
+      )
+      register "version", version_cmd
+      register "--version", version_cmd
+
+      # Help command
+      help_cmd = Ace::Support::Cli::HelpCommand.build(
+        program_name: PROGRAM_NAME,
+        version: Ace::B36ts::VERSION,
+        commands: REGISTERED_COMMANDS,
+        examples: HELP_EXAMPLES
+      )
+      register "help", help_cmd
+      register "--help", help_cmd
+      register "-h", help_cmd
+    end
+  end
+end

data/lib/ace/b36ts/commands/config_command.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ace
+  module B36ts
+    module Commands
+      # Command to display current configuration
+      #
+      # @example Usage
+      #   ConfigCommand.execute
+      #   # Output:
+      #   # year_zero: 2000
+      #   # alphabet: 0123456789abcdefghijklmnopqrstuvwxyz
+      #
+      class ConfigCommand
+        class << self
+          # Execute the config command
+          #
+          # @param options [Hash] Command options
+          # @option options [Boolean] :verbose Show additional config details
+          # @return [Integer] Exit code (0 for success)
+          def execute(options = {})
+            config = Molecules::ConfigResolver.resolve
+
+            puts "Current ace-b36ts configuration:"
+            puts ""
+            puts "  year_zero: #{config[:year_zero]}"
+            puts "  alphabet: #{config[:alphabet]}"
+
+            if options[:verbose]
+              puts ""
+              puts "Configuration sources (in order of precedence):"
+              puts "  1. Runtime options (passed to commands)"
+              puts "  2. Project config: .ace/b36ts/config.yml"
+              puts "  3. User config: ~/.ace/b36ts/config.yml"
+              puts "  4. Gem defaults: .ace-defaults/b36ts/config.yml"
+              puts ""
+              puts "Year range: #{config[:year_zero]} to #{config[:year_zero] + 107}"
+              puts "ID length: 6 characters (Base36)"
+              puts "Time precision: ~1.85 seconds"
+            end
+
+            0
+          rescue => e
+            warn "Error displaying config: #{e.message}"
+            warn e.backtrace.first(5).join("\n") if Ace::B36ts.debug?
+            raise
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/b36ts/commands/decode_command.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Ace
+  module B36ts
+    module Commands
+      # Command to decode a compact ID to a timestamp
+      #
+      # @example Usage
+      #   DecodeCommand.execute("i50jj3")
+      #   # => "2025-01-06 12:30:00 UTC"
+      #
+      class DecodeCommand
+        class << self
+          # Execute the decode command
+          #
+          # @param compact_id [String] 2-8 character compact ID to decode
+          # @param options [Hash] Command options
+          # @option options [Integer] :year_zero Override year_zero config
+          # @option options [String] :format Output format (:iso, :timestamp, :readable)
+          # @option options [Boolean] :quiet Suppress config summary output
+          # @return [Integer] Exit code (0 for success, 1 for error)
+          def execute(compact_id, options = {})
+            config = Molecules::ConfigResolver.resolve(options)
+
+            display_config_summary("decode", config, options)
+
+            # Use split decoding for hierarchical paths, otherwise auto-detect
+            time = if options[:split] || contains_split_separator?(compact_id)
+              Atoms::CompactIdEncoder.decode_path(
+                compact_id,
+                year_zero: config[:year_zero],
+                alphabet: config[:alphabet]
+              )
+            else
+              Atoms::CompactIdEncoder.decode_auto(
+                compact_id,
+                year_zero: config[:year_zero],
+                alphabet: config[:alphabet]
+              )
+            end
+
+            output = format_output(time, options[:format])
+            puts output
+            0
+          rescue ArgumentError => e
+            warn "Error: #{e.message}"
+            raise
+          rescue => e
+            warn "Error decoding compact ID: #{e.message}"
+            warn e.backtrace.first(5).join("\n") if Ace::B36ts.debug?
+            raise
+          end
+
+          private
+
+          # Format the time output based on requested format
+          #
+          # @param time [Time] Decoded time
+          # @param format [Symbol, String, nil] Output format
+          # @return [String] Formatted time string
+          def format_output(time, format)
+            case format&.to_sym
+            when :iso
+              time.iso8601
+            when :timestamp
+              Atoms::Formats.format_timestamp(time)
+            when :readable
+              time.strftime("%Y-%m-%d %H:%M:%S UTC")
+            else
+              # Default: readable format
+              time.strftime("%Y-%m-%d %H:%M:%S UTC")
+            end
+          end
+
+          # Display configuration summary (unless quiet mode)
+          #
+          # @param command [String] Command name
+          # @param config [Hash] Resolved configuration
+          # @param options [Hash] Command options
+          def display_config_summary(command, config, options)
+            return if options[:quiet]
+
+            require "ace/core"
+            Ace::Core::Atoms::ConfigSummary.display(
+              command: command,
+              config: config,
+              defaults: Molecules::ConfigResolver::FALLBACK_DEFAULTS,
+              options: options,
+              quiet: false
+            )
+          end
+
+          # Detect split separators in input
+          #
+          # @param value [String] Input to check
+          # @return [Boolean] True if split separators are present
+          def contains_split_separator?(value)
+            value.is_a?(String) && value.match?(/[\/\\:]/)
+          end
+        end
+      end
+    end
+  end
+end