ace-b36ts 0.13.0

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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Ace
+  module B36ts
+    module Commands
+      # Command to encode a timestamp to a compact ID
+      #
+      # @example Usage
+      #   EncodeCommand.execute("2025-01-06 12:30:00")
+      #   # => "i50jj3"
+      #
+      class EncodeCommand
+        class << self
+          # Execute the encode command
+          #
+          # @param time_string [String] Time string to encode (various formats supported)
+          # @param options [Hash] Command options
+          # @option options [Integer] :year_zero Override year_zero config
+          # @option options [String] :format Output format
+          # @option options [Boolean] :quiet Suppress config summary output
+          # @return [Integer] Exit code (0 for success, 1 for error)
+          def execute(time_string, options = {})
+            time = parse_time(time_string)
+            config = Molecules::ConfigResolver.resolve(options)
+
+            display_config_summary("encode", config, options)
+
+            # Validate mutually exclusive options
+            if options[:split]
+              if options[:format]
+                raise ArgumentError, "--split and --format are mutually exclusive"
+              end
+              if options[:count]
+                raise ArgumentError, "--count and --split are mutually exclusive"
+              end
+
+              levels = parse_split_levels(options[:split])
+              output = Atoms::CompactIdEncoder.encode_split(
+                time,
+                levels: levels,
+                year_zero: config[:year_zero],
+                alphabet: config[:alphabet]
+              )
+
+              if options[:path_only]
+                puts output[:path]
+              elsif options[:json]
+                puts JSON.generate(output.transform_keys(&:to_s))
+              else
+                display_split_output(levels, output)
+              end
+            else
+              # Get format from options or config (default: :"2sec")
+              # Normalize hyphens to underscores for CLI compatibility (e.g., high-8 -> high_8)
+              format = options[:format]
+              format = format.to_s.tr("-", "_").to_sym if format
+              format ||= config[:default_format]&.to_sym || :"2sec"
+
+              if options[:count]
+                count = options[:count].to_i
+                ids = Atoms::CompactIdEncoder.encode_sequence(
+                  time,
+                  count: count,
+                  format: format,
+                  year_zero: config[:year_zero],
+                  alphabet: config[:alphabet]
+                )
+
+                if options[:json]
+                  puts JSON.generate(ids)
+                else
+                  ids.each { |id| puts id }
+                end
+              else
+                compact_id = Atoms::CompactIdEncoder.encode_with_format(
+                  time,
+                  format: format,
+                  year_zero: config[:year_zero],
+                  alphabet: config[:alphabet]
+                )
+
+                puts compact_id
+              end
+            end
+            0
+          rescue ArgumentError => e
+            warn "Error: #{e.message}"
+            raise
+          rescue => e
+            warn "Error encoding timestamp: #{e.message}"
+            warn e.backtrace.first(5).join("\n") if Ace::B36ts.debug?
+            raise
+          end
+
+          private
+
+          # Parse various time string formats
+          #
+          # @param time_string [String] Time string to parse
+          # @return [Time] Parsed time
+          # @raise [ArgumentError] If format is unrecognized
+          def parse_time(time_string)
+            return Time.now.utc if time_string.nil? || time_string.empty? || time_string == "now"
+
+            # Check for legacy timestamp format FIRST (YYYYMMDD-HHMMSS)
+            # Time.parse incorrectly parses this format (treats -HHMMSS as timezone offset)
+            if Atoms::Formats.timestamp?(time_string)
+              return Atoms::Formats.parse_timestamp(time_string)
+            end
+
+            parsed = Time.parse(time_string)
+            return parsed if has_explicit_timezone?(time_string)
+
+            # Treat naïve timestamps as UTC to avoid local-time offsets on date-only
+            # inputs and systems with non-UTC defaults.
+            Time.utc(parsed.year, parsed.month, parsed.day, parsed.hour, parsed.min, parsed.sec, parsed.nsec)
+          rescue ArgumentError
+            raise ArgumentError, "Cannot parse time: #{time_string}"
+          end
+
+          def has_explicit_timezone?(time_string)
+            value = time_string.to_s
+            return true if value.match?(%r{[+-]\d{2}:?\d{2}\b})
+            return true if value.match?(%r{(?:\A|[[:space:]])(?:Z|UTC|GMT)\b}i)
+
+            false
+          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] || options[:path_only] || options[:json]
+
+            require "ace/core"
+            Ace::Core::Atoms::ConfigSummary.display(
+              command: command,
+              config: config,
+              defaults: Molecules::ConfigResolver::FALLBACK_DEFAULTS,
+              options: options,
+              quiet: false
+            )
+          end
+
+          # Normalize split levels from string or array
+          #
+          # @param levels [String, Array<Symbol>] Split level list
+          # @return [Array<Symbol>] Normalized levels
+          def parse_split_levels(levels)
+            list = levels.is_a?(String) ? levels.split(",") : Array(levels)
+            list.map { |level| level.to_s.strip }
+              .reject(&:empty?)
+              .map(&:to_sym)
+          end
+
+          # Display split output in key/value format
+          #
+          # @param levels [Array<Symbol>] Split levels in order
+          # @param output [Hash] Split output hash
+          def display_split_output(levels, output)
+            lines = []
+            levels.each do |level|
+              lines << "#{level}: #{output[level]}"
+            end
+            lines << "rest: #{output[:rest]}"
+            lines << "path: #{output[:path]}"
+            lines << "full: #{output[:full]}"
+            puts lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/b36ts/molecules/config_resolver.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/format_specs"
+
+module Ace
+  module B36ts
+    module Molecules
+      # Resolves configuration for ace-b36ts using the ace-config cascade.
+      #
+      # Configuration sources (in order of precedence):
+      # 1. Runtime options (passed directly to methods)
+      # 2. Project config (.ace/b36ts/config.yml)
+      # 3. User config (~/.ace/b36ts/config.yml)
+      # 4. Gem defaults (.ace-defaults/b36ts/config.yml)
+      #
+      # @example Get resolved configuration
+      #   config = ConfigResolver.resolve
+      #   config[:year_zero]  # => 2000
+      #   config[:alphabet]   # => "0123456789abcdefghijklmnopqrstuvwxyz"
+      #
+      # @example Override with runtime options
+      #   config = ConfigResolver.resolve(year_zero: 2025)
+      #   config[:year_zero]  # => 2025
+      #
+      module ConfigResolver
+        # Fallback defaults (used only if .ace-defaults files cannot be loaded)
+        FALLBACK_DEFAULTS = {
+          year_zero: 2000,
+          alphabet: "0123456789abcdefghijklmnopqrstuvwxyz",
+          default_format: :"2sec"
+        }.freeze
+
+        class << self
+          # Resolve configuration with optional overrides
+          #
+          # Uses Ace::Support::Config::Models::Config.wrap for proper merging per ADR-022.
+          #
+          # @param overrides [Hash] Runtime configuration overrides
+          # @return [Hash] Merged configuration
+          # @raise [ArgumentError] If configuration values are invalid
+          def resolve(overrides = {})
+            base_config = load_config
+
+            # Apply runtime overrides (symbolize keys, skip nil values)
+            symbolized_overrides = {}
+            overrides.each do |key, value|
+              symbolized_overrides[key.to_sym] = value unless value.nil?
+            end
+
+            # Merge base config with runtime overrides
+            config = Ace::Support::Config::Models::Config.wrap(
+              base_config,
+              symbolized_overrides,
+              source: "ace-b36ts"
+            )
+
+            # Validate the merged configuration
+            validate_config!(config)
+
+            config
+          end
+
+          # Get the year_zero value from configuration
+          #
+          # @param override [Integer, nil] Optional runtime override
+          # @return [Integer] The year_zero value
+          def year_zero(override = nil)
+            override || resolve[:year_zero]
+          end
+
+          # Get the alphabet value from configuration
+          #
+          # @param override [String, nil] Optional runtime override
+          # @return [String] The alphabet value
+          def alphabet(override = nil)
+            override || resolve[:alphabet]
+          end
+
+          # Get the default_format value from configuration
+          #
+          # @param override [Symbol, String, nil] Optional runtime override
+          # @return [Symbol] The default_format value (always a symbol)
+          def default_format(override = nil)
+            value = override || resolve[:default_format]
+            value.is_a?(String) ? value.to_sym : value
+          end
+
+          # Reset cached configuration (useful for testing)
+          def reset!
+            @config = nil
+          end
+
+          private
+
+          # Validate configuration values
+          #
+          # @param config [Hash] Configuration to validate
+          # @raise [ArgumentError] If configuration values are invalid
+          def validate_config!(config)
+            alphabet = config[:alphabet]
+            year_zero = config[:year_zero]
+            default_format = config[:default_format]
+
+            unless alphabet.is_a?(String) && alphabet.length == 36
+              raise ArgumentError, "alphabet must be exactly 36 characters, got #{alphabet&.length || "nil"}"
+            end
+
+            # Verify all characters in the alphabet are unique
+            unless alphabet.chars.uniq.length == 36
+              raise ArgumentError, "alphabet must contain 36 unique characters (duplicates found)"
+            end
+
+            unless year_zero.is_a?(Integer) && year_zero.between?(1900, 2100)
+              raise ArgumentError, "year_zero must be between 1900-2100, got #{year_zero.inspect}"
+            end
+
+            # Validate default_format is a supported format
+            format_sym = default_format.is_a?(String) ? default_format.to_sym : default_format
+            unless format_sym.nil? || Ace::B36ts::Atoms::FormatSpecs.valid_format?(format_sym)
+              raise ArgumentError, "default_format must be one of #{Ace::B36ts::Atoms::FormatSpecs.all_formats.join(", ")}, got #{default_format.inspect}"
+            end
+          end
+
+          # Load configuration using ace-config cascade
+          #
+          # @return [Hash] Loaded configuration with symbolized keys
+          def load_config
+            @config ||= begin
+              gem_root = Gem.loaded_specs["ace-b36ts"]&.gem_dir ||
+                File.expand_path("../../../..", __dir__)
+
+              resolver = Ace::Support::Config.create(
+                config_dir: ".ace",
+                defaults_dir: ".ace-defaults",
+                gem_path: gem_root
+              )
+
+              loaded_config = resolver.resolve_namespace("b36ts")
+              # loaded_config.data is already namespaced (no need to fetch "b36ts" key again)
+              user_config = symbolize_keys(loaded_config.data)
+
+              # Merge user config with fallback defaults (user values take precedence)
+              FALLBACK_DEFAULTS.merge(user_config)
+            rescue Psych::SyntaxError => e
+              config_path = File.join(Dir.pwd, ".ace", "b36ts", "config.yml")
+              warn "Error: Failed to parse #{config_path}: #{e.message}" if Ace::B36ts.debug?
+              warn "  Check YAML syntax at line #{e.line}, column #{e.column}" if Ace::B36ts.debug? && e.line
+              FALLBACK_DEFAULTS.dup
+            rescue => e
+              warn "Warning: Could not load ace-b36ts config: #{e.message}" if Ace::B36ts.debug?
+              FALLBACK_DEFAULTS.dup
+            end
+          end
+
+          # Convert string keys to symbols
+          #
+          # @param hash [Hash] Hash with string or symbol keys
+          # @return [Hash] Hash with symbol keys
+          def symbolize_keys(hash)
+            hash.transform_keys(&:to_sym)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/b36ts/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Ace
+  module B36ts
+    # Version 0.2.0: Gem renamed from ace-timestamp to ace-support-timestamp
+    # Namespace changed from Ace::Timestamp to Ace::Support::Timestamp
+    # Version 0.6.0: Gem renamed from ace-support-timestamp to ace-b36ts
+    # Namespace changed from Ace::Support::Timestamp to Ace::B36ts
+    VERSION = "0.13.0"
+  end
+end

data/lib/ace/b36ts.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative "b36ts/version"
+
+# Load ace-config for configuration cascade management
+require "ace/support/config"
+
+# Atoms
+require_relative "b36ts/atoms/compact_id_encoder"
+require_relative "b36ts/atoms/formats"
+require_relative "b36ts/atoms/format_specs"
+
+# Molecules
+require_relative "b36ts/molecules/config_resolver"
+
+# Commands
+require_relative "b36ts/commands/encode_command"
+require_relative "b36ts/commands/decode_command"
+require_relative "b36ts/commands/config_command"
+
+# CLI
+require_relative "b36ts/cli"
+
+module Ace
+  # B36ts module providing Base36 compact ID generation for timestamps.
+  #
+  # This module provides a 6-character Base36 encoding for timestamps that
+  # replaces traditional 14-character timestamp formats (YYYYMMDD-HHMMSS).
+  #
+  # @example Quick encoding
+  #   Ace::B36ts.encode(Time.now)
+  #   # => "i50jj3"
+  #
+  # @example Quick decoding
+  #   Ace::B36ts.decode("i50jj3")
+  #   # => 2025-01-06 12:30:00 UTC
+  #
+  # @example Format detection
+  #   Ace::B36ts.detect_format("i50jj3")      # => :"2sec"
+  #   Ace::B36ts.detect_format("20250106-123000") # => :timestamp
+  #
+  module B36ts
+    class Error < StandardError; end
+
+    # Check if debug mode is enabled
+    # @return [Boolean] True if debug mode is enabled
+    def self.debug?
+      ENV["ACE_DEBUG"] == "1" || ENV["DEBUG"] == "1"
+    end
+
+    # Encode a Time object to a compact ID (convenience method)
+    #
+    # @param time [Time] The time to encode
+    # @param format [Symbol, nil] Output format (default: :"2sec")
+    #   Supported formats: :month (2 chars), :week (3 chars), :day (3 chars),
+    #   :"40min" (4 chars), :"2sec" (6 chars), :"50ms" (7 chars), :ms (8 chars)
+    # @param year_zero [Integer, nil] Optional year_zero override
+    # @return [String] Compact ID (length varies by format)
+    def self.encode(time, format: nil, year_zero: nil)
+      config = Molecules::ConfigResolver.resolve(year_zero: year_zero)
+      effective_format = format || config[:default_format]&.to_sym || :"2sec"
+
+      Atoms::CompactIdEncoder.encode_with_format(
+        time,
+        format: effective_format,
+        year_zero: config[:year_zero],
+        alphabet: config[:alphabet]
+      )
+    end
+
+    # Decode a compact ID to a Time object (convenience method)
+    #
+    # @param compact_id [String] The compact ID to decode
+    # @param format [Symbol, nil] Format of the ID (default: :"2sec" for 6-char, or auto-detect)
+    # @param year_zero [Integer, nil] Optional year_zero override
+    # @return [Time] Decoded time in UTC
+    def self.decode(compact_id, format: nil, year_zero: nil)
+      config = Molecules::ConfigResolver.resolve(year_zero: year_zero)
+
+      if format
+        Atoms::CompactIdEncoder.decode_with_format(
+          compact_id,
+          format: format,
+          year_zero: config[:year_zero],
+          alphabet: config[:alphabet]
+        )
+      else
+        # Default to 2sec format for backward compatibility with 6-char IDs
+        Atoms::CompactIdEncoder.decode(
+          compact_id,
+          year_zero: config[:year_zero],
+          alphabet: config[:alphabet]
+        )
+      end
+    end
+
+    # Decode a compact ID with automatic format detection (convenience method)
+    #
+    # Automatically detects the format based on ID length and value ranges:
+    # - 2 chars: month format
+    # - 3 chars: day or week format (auto-detected by 3rd char value)
+    # - 4 chars: 40min format
+    # - 6 chars: 2sec format
+    # - 7 chars: 50ms format
+    # - 8 chars: ms format
+    #
+    # @param compact_id [String] The compact ID to decode (2-8 characters)
+    # @param year_zero [Integer, nil] Optional year_zero override
+    # @return [Time] Decoded time in UTC
+    # @raise [ArgumentError] If format cannot be detected
+    def self.decode_auto(compact_id, year_zero: nil)
+      config = Molecules::ConfigResolver.resolve(year_zero: year_zero)
+      Atoms::CompactIdEncoder.decode_auto(
+        compact_id,
+        year_zero: config[:year_zero],
+        alphabet: config[:alphabet]
+      )
+    end
+
+    # Encode a Time object into split components for hierarchical paths
+    #
+    # @param time [Time] The time to encode
+    # @param levels [Array<Symbol>, String] Split levels (month, week, day, block)
+    # @param path_only [Boolean] Return only the path string
+    # @param year_zero [Integer, nil] Optional year_zero override
+    # @return [Hash, String] Split component hash or path string
+    def self.encode_split(time, levels:, path_only: false, year_zero: nil)
+      config = Molecules::ConfigResolver.resolve(year_zero: year_zero)
+      result = Atoms::CompactIdEncoder.encode_split(
+        time,
+        levels: levels,
+        year_zero: config[:year_zero],
+        alphabet: config[:alphabet]
+      )
+
+      path_only ? result[:path] : result
+    end
+
+    # Decode a hierarchical split path into a Time object
+    #
+    # @param path_string [String] Split path string
+    # @param year_zero [Integer, nil] Optional year_zero override
+    # @return [Time] Decoded time in UTC
+    def self.decode_path(path_string, year_zero: nil)
+      config = Molecules::ConfigResolver.resolve(year_zero: year_zero)
+      Atoms::CompactIdEncoder.decode_path(
+        path_string,
+        year_zero: config[:year_zero],
+        alphabet: config[:alphabet]
+      )
+    end
+
+    # Validate if a string is a valid 6-character compact ID (legacy method)
+    #
+    # NOTE: This method only validates 6-character "2sec" format IDs.
+    # For validating IDs of any format, use valid_any_format? instead.
+    #
+    # @param compact_id [String] The string to validate
+    # @return [Boolean] True if valid 6-char compact ID format
+    # @see valid_any_format? for validating all format lengths
+    def self.valid?(compact_id)
+      Atoms::CompactIdEncoder.valid?(compact_id)
+    end
+
+    # Validate if a string is a valid compact ID of any format
+    #
+    # Supports all 7 formats: month (2 chars), week (3 chars), day (3 chars),
+    # 40min (4 chars), 2sec (6 chars), 50ms (7 chars), ms (8 chars).
+    #
+    # @param compact_id [String] The string to validate (2-8 characters)
+    # @return [Boolean] True if valid compact ID of any format
+    def self.valid_any_format?(compact_id)
+      Atoms::CompactIdEncoder.valid_any_format?(compact_id)
+    end
+
+    # Detect the format of a timestamp string
+    #
+    # @param value [String] The timestamp string
+    # @return [Symbol, nil] :"2sec", :timestamp, or nil
+    def self.detect_format(value)
+      Atoms::Formats.detect(value)
+    end
+
+    # Generate a compact ID for the current time (convenience method)
+    #
+    # @param year_zero [Integer, nil] Optional year_zero override
+    # @return [String] 6-character compact ID for current time
+    def self.now(year_zero: nil)
+      encode(Time.now.utc, year_zero: year_zero)
+    end
+
+    # Load configuration using ace-config cascade
+    # @return [Hash] Configuration hash
+    def self.config
+      Molecules::ConfigResolver.resolve
+    end
+
+    # Reset configuration cache (useful for testing)
+    def self.reset_config!
+      Molecules::ConfigResolver.reset!
+    end
+  end
+end