zone 0.1.1 → 0.1.2

data/completions/README.md

@@ -0,0 +1,126 @@
+# Zsh Completion for Zone
+
+Intelligent command-line completion for the `zone` timezone conversion tool.
+
+## Features
+
+- Completes all command-line flags and options
+- Suggests common timezone names (UTC, local, America/New_York, etc.)
+- Provides example timestamp formats
+- Handles mutually exclusive options (e.g., --iso8601 vs --unix)
+- Context-aware completions for option values
+
+## Installation
+
+### Method 1: User-specific installation
+
+1. Create a completions directory if it doesn't exist:
+   ```bash
+   mkdir -p ~/.zsh/completions
+   ```
+
+2. Copy the completion script:
+   ```bash
+   cp completions/_zone ~/.zsh/completions/
+   ```
+
+3. Add to your `~/.zshrc` (before `compinit`):
+   ```bash
+   fpath=(~/.zsh/completions $fpath)
+   autoload -U compinit && compinit
+   ```
+
+4. Reload your shell:
+   ```bash
+   exec zsh
+   ```
+
+### Method 2: System-wide installation
+
+1. Copy to the system completions directory:
+   ```bash
+   sudo cp completions/_zone /usr/local/share/zsh/site-functions/
+   ```
+
+2. Rebuild completion cache:
+   ```bash
+   rm -f ~/.zcompdump && compinit
+   ```
+
+### Method 3: Oh My Zsh
+
+1. Copy to Oh My Zsh completions:
+   ```bash
+   cp completions/_zone ~/.oh-my-zsh/completions/
+   ```
+
+2. Reload:
+   ```bash
+   exec zsh
+   ```
+
+## Usage
+
+Once installed, press `<Tab>` after typing `zone` to see available completions:
+
+```bash
+zone <Tab>               # Shows all options
+zone --zone <Tab>        # Shows timezone suggestions
+zone --strftime <Tab>    # Prompts for strftime format
+zone 2025 <Tab>          # Shows timestamp format examples
+```
+
+## Examples
+
+```bash
+# Complete timezone names
+zone "$(date)" --zone <Tab>
+# Suggests: UTC, local, America/New_York, Europe/London, Asia/Tokyo, etc.
+
+# Complete output formats
+zone "now" --<Tab>
+# Shows: --iso8601, --pretty, --unix, --strftime, etc.
+
+# Mutually exclusive options
+zone "now" --unix --<Tab>
+# Won't suggest --iso8601, --pretty, or --strftime (incompatible)
+```
+
+## Testing
+
+Verify the completion is loaded:
+```bash
+which _zone
+# Should output the path to the completion function
+```
+
+Test syntax:
+```bash
+zsh -n completions/_zone
+# Should output nothing (syntax valid)
+```
+
+## Troubleshooting
+
+**Completions not working:**
+1. Ensure `fpath` includes your completions directory:
+   ```bash
+   echo $fpath
+   ```
+
+2. Verify the completion function is loaded:
+   ```bash
+   which _zone
+   ```
+
+3. Rebuild completion cache:
+   ```bash
+   rm -f ~/.zcompdump && exec zsh
+   ```
+
+**Completions are outdated:**
+```bash
+# Force rebuild
+rm -f ~/.zcompdump*
+compinit
+```

data/completions/_zone

@@ -0,0 +1,89 @@
+#compdef zone
+
+# Zsh completion script for zone
+# https://github.com/anthropics/zone
+
+_zone() {
+  local context state state_descr line
+  typeset -A opt_args
+
+  local -a output_formats timezones_opts data_opts other_opts
+
+  output_formats=(
+    '(--pretty --unix --strftime)--iso8601[Output in ISO 8601 format (default)]'
+    '(--iso8601 --unix --strftime)-p[Output in pretty format]'
+    '(--iso8601 --unix --strftime)--pretty[Output in pretty format (e.g., "Jan 02 - 03:04 PM")]'
+    '(--iso8601 --pretty --strftime)--unix[Output as Unix timestamp]'
+    '(--iso8601 --pretty --unix)-f[Output format using strftime]:format string'
+    '(--iso8601 --pretty --unix)--strftime[Output format using strftime]:format string'
+  )
+
+  timezones_opts=(
+    '--require[Require external library]:library name'
+    '(-z --utc --local)-z[Convert to specified timezone]:timezone:_zone_timezones'
+    '(-z --utc --local)--zone[Convert to specified timezone]:timezone:_zone_timezones'
+    '(-z --zone --local)--utc[Convert to UTC timezone]'
+    '(-z --zone --utc)--local[Convert to local timezone]'
+  )
+
+  data_opts=(
+    '(-F)-F[Field index or field name]:field:(1 2 3 4 5)'
+    '(-F)--field[Field index or field name]:field:(1 2 3 4 5)'
+    '(-d)-d[Field delimiter]:delimiter'
+    '(-d)--delimiter[Field delimiter]:delimiter'
+    '--headers[Treat first line as headers]'
+  )
+
+  other_opts=(
+    '(-v)'{-v,--verbose}'[Enable verbose/debug output]'
+    '(-h)'{-h,--help}'[Show help message]'
+  )
+
+  _arguments -C -s \
+    $output_formats \
+    $timezones_opts \
+    $data_opts \
+    $other_opts \
+    '*:timestamp string:_zone_timestamp'
+}
+
+_zone_timezones() {
+  local -a timezones
+
+  # Common timezones for quick completion
+  timezones=(
+    'UTC:Coordinated Universal Time'
+    'local:Local system timezone'
+    'America/New_York:Eastern Time'
+    'America/Chicago:Central Time'
+    'America/Denver:Mountain Time'
+    'America/Los_Angeles:Pacific Time'
+    'Europe/London:British Time'
+    'Europe/Paris:Central European Time'
+    'Asia/Tokyo:Japan Standard Time'
+    'Asia/Shanghai:China Standard Time'
+    'Australia/Sydney:Australian Eastern Time'
+  )
+
+  _describe -t timezones 'timezone' timezones
+
+  # Also allow arbitrary timezone input
+  _message -r 'timezone name or fuzzy match'
+}
+
+_zone_timestamp() {
+  # Suggest common timestamp formats
+  local -a formats
+  formats=(
+    'now:Current time'
+    '$(date):Current date/time from date command'
+    '2025-01-15T10:30:00Z:ISO 8601 format'
+    '1736937000:Unix timestamp (seconds)'
+    '"5 minutes ago":Relative time'
+    '"1 hour from now":Relative future time'
+  )
+
+  _describe -t formats 'timestamp format' formats
+}
+
+_zone "$@"

data/docs/user-experience-review.md

@@ -0,0 +1,150 @@
+# User Experience Review of Zone
+
+## My Thoughts on Zone as a User
+
+### What Zone Does Really Well
+
+**1. Solves a Real Pain Point**
+Timezone conversion is genuinely annoying. Looking at `2025-01-15T10:30:00Z` in logs and mentally calculating "what time was that for me?" is cognitive overhead. Zone eliminates that instantly. The name is perfect - simple, memorable, and describes exactly what it does.
+
+**2. The Dual-Mode Architecture is Brilliant**
+The pattern/field mode split is exactly right:
+- **Pattern mode** feels like `bat` for timestamps - magical and effortless. Just pipe text through and timestamps become readable. No configuration needed.
+- **Field mode** handles the structured data case without polluting the simple case with complexity.
+
+Requiring explicit `--field` AND `--delimiter` was the right call. Auto-detection adds complexity and surprising behavior. Explicit is better.
+
+**3. The New Defaults are Perfect**
+Before: `zone "2025-01-15T10:30:00Z"` → `2025-01-15T10:30:00Z` (no visible change)
+After: `zone "2025-01-15T10:30:00Z"` → `Jan 15, 2025 - 5:30 AM EST` (immediate value)
+
+This is *excellent* UX design. New users see the tool working immediately. The "principle of least surprise" - of course I want my local time, that's why I'm using a timezone tool!
+
+**4. Idempotency is Underrated**
+Being able to pipe zone output back through zone is surprisingly powerful. It means zone becomes composable - you can chain transformations without worrying about format compatibility. This is Unix philosophy done right.
+
+**5. The Three Pretty Formats are Well-Chosen**
+- `-p 1`: North American default, maximum readability
+- `-p 2`: International/technical users, 24-hour
+- `-p 3`: Sortable, machine-friendly but still readable
+
+The progression makes sense and covers real use cases without format proliferation.
+
+### What Could Be Even Better
+
+**1. Discovery of Pretty Format Variants**
+Running `zone --help` shows:
+```
+-p, --pretty [STYLE]     Pretty format (1=12hr, 2=24hr, 3=ISO-compact, default: 1)
+```
+
+This is compact but not discoverable. A user has to know to try `-p 2` to see what it looks like. Could consider:
+- Showing example output in `--help` for each format
+- Or: `zone --formats` command that prints all format examples
+
+**2. Relative Time Parsing Feels Incomplete**
+Zone parses "5 hours ago" but the pattern doesn't match common formats like:
+- "2 hours ago" (GitHub, Twitter, etc.)
+- "in 3 days" (Google Calendar)
+- "yesterday" / "tomorrow"
+
+Either commit fully to natural language parsing (integrate with `chronic` gem?) or remove it entirely. Half-done features are confusing.
+
+**3. Color Choice is Good but Could Be Configurable**
+Cyan for timestamps is reasonable, but some users might want:
+- Different colors for different timezones (red=past, green=future)
+- Bold instead of color
+- User-configurable via env var
+
+Not critical, but would be nice for power users.
+
+**4. Error Messages Could Be More Helpful**
+```bash
+$ echo "invalid" | zone --field 2 --delimiter ','
+Error: Could not parse time 'invalid'
+```
+
+Could suggest: "Does not look like a timestamp. Expected formats: ISO8601, Unix timestamp, etc."
+
+**5. The Name "Pretty" Format**
+Calling it "pretty" format is subjective. Some users might think ISO8601 is "pretty" (it's certainly more standardized). Consider:
+- "human" format (human-readable)
+- "readable" format
+- Just "format 1/2/3" without the "pretty" label
+
+Minor bikeshedding, but naming matters.
+
+### Outstanding Design Decisions
+
+**1. No Magic, Clear Contracts**
+- Field mode requires explicit delimiter ✓
+- Pattern mode is clearly the default ✓
+- Flags do one thing ✓
+
+No surprises, no hidden behavior.
+
+**2. Fuzzy Timezone Matching**
+```bash
+zone --zone tokyo    # Just works
+zone --zone pacific  # Just works
+zone --zone "new york"  # Just works
+```
+
+This is *delightful*. Makes the tool feel intelligent without being magical.
+
+**3. No External Dependencies (Base)**
+Pure Ruby stdlib (until you `--require active_support`). Fast startup, easy installation, no surprises.
+
+**4. The Pattern Numbering System (P01_, P02_)**
+This is clever engineering:
+- Easy to add new patterns (just add P08_)
+- Priority is explicit and visible
+- Self-documenting code
+
+Really nice.
+
+### Use Cases Where Zone Shines
+
+1. **Log Analysis**: `tail -f app.log | zone` - instant readability
+2. **API Development**: Converting timestamps in JSON responses during debugging
+3. **Data Migration**: Converting CSV/TSV timestamp columns
+4. **Slack/IRC Bots**: Processing messages with embedded timestamps
+5. **International Teams**: Converting meeting times across timezones
+
+### Competitive Analysis
+
+**vs `date` command**: Zone is *way* easier for interactive use. Compare:
+```bash
+# date
+date -d "2025-01-15T10:30:00Z" "+%b %d, %Y - %I:%M %p %Z"
+
+# zone
+zone "2025-01-15T10:30:00Z"
+```
+
+Zone wins on ergonomics by a mile.
+
+**vs `dateutils`**: More powerful but also more complex. Zone targets the 80% use case perfectly.
+
+**vs Online Converters**: Zone works offline, in pipelines, is automatable. Different category.
+
+### Final Verdict
+
+Zone is a **10/10 tool for its intended use case**. It's:
+- Simple enough for beginners (just type `zone` with a timestamp)
+- Powerful enough for experts (field mode, regex delimiters, chaining)
+- Well-documented
+- Follows Unix philosophy
+- Actually useful in daily work
+
+The recent changes (colors, pretty formats, better defaults) transformed it from "neat utility" to "essential tool I'd add to every machine."
+
+### One More Thing
+
+The pattern mode really feels like magic the first time you use it:
+```bash
+echo "Server started at 1736937000 and crashed at 1736940600" | zone
+# Server started at Jan 15, 2025 - 5:30 AM EST and crashed at Jan 15, 2025 - 6:30 AM EST
+```
+
+That's the kind of "just works" experience that makes a tool memorable. Well done.

data/exe/zone

@@ -2,269 +2,6 @@
 
 # frozen_string_literal: true
 
-require 'rubygems'
-require 'logger'
-require 'optparse'
-require 'tzinfo'
-require 'time'
-require 'date'
+require_relative '../lib/zone'
 
-options = { delimiter: nil, strftime: nil, iso8601: false, pretty: false, headers: false, unix: false, index: 1, zone: nil, utc: false, local: false }
-parser = OptionParser.new do |parser|
-  parser.banner = "Usage: zone [options] [timestamps...]"
-  parser.separator ""
-  parser.separator "Output Formats:"
-  parser.on '--iso8601', 'Output in ISO 8601 (default: true)'
-  parser.on '--strftime FORMAT', '-f', 'Output format using strftime (default: none)'
-  parser.on '--pretty', 'Output in pretty format (e.g., "Jan 02 - 03:04 PM")'
-  parser.on '--unix', 'Output as Unix timestamp (default: false)'
-  
-  parser.separator ""
-  parser.separator "Timezones:"
-  parser.on '--zone TZ', 'Convert to time zone (default: local time zone)'
-  parser.on '--local', 'Convert to local time zone (alias for --zone local)'
-  parser.on '--utc', 'Convert to UTC time zone (alias for --zone UTC)'
-  
-  parser.separator ""
-  parser.separator "Data Processing:"
-  parser.on '--index N', '-i N', Integer, 'Index of the field to convert (default: 1)'
-  parser.on '--delimiter PATTERN', '-d', 'Field delimiter (default: space)'
-  parser.on '--headers', 'Skip the first line as headers'
-  
-  parser.separator ""
-  parser.separator "Other:"
-  parser.on '--verbose', '-v', 'Enable verbose/debug output'
-  parser.on '--help', '-h', 'Show this help message' do
-    puts parser
-    exit
-  end
-end
-
-parser.parse!(into: options)
-
-COLORS = {
-  reset: "\e[0m",
-  bold: "\e[1m",
-  cyan: "\e[36m",
-  yellow: "\e[33m",
-  red: "\e[31m",
-  gray: "\e[90m"
-}
-
-$logger = Logger.new($stderr).tap do |l|
-  l.formatter = ->(severity, _datetime, _progname, message) {
-    color = case severity
-    when "INFO"  then COLORS[:cyan]
-    when "WARN"  then COLORS[:yellow]
-    when "ERROR" then COLORS[:red]
-    else COLORS[:gray]
-    end
-    
-    prefix = case severity
-    when "INFO"  then "→"
-    when "WARN"  then "⚠"
-    when "ERROR" then "✗"
-    else "·"
-    end
-    
-    "#{color}#{prefix} #{message}#{COLORS[:reset]}\n"
-  }
-  l.level = options.delete(:verbose) ? Logger::INFO : Logger::WARN
-end
-
-format = (
-  case options
-  in { strftime: nil, iso8601: true, unix: false, pretty: false } then :iso8601
-  in { strftime: nil, iso8601: false, unix: true, pretty: false } then :unix
-  in { strftime: String, iso8601: false, unix: false, pretty: false } then :strftime
-  in { strftime: nil, iso8601: false, unix: false, pretty: true } then :pretty
-  in { strftime: nil, iso8601: false, unix: false, pretty: false } then  :iso8601
-  else
-    $logger.error 'Error: Only one of --strftime, --iso8601, or --unix can be specified.'
-    exit 1
-  end
-)
-
-zone = (
-  case options
-  in { utc: true, local: false, zone: nil } then 'utc'
-  in { utc: false, local: true, zone: nil } then 'local'
-  in { zone: nil, utc: false, local: false } then 'utc'
-  in { zone: String => z, utc: false, local: false } then z
-  else
-    $logger.error 'Error: Only one of --zone, --local, or --utc can be specified.'
-    exit 1
-  end
-)
-
-class TimezoneSearch
-  attr_reader :keyword, :debug
-
-  def self.all_zones
-    TZInfo::Timezone.all_identifiers
-  end
-
-  def initialize(
-    keyword, 
-    debug: false, 
-    logger: $logger || Logger.new($stderr)
-  )
-    @keyword = keyword
-    @debug = debug
-    @logger = logger
-  end
-
-  def execute
-    begin
-      TZInfo::Timezone.get(keyword)
-    rescue TZInfo::InvalidTimezoneIdentifier
-      search_wildcard
-    end
-  end
-
-  def us_wildcard
-    keyword
-    .gsub(/^(?:US)?\/?/, 'US/')
-    .gsub(/$/,'.*')
-    .then { Regexp.new(it, Regexp::IGNORECASE) }
-  end
-
-  def all_wildcard
-    Regexp.new(".*#{keyword}.*", Regexp::IGNORECASE)
-  end
-
-  def search_wildcard
-    case self.class.all_zones
-    in [*, ^(us_wildcard) => found_zone, *]
-    in [*, ^(all_wildcard) => found_zone, *]
-    else nil
-    end
-
-    return unless found_zone
-
-    TZInfo::Timezone.get(found_zone).tap do
-      @logger.info "Using time zone '#{found_zone}' matching pattern '#{@keyword}'."
-    end
-  end
-
-  private
-
-  def log(message)
-    warn message if @debug
-  end
-end
-
-zone_callables = Hash.new do |hash, key|
-  hash[key] = ->(time) { 
-    search = TimezoneSearch.new(key)
-    if zone = search.execute
-      zone.to_local(time)
-    else
-      $logger.warn "Error: Invalid time zone identifier '#{key}'."
-      time
-    end
-  }
-end
-
-zone_callables.merge!(
-  'utc' => ->(t) { t.utc },
-  'local' => ->(t) { t.localtime },
-  'UTC' => ->(t) { t.utc },
-)
-
-actual_index = options[:index] - 1
-zone_callable = zone_callables[zone]
-
-# Detect if args are timestamps (not filenames)
-timestamps = []
-if ARGV.any? && ARGV.all? { |arg| arg.match?(/^\d/) || arg.match?(/[A-Z][a-z]{2}/) || arg.match?(/:/) }
-  $logger.info "Treating arguments as timestamp strings."
-  timestamps = ARGV.dup
-  ARGV.clear  # Clear so ARGF will read from STDIN if piped
-end
-
-# Build input enumerable
-input = (
-  if timestamps.any?
-    timestamps.each
-  elsif ARGV.any? || !STDIN.tty?
-    ARGF.each_line(chomp: true)
-  else
-    [Time.now.to_s].each
-  end
-)
-
-input.each do |line|
-  case [options, $.]
-  in { headers: true }, 1 then next
-  in { delimiter: String => delimiter }
-  in { delimiter: nil }
-    $logger.info "Auto-detecting delimiter for line: #{line.inspect}"
-    options[:delimiter] = (
-      case line
-      in /,\s*/
-        $logger.info "Using comma with whitespace as delimiter."
-        /,\s*/
-      in /\t/
-        $logger.info "Using tab as delimiter."
-        "\t"
-      in /,/
-        $logger.info "Using comma as delimiter."
-        ','
-      else
-        $logger.info "Could not detect delimiter. Using whitespace."
-        /\s+/
-      end
-    )
-  else
-    ""
-  end
-
-  delimiter = options[:delimiter] || ""
-  
-  fields = (
-    case [line, delimiter]
-    in String, "" then [line]
-    in String, /^.+$/ then line.split(delimiter) 
-    else [line]
-    end
-   )
-
-  target = fields[actual_index]
-
-  time = (
-    begin
-      case target
-      in Time then target
-      in DateTime then target.to_time
-      in Date then target.to_time
-      in /^[0-9\.]+$/
-        Time.at(target.to_f)
-      else
-        DateTime.parse(target).to_time
-      end
-    rescue StandardError => e
-      $logger.warn "Warning: Could not parse time '#{target}'. Skipping line."
-      $logger.warn "  #{e.class}: #{e.message}"
-      next
-    end
-  )
-  
-  converted = zone_callable.call(time)
-  formatted = (
-    case format
-    in :pretty
-      if (Time.now - converted).abs > 30 * 24 * 60 * 60
-        converted.strftime("%b %d, %Y - %I:%M %p %Z")
-      else
-        converted.strftime("%b %d - %I:%M %p %Z")
-      end
-    in :strftime then converted.strftime(options[:strftime])
-    in :iso8601 then converted.iso8601
-    in :unix then converted.to_i
-    end
-  )
-
-  fields[actual_index] = formatted
-  puts fields.join(delimiter)
-end
+Zone::CLI.run(ARGV)

data/lib/zone/cli.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'options'
+require_relative 'input'
+require_relative 'output'
+require_relative 'transform'
+require_relative 'colors'
+require_relative 'logging'
+require_relative 'pattern'
+require_relative 'field'
+
+module Zone
+  class CLI
+    def self.run(argv)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv = argv
+    end
+
+    def run
+      options = Options.new
+      options.parse!(@argv)
+      options.validate!
+
+      setup_logger!(options.verbose)
+      setup_active_support!
+
+      input = Input.new(@argv)
+      output = Output.new(color_mode: options.color)
+      transformation = Transform.build(zone: options.zone, format: options.format)
+
+      if options.field
+        Field.process(input, output, transformation, options, @logger)
+      else
+        Pattern.process(input, output, transformation, @logger)
+      end
+    rescue OptionParser::MissingArgument, OptionParser::InvalidOption, OptionParser::InvalidArgument => e
+      $stderr.puts Colors.colors($stderr).red("Error:") + " #{e.message}"
+      $stderr.puts "Run 'zone --help' for usage information."
+      exit 1
+    rescue ArgumentError, StandardError => e
+      message = e.message.gsub(/'([^']+)'/) do
+        "'#{Colors.colors($stderr).bold($1)}'"
+      end
+      $stderr.puts Colors.colors($stderr).red("Error:") + " #{message}"
+      exit 1
+    end
+
+    private
+
+    def setup_logger!(verbose)
+      @logger = Logging.build(verbose: verbose)
+    end
+
+    def setup_active_support!
+      if defined?(ActiveSupport)
+        ActiveSupport.to_time_preserves_timezone = true
+      end
+    end
+
+  end
+end