lux-hammer 0.3.13 → 0.3.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 411174afd97cefbe9e7e3309c25233f465b9458ee0dc710e67077725658876c0
-  data.tar.gz: f4b64f7897fd8c67412fdbe418ad51b96eeac1ebb3e87ce9df5b97651a4a9ff6
+  metadata.gz: a61994d8f82b575a019cfb1171935b334b840cdb5561fcc56e9ba2c141a314d2
+  data.tar.gz: a4d4d730c830b4d30de13dc9e0c27e9cc2fa3902c9297154d4fe81ba5365fe94
 SHA512:
-  metadata.gz: ba1364fcff70fefa529a2e7586ee33f7826b43ee7cd3ebd5e454f0bce82131b427cf320d85d8d911edc3a11762196de7db9964c6877959548eb4c6753e5ac063
-  data.tar.gz: 5b21c08ac766b1af02b1a0d49b7fb3129fffd94b0c13fd07c7a5995851c21447e6a437848f25ef30f364bfccb94f1bac51046630dbbd574aaa109a61a738e893
+  metadata.gz: 0e4c0a5f1fbf47550df2929670e647cf7e1e390e7b3aab0b71932dc5f9557295953c39cdf9fafc6ac719d53b94ed14058bd1a2bb32bcaf9bb79ff3b2198fee16
+  data.tar.gz: b0012fd33259c5ea63af2d3ea0040c4a618292042f842dbda523f462d90fbc9138c04217c3c86a7d52fd56a6b650249ab2dd9bb6f070e1f1a24497ab68e6dbe2

data/.version

@@ -1 +1 @@
-0.3.13
+0.3.15

data/AGENTS.md

@@ -41,6 +41,9 @@ lib/hammer/shell.rb         # ANSI/IO helpers
 lib/hammer/option.rb        # One option definition
 lib/hammer/parser.rb        # ARGV -> [positional, opts_hash]
 lib/hammer/command.rb       # One registered command (name, opts, alts, handler)
+lib/hammer/cron.rb          # `cron '<expr>'` schedule parser (cron/interval/@shortcut)
+lib/hammer/cron_server.rb   # `h:cron` job server (scheduler, logs, state; lazy-loaded)
+lib/hammer/cron_web.rb      # job server web UI (stdlib TCPServer; lazy-loaded)
 lib/hammer/loader.rb        # `*_hammer.rb` fragment loader (auto/glob/file)
 lib/hammer/builder.rb       # Block-DSL context (Hammerfile / Hammer.run)
 lib/hammer/command_builder.rb # `task :name do ... end` context
@@ -54,6 +57,8 @@ test/option_test.rb         # Option declaration / casting
 test/command_test.rb        # Command data type
 test/shell_test.rb          # ANSI / IO helpers
 test/cli_test.rb            # `hammer` binary end-to-end
+test/cron_test.rb           # schedule parser (matches?/due?/next_run)
+test/cron_server_test.rb    # job discovery, state, rotation, web UI
 examples/Hammerfile         # Reference Hammerfile
 examples/class_dsl.rb       # Reference class DSL usage
 examples/block_dsl.rb       # Reference block DSL usage
@@ -73,11 +78,18 @@ Inside a `task :name do ... end` block (CommandBuilder context):
   resolved against root (same lookup as `hammer`), deduped per
   top-level `start` so each prereq fires at most once. Dedupe also
   spans `+`-chained segments. Unknown prereq raises `Hammer::Error`.
+* `cron '<expr>'` - schedule for the `h:cron` job server. Accepts
+  5-field cron (`'*/10 * * * *'`), an interval (`'10s'`, `'10m'`,
+  `'2h'`, `'1d'`, counted from the last run) or `@hourly` / `@daily` /
+  `@weekly` / `@monthly`. Parsed eagerly (`Hammer::Cron.new`) so an invalid
+  expression raises `Hammer::Error` at definition time. Stored on the
+  Command (`cmd.cron` raw string, `cmd.cron_schedule` parsed), exported
+  by `h:json`, shown in per-command help.
 * `proc do |opts| ... end` - **the last expression**, becomes handler
 
 At class scope (for `def`-style commands):
 
-* `desc`, `example`, `opt`, `alt`, `needs` set pending state
+* `desc`, `example`, `opt`, `alt`, `needs`, `cron` set pending state
 * The next `def` consumes the pending state IF `desc` was set; otherwise
   the method is treated as a plain helper
 * Methods with arity 0 are called without opts; methods that take an arg
@@ -249,7 +261,7 @@ reserved `h:` namespace.
 
 * Root: `:default` (hidden, carries `--version` / `-v`).
 * `h:` namespace: `h:help`, `h:update`, `h:agents`, `h:version`,
-  `h:recipes`, `h:init`.
+  `h:recipes`, `h:init`, `h:json`, `h:cron`.
 
 `h:` is the reserved built-in namespace - keeping the tool-meta commands
 there means they never collide with a project's root tasks, so there's
@@ -279,6 +291,32 @@ Task contracts:
   forward flags through). Bare invocation lists.
 * `h:init` - writes `Hammer::STARTER_HAMMERFILE` to `./Hammerfile`;
   refuses if one exists.
+* `h:json` - `puts JSON` of `root.export_spec` (tasks grouped exactly
+  like the bare listing via `section_for`, root group keyed `__root`).
+  `--all` keeps the `h:` tree, `--compact` minifies.
+* `h:cron` - foreground job server for tasks with a `cron` schedule.
+  Lazy-requires `hammer/cron_server`. Ticks each minute (each second
+  when any job has a sub-minute interval); every due job
+  runs in a fresh subprocess (`hammer ns:task`, env `HAMMER_QUIET=1
+  NO_COLOR=1`, stdin closed, chdir to the Hammerfile dir), stdout+stderr
+  appended to `log/hammer/<slug>.log` (`:` -> `-`; rotated to `.log.1`
+  past 1 MB, max 2 files). Last runs persist in
+  `tmp/hammer/cron.state.json` (atomic tmp+rename) so restarts don't
+  re-fire; a live pid recorded there blocks a second instance.
+  Running state persists too: each active run's child pid is saved, and
+  on restart a still-alive orphan is restored as `running` (a watcher
+  polls until it exits; the overlap guard keeps skipping), while a dead
+  one becomes status `unknown` (exit status lost) instead of a stale
+  `running`. Overlapping runs of the same job are skipped, never
+  queued. Web UI on
+  `127.0.0.1` only (default port 4267, hand-rolled HTTP in
+  `hammer/cron_web.rb` - no webrick, keep it dependency-free): jobs
+  table, per-job log tail, POST run-now, `/json` status. Flags:
+  `--port`, `--pass` (HTTP basic auth on every route, any username,
+  constant-time compare; falls back to `HAMMER_CRON_PASS` env),
+  `--list` (print jobs + next runs, exit), `--service` (print launchd
+  plist / systemd unit, carries `--pass` when set, install hints on
+  stderr).
 
 The `:default` task and the `help` / `-h` / `--help` requests are
 invoked via `run_command(cmd, argv, full: name, quiet: true)` - the

data/README.md

@@ -562,6 +562,13 @@ Under the `h:` namespace:
 * `h:version` - print the lux-hammer version.
 * `h:recipes` - list / install / show / edit recipes.
 * `h:init` - write a starter Hammerfile in cwd (refuses if one exists).
+* `h:json` - dump the CLI definition as JSON (tasks grouped like the
+  bare listing, with desc/options/examples/aliases/needs/cron); `--all`
+  includes the `h:` tasks, `--compact` minifies. Output is plain stdout
+  (the run banner goes to stderr), so `hammer h:json | jq` just works.
+* `h:cron` - job server: runs every task that declares a
+  `cron '<expr>'` schedule, with a localhost web UI for status and
+  logs. See [Cron / job server](#cron--job-server).
 
 Each is guarded by `unless commands.key?` within the namespace, so you
 can override one by reopening `namespace :h` in your Hammerfile.
@@ -574,6 +581,16 @@ hammer --system h:recipes              # list recipes, ignoring any local Hammer
 hammer --system h:recipes --install srt ~/bin/srt
 ```
 
+`--gui` opens a native macOS window for the current project: a sidebar of
+your tasks (grouped like the listing), a form per task built from its
+options, and a Run button that streams the task's output. It reads the
+project via `h:json` and runs each task as a `hammer <path> ...`
+subprocess. macOS / arm64 only.
+
+```sh
+hammer --gui                           # open the runner for the nearest Hammerfile
+```
+
 Customize bare `hammer` by replacing `:default`:
 
 ```ruby
@@ -611,6 +628,101 @@ end
 `-h` / `--help` stay reserved on every command - you can't shadow them
 with an `opt`.
 
+## Cron / job server
+
+Any task can declare a schedule with `cron`; `hammer h:cron` then runs
+those tasks on time, like a project-local crontab with a web UI:
+
+```ruby
+task :backup do
+  desc 'Snapshot the database'
+  cron '@daily'                    # 00:00 every day
+  proc { |_| sh 'bin/backup' }
+end
+
+namespace :cache do
+  task :warm do
+    desc 'Refresh hot caches'
+    cron '10m'                     # every 10 minutes
+    proc { |_| sh 'bin/warm-cache' }
+  end
+end
+```
+
+Accepted schedule forms:
+
+| form | example | meaning |
+|---|---|---|
+| 5-field cron | `*/10 * * * *` | standard crontab (`min hour dom mon dow`) |
+| interval | `10s`, `10m`, `2h`, `1d` | every N seconds/minutes/hours/days, counted from the last run |
+| shortcut | `@hourly`, `@daily`, `@weekly`, `@monthly` | expands to the cron equivalent |
+
+Careful with raw cron fields: `10 * * * *` means "minute 10 of every
+hour", not "every 10 minutes" - that's `*/10 * * * *`, or just `10m`.
+Cron fields support `*`, `a`, `a-b`, `*/n`, `a-b/n` and comma lists
+(numeric values only). Weekday `7` equals `0` (Sunday). Intervals are
+not clock-aligned, so odd periods like `90m` work; a job that never ran
+fires on the server's first tick. The scheduler ticks once per minute,
+or once per second when any job declares a sub-minute interval.
+Invalid expressions fail at Hammerfile load, not at runtime.
+
+Run the server:
+
+```sh
+hammer h:cron                      # scheduler + web UI, Ctrl-C to stop
+hammer h:cron --port=7777          # UI on another port (default 4267)
+hammer h:cron --list               # print jobs + next runs, then exit
+```
+
+The web UI at `http://127.0.0.1:4267` (localhost only, never a public
+interface) lists every job with its schedule, last/next run, status and
+duration, shows per-job logs, and has a "run now" button for manual
+triggers. `GET /json` serves the same status for scripting.
+
+On a shared machine, protect the UI with HTTP basic auth - useful since
+"run now" executes tasks:
+
+```sh
+hammer h:cron --pass=secret        # or: HAMMER_CRON_PASS=secret hammer h:cron
+curl -u :secret http://127.0.0.1:4267/json   # any username, password checked
+```
+
+Prefer the `HAMMER_CRON_PASS` env var when other users can read your
+process list (`ps` shows flag values). A `--service` unit generated
+while `--pass` is set carries the flag along, so keep that file private.
+Note this is plain HTTP - credentials are encoded, not encrypted; for
+anything beyond localhost put a TLS proxy in front.
+
+Each run executes in a fresh subprocess (`hammer ns:task` - same
+isolation as the GUI runner), through the full normal pipeline: Bundler,
+dotenv, `before` hooks, `needs`. Output goes to a per-job log:
+
+```
+log/hammer/backup.log              # current log (db:backup -> db-backup.log)
+log/hammer/backup.log.1            # previous, rotated past 1 MB - max 2 files
+tmp/hammer/cron.state.json         # last runs + server pid, survives restarts
+```
+
+You probably want `log/hammer/` and `tmp/hammer/` in `.gitignore`.
+
+Overlap policy: if a run is still going when the next one comes due,
+the new run is skipped (noted in the job log) - jobs never pile up.
+Because last runs persist in the state file, a restart neither re-fires
+jobs nor resets interval clocks, and a second `h:cron` for the same
+project refuses to start while one is already running. Running state
+survives restarts too: a job whose subprocess outlived a server crash
+is picked up again as `running` (no double-start), and one that died
+with the server shows `unknown` rather than a stale `running`.
+
+To keep it running supervised, `--service` prints a ready-to-save
+launchd plist (macOS) or systemd user unit (linux) - it only prints,
+installing is up to you:
+
+```sh
+hammer h:cron --service > ~/.config/systemd/user/hammer-cron.service
+systemctl --user enable --now hammer-cron
+```
+
 ## Prereqs (`needs`)
 
 Declare commands that must run before this one (Rake-style task deps):

data/bin/hammer

@@ -23,5 +23,15 @@ if File.exist?('Gemfile') && !defined?(Bundler)
 end
 
 require 'lux-hammer'
+
+# `hammer --dir` prints the gem root of the lux-hammer that actually loaded
+# (repo checkout or installed gem). Lets recipes locate the lib without
+# hardcoding a path: require File.join(`hammer --dir`.chomp, 'lib/lux-hammer')
+if ARGV.first == '--dir'
+  lib = $LOADED_FEATURES.grep(%r{/lux-hammer\.rb$}).last
+  puts File.expand_path('../..', lib)   # lib/lux-hammer.rb -> gem root
+  exit
+end
+
 Hammer.cli(ARGV)
 

data/gui/Hammer.app/Contents/Info.plist

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key><string>Hammer</string>
+  <key>CFBundleDisplayName</key><string>Hammer</string>
+  <key>CFBundleIdentifier</key><string>com.lux-hammer.gui</string>
+  <key>CFBundleVersion</key><string>1</string>
+  <key>CFBundleShortVersionString</key><string>1.0</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleExecutable</key><string>HammerGUI</string>
+  <key>LSMinimumSystemVersion</key><string>11.0</string>
+  <key>NSHighResolutionCapable</key><true/>
+  <key>NSPrincipalClass</key><string>NSApplication</string>
+</dict>
+</plist>

data/lib/hammer/builtins.rb

@@ -31,6 +31,8 @@ class Hammer
       register_version(h) unless h.commands.key?('version')
       register_recipes(h) unless h.commands.key?('recipes')
       register_init(h)    unless h.commands.key?('init')
+      register_json(h)    unless h.commands.key?('json')
+      register_cron(h)    unless h.commands.key?('cron')
     end
 
     def register_help(klass)
@@ -112,6 +114,72 @@ class Hammer
       end
     end
 
+    # The job server: runs every task that declares `cron '<expr>'` on
+    # its schedule, in the foreground, with a localhost web UI for
+    # status, logs and manual triggers. Per-job logs land in log/hammer/
+    # (rotated at 1 MB, max 2 files), state in tmp/hammer/cron.state.json.
+    def register_cron(klass)
+      klass.class_eval do
+        task :cron do
+          desc <<~TXT
+            Job server: run tasks that declare a `cron '<expr>'` schedule.
+
+            Runs in the foreground (Ctrl-C to stop) with a web UI on
+            localhost for job status, per-job logs and manual runs. Use
+            --service to print a launchd plist / systemd unit and let the
+            OS supervise it.
+          TXT
+          example 'h:cron'
+          example 'h:cron --port=7777'
+          example 'h:cron --pass=secret'
+          example 'h:cron --list'
+          example 'h:cron --service > ~/.config/systemd/user/hammer-cron.service'
+          opt :port,    type: :integer, default: 4267, desc: 'web UI port (binds 127.0.0.1 only)'
+          opt :pass,    type: :string,  desc: 'HTTP basic-auth password for the web UI (or HAMMER_CRON_PASS env)'
+          opt :list,    type: :boolean, desc: 'print scheduled jobs + next runs, then exit'
+          opt :service, type: :boolean, desc: 'print a launchd plist (macOS) / systemd unit (linux)'
+          proc do |opts|
+            if self.class.root.instance_variable_get(:@no_hammerfile)
+              error "no Hammerfile found - h:cron needs a project with scheduled tasks"
+            end
+            require_relative 'cron_server'
+            server = Hammer::CronServer.new(self.class.root, port: opts[:port],
+                                            pass: opts[:pass] || ENV['HAMMER_CRON_PASS'])
+            if opts[:service]
+              server.print_service_unit
+            elsif opts[:list]
+              server.print_startup_summary
+            else
+              server.run!
+            end
+          end
+        end
+      end
+    end
+
+    def register_json(klass)
+      klass.class_eval do
+        task :json do
+          desc <<~TXT
+            Dump the CLI definition as JSON: tasks grouped exactly like
+            the bare-`hammer` listing, each with desc, options, examples,
+            aliases, needs. Consumed by the macOS GUI and any tooling
+            that wants the full Hammerfile spec.
+          TXT
+          example 'h:json'
+          example 'h:json --all       # include the reserved h: tasks'
+          example 'h:json --compact   # minified, single line'
+          opt :all,     type: :boolean, desc: 'include reserved built-in h: tasks'
+          opt :compact, type: :boolean, desc: 'minified JSON (default: pretty)'
+          proc do |opts|
+            require 'json'
+            spec = self.class.root.export_spec(include_builtins: opts[:all])
+            puts opts[:compact] ? JSON.generate(spec) : JSON.pretty_generate(spec)
+          end
+        end
+      end
+    end
+
     # `:recipes` rolls all recipe-management actions into one task. Bare
     # invocation lists; opts pick the action and positional args carry
     # the recipe name (and optional target path for --install). Run via

data/lib/hammer/command.rb

@@ -1,7 +1,7 @@
 class Hammer
   # A single registered command on a Hammer class.
   class Command
-    attr_reader :name, :desc, :options, :examples, :alts, :needs
+    attr_reader :name, :desc, :options, :examples, :alts, :needs, :cron
     attr_accessor :handler, :location, :prev_location
 
     def initialize(name:, desc: '', handler: nil)
@@ -35,6 +35,19 @@ class Hammer
       @needs << name.to_s
     end
 
+    # Store a `cron '<expr>'` schedule. The raw string is kept for
+    # display/export; parsing happens here so an invalid expression
+    # raises Hammer::Error at definition time, not when the job server
+    # starts. The parsed Hammer::Cron is what the scheduler consumes.
+    def set_cron(expr)
+      @cron_schedule = Hammer::Cron.new(expr)
+      @cron = @cron_schedule.source
+    end
+
+    def cron_schedule
+      @cron_schedule
+    end
+
     def matches?(name)
       name = name.to_s
       name == @name || @alts.include?(name)
@@ -63,6 +76,27 @@ class Hammer
       end
     end
 
+    # Structured form for JSON export (`h:json`). `path` is the full
+    # colon path supplied by the tree walk - a Command doesn't know its
+    # own namespace prefix. `hidden` follows the help rule: a task with
+    # no `desc` still dispatches but is hidden from listings.
+    def to_h(path = name)
+      {
+        name:      name,
+        path:      path,
+        desc:      desc,
+        brief:     brief,
+        hidden:    desc.empty?,
+        redefined: !prev_location.nil?,
+        location:  location,
+        alts:      alts,
+        needs:     needs,
+        cron:      cron,
+        examples:  examples,
+        options:   options.map(&:to_h)
+      }
+    end
+
     private
 
     def short_flag?(switch)

data/lib/hammer/command_builder.rb

@@ -26,5 +26,13 @@ class Hammer
     def needs(*names)
       names.each { |n| @cmd.add_need(n) }
     end
+
+    # Schedule this task for the `hammer h:cron` job server. Accepts a
+    # 5-field cron expression ('*/10 * * * *'), a simple interval ('10s',
+    # '10m', '2h', '1d') or a shortcut (@hourly, @daily, @weekly,
+    # @monthly). Validated immediately, so a typo fails at Hammerfile load.
+    def cron(expr)
+      @cmd.set_cron(expr)
+    end
   end
 end

data/lib/hammer/cron.rb

@@ -0,0 +1,151 @@
+class Hammer
+  # Schedule of a task declared with `cron '<expr>'`. Parses the
+  # expression once (at Hammerfile eval, so typos fail at load time) and
+  # answers the scheduler's questions: does this wall-clock minute match,
+  # is a run due given the last one, and when is the next run.
+  #
+  # Accepted forms:
+  #
+  #   cron '*/10 * * * *'   # standard 5-field crontab
+  #   cron '10m'            # simple interval: every 10 minutes
+  #   cron '10s' / '2h' / '1d'  # seconds / hours / days
+  #   cron '@daily'         # shortcut, expands to '0 0 * * *'
+  #
+  # Cron fields support '*', 'a', 'a-b', '*/n', 'a-b/n' and comma lists,
+  # numeric values only (no 'jan'/'mon' names). Weekday 7 equals 0
+  # (Sunday). Intervals are measured from the last run - not aligned to
+  # the clock - which makes odd periods like '90m' possible and keeps
+  # restarts from re-firing (last run persists in the state file).
+  class Cron
+    SHORTCUTS ||= {
+      '@hourly'  => '0 * * * *',
+      '@daily'   => '0 0 * * *',
+      '@weekly'  => '0 0 * * 0',
+      '@monthly' => '0 0 1 * *'
+    }.freeze
+
+    # [name, min, max] per cron field, in crontab order.
+    FIELDS ||= [
+      [:minute, 0, 59], [:hour, 0, 23], [:day, 1, 31],
+      [:month, 1, 12], [:weekday, 0, 7]
+    ].freeze
+
+    INTERVAL_UNITS ||= { 's' => 1, 'm' => 60, 'h' => 3600, 'd' => 86_400 }.freeze
+
+    attr_reader :source, :interval
+
+    def initialize(expr)
+      @source = expr.to_s.strip
+
+      if (m = @source.match(/\A(\d+)([smhd])\z/))
+        @interval = m[1].to_i * INTERVAL_UNITS[m[2]]
+        raise Hammer::Error, "cron: interval must be > 0 in #{@source.inspect}" if @interval.zero?
+        return
+      end
+
+      if @source.start_with?('@') && !SHORTCUTS.key?(@source)
+        raise Hammer::Error, "cron: unknown shortcut #{@source.inspect} (valid: #{SHORTCUTS.keys.join(', ')})"
+      end
+
+      parts = (SHORTCUTS[@source] || @source).split(/\s+/)
+      unless parts.size == 5
+        raise Hammer::Error, "cron: #{@source.inspect} - expected 5 fields ('*/10 * * * *'), " \
+                             "an interval ('10s', '10m', '2h', '1d') or a shortcut (#{SHORTCUTS.keys.join(', ')})"
+      end
+
+      @fields   = FIELDS.each_with_index.map { |(name, lo, hi), i| parse_field(name, parts[i], lo, hi) }
+      @dom_star = parts[2] == '*'
+      @dow_star = parts[4] == '*'
+    end
+
+    def interval?
+      !@interval.nil?
+    end
+
+    # True when local wall-clock time `t` (minute resolution) matches the
+    # cron expression. Vixie-cron day rule: when BOTH day-of-month and
+    # day-of-week are restricted, matching either one is enough;
+    # otherwise both must match.
+    def matches?(t)
+      return false if interval?
+      min, hour, dom, mon, dow = @fields
+      return false unless min[t.min] && hour[t.hour] && mon[t.month]
+      dom_ok = dom[t.day]
+      dow_ok = dow[t.wday]
+      @dom_star || @dow_star ? dom_ok && dow_ok : dom_ok || dow_ok
+    end
+
+    # Should the scheduler fire at `tick` (a boundary-aligned Time),
+    # given the persisted last run? Cron mode fires once per matching
+    # minute; interval mode fires when a full interval has elapsed (or
+    # the job never ran, so a fresh job gives immediate feedback on the
+    # first tick).
+    def due?(tick, last_run)
+      if interval?
+        last_run.nil? || tick.to_i - last_run.to_i >= @interval
+      else
+        matches?(tick) && (last_run.nil? || last_run.to_i / 60 < tick.to_i / 60)
+      end
+    end
+
+    # Next fire time strictly after `from`. Cron mode walks minute by
+    # minute - real-world expressions match within days, and the walk is
+    # ~100 hash lookups per simulated minute - capped at 500 days so an
+    # impossible date (a Feb 30 style expression) fails loudly instead of
+    # spinning forever.
+    def next_run(from = Time.now, last_run: nil)
+      if interval?
+        return from if last_run.nil?
+        Time.at(last_run.to_i + @interval)
+      else
+        t = Time.at((from.to_i / 60 + 1) * 60)
+        (500 * 24 * 60).times do
+          return t if matches?(t)
+          t += 60
+        end
+        raise Hammer::Error, "cron: #{@source.inspect} never matches"
+      end
+    end
+
+    private
+
+    # Parse one crontab field into a {int => true} lookup hash. Each
+    # comma-separated item is '*', 'a', 'a-b', '*/n' or 'a-b/n'.
+    # Weekday 7 is folded into 0 - both mean Sunday.
+    def parse_field(name, part, lo, hi)
+      seen = {}
+      part.split(',', -1).each do |item|
+        base, step = item.split('/', 2)
+        step = step ? parse_int(name, step, 1, hi) : 1
+        a, b =
+          if base == '*'
+            [lo, hi]
+          elsif base.include?('-')
+            base.split('-', 2).map { |v| parse_int(name, v, lo, hi) }
+          elsif item.include?('/')
+            raise Hammer::Error, "cron: #{name} - step needs '*' or a range: #{item.inspect}"
+          else
+            v = parse_int(name, base, lo, hi)
+            [v, v]
+          end
+        raise Hammer::Error, "cron: #{name} - inverted range #{item.inspect}" if a > b
+        (a..b).step(step) { |v| seen[name == :weekday && v == 7 ? 0 : v] = true }
+      end
+      seen
+    end
+
+    # Strict integer within [lo, hi], or a Hammer::Error naming the field
+    # so the message points straight at the typo.
+    def parse_int(name, str, lo, hi)
+      v = begin
+        Integer(str, 10)
+      rescue ArgumentError, TypeError
+        nil
+      end
+      unless v && v.between?(lo, hi)
+        raise Hammer::Error, "cron: bad #{name} value #{str.inspect} (allowed #{lo}-#{hi})"
+      end
+      v
+    end
+  end
+end