lux-hammer 0.3.14 → 0.3.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ea304583caa18c45db8f340aecf5e08803f23eebe4f9152eefec7ac77c64b18
-  data.tar.gz: 72eafeef47b8ae8c2ff41e226756199f085865899532c3d7669dd5025c4b4019
+  metadata.gz: a61994d8f82b575a019cfb1171935b334b840cdb5561fcc56e9ba2c141a314d2
+  data.tar.gz: a4d4d730c830b4d30de13dc9e0c27e9cc2fa3902c9297154d4fe81ba5365fe94
 SHA512:
-  metadata.gz: 7cfa688c6d9d21acc72a6c8d614acefe2942746fb8b8b55f4f72fb08d9f1d37a6eccbd3326551348ea572889e3404790c4a59f64577d394f257e1ab826959c45
-  data.tar.gz: 535fb35b15ae31e9e861ad0ff32d9e216382b533cb877b12560185cd722724c0d01a0dde350facebf209178166d88c4109328e7882ba6a14ae0273eb111d2215
+  metadata.gz: 0e4c0a5f1fbf47550df2929670e647cf7e1e390e7b3aab0b71932dc5f9557295953c39cdf9fafc6ac719d53b94ed14058bd1a2bb32bcaf9bb79ff3b2198fee16
+  data.tar.gz: b0012fd33259c5ea63af2d3ea0040c4a618292042f842dbda523f462d90fbc9138c04217c3c86a7d52fd56a6b650249ab2dd9bb6f070e1f1a24497ab68e6dbe2

data/.version

@@ -1 +1 @@
-0.3.14
+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
@@ -282,6 +294,29 @@ Task contracts:
 * `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

@@ -563,9 +563,12 @@ Under the `h:` namespace:
 * `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); `--all`
+  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.
@@ -625,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/lib/hammer/builtins.rb

@@ -32,6 +32,7 @@ class Hammer
       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)
@@ -113,6 +114,49 @@ 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

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)
@@ -78,6 +91,7 @@ class Hammer
         location:  location,
         alts:      alts,
         needs:     needs,
+        cron:      cron,
         examples:  examples,
         options:   options.map(&:to_h)
       }

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

data/lib/hammer/cron_server.rb

@@ -0,0 +1,416 @@
+require 'json'
+require 'fileutils'
+
+class Hammer
+  # The `hammer h:cron` job server. Discovers every task that declares a
+  # `cron '<expr>'` schedule, ticks once per minute and runs each due job
+  # in its own subprocess (a fresh `hammer ns:task`, exactly like the
+  # macOS GUI runs tasks), streaming stdout+stderr into a per-job log.
+  # A small web UI (Hammer::CronWeb) serves job status and logs on
+  # localhost.
+  #
+  # On-disk layout, relative to the Hammerfile dir:
+  #
+  #   log/hammer/<slug>.log      current job log (db:backup -> db-backup.log)
+  #   log/hammer/<slug>.log.1    previous log, rotation keeps max 2 files
+  #   tmp/hammer/cron.state.json last-run timestamps + daemon pid/port
+  class CronServer
+    MAX_LOG_BYTES ||= 1_048_576   # rotate the job log past 1 MB
+
+    # One scheduled task. `pid` doubles as the running flag: nil when
+    # idle, :starting between due-check and spawn, then the child pid.
+    Job = Struct.new(:path, :command, :schedule, :last_run, :status,
+                     :exit_code, :duration, :pid, keyword_init: true) do
+      def running?
+        !pid.nil?
+      end
+
+      # Log-safe file name: 'db:backup' -> 'db-backup'.
+      def file_slug
+        path.tr(':', '-').gsub(/[^\w.-]/, '-')
+      end
+    end
+
+    attr_reader :jobs, :port, :root_dir
+
+    def initialize(root_klass, port:, pass: nil)
+      @root_dir   = Dir.pwd   # Hammer.cli already chdir-ed to the Hammerfile dir
+      @port       = port
+      @pass       = pass && !pass.to_s.empty? ? pass.to_s : nil
+      @hammer_bin = begin
+        File.realpath($PROGRAM_NAME)
+      rescue Errno::ENOENT
+        File.expand_path($PROGRAM_NAME)
+      end
+      @log_dir    = File.join(@root_dir, 'log/hammer')
+      @state_path = File.join(@root_dir, 'tmp/hammer/cron.state.json')
+      @mutex      = Mutex.new
+      @threads    = []
+
+      @jobs = {}
+      root_klass.each_command(include_builtins: false) do |path, cmd|
+        next unless cmd.cron
+        @jobs[path] = Job.new(path: path, command: cmd, schedule: cmd.cron_schedule)
+      end
+      if @jobs.empty?
+        raise Hammer::Error,
+              "no tasks declare a cron schedule - add `cron '*/10 * * * *'` (or '10m', '@daily') inside a task block"
+      end
+
+      load_state
+    end
+
+    # ----- foreground service --------------------------------------------
+
+    # Run scheduler + web UI until SIGINT/SIGTERM. Ticks on minute
+    # boundaries (or every second when a sub-minute interval job exists,
+    # see tick_step). The scheduler owns the main thread (so Ctrl-C
+    # lands in the thread that is sleeping); the HTTP accept loop runs
+    # in a background thread. Trap handlers only flip a flag - no IO or
+    # locking is allowed inside a trap.
+    def run!
+      ensure_single_instance!
+      @stop = false
+      trap('INT')  { @stop = true }
+      trap('TERM') { @stop = true }
+
+      save_state
+      @jobs.each_value { |job| watch_orphan(job) if job.running? }
+      require_relative 'cron_web'
+      @web = CronWeb.new(self, port: @port, pass: @pass).start
+      print_startup_summary
+      Shell.say "web ui: http://127.0.0.1:#{@port}#{' (password protected)' if @pass}", :cyan
+      Shell.say 'Ctrl-C to stop', :gray
+
+      until @stop
+        tick = wait_for_tick or break
+        each_job_snapshot do |job|
+          launch(job, tick, trigger: 'cron') if job.schedule.due?(tick, job.last_run)
+        end
+      end
+
+      shutdown!
+    end
+
+    # Table of scheduled jobs + next runs; doubles as `h:cron --list`.
+    def print_startup_summary
+      now  = Time.now
+      rows = @jobs.values.map do |job|
+        [job.path, job.schedule.source, format_time(job.last_run),
+         format_time(job.schedule.next_run(now, last_run: job.last_run))]
+      end
+      widths = ['task', 'schedule', 'last run', 'next run'].each_with_index.map do |h, i|
+        [h.length, *rows.map { |r| r[i].length }].max
+      end
+      header = ['task', 'schedule', 'last run', 'next run']
+      Shell.say header.each_with_index.map { |h, i| h.ljust(widths[i]) }.join('  '), :yellow
+      rows.each do |r|
+        Shell.say r.each_with_index.map { |v, i| v.ljust(widths[i]) }.join('  ')
+      end
+    end
+
+    # Trigger one job outside its schedule (web UI "run now" button).
+    # Same code path as a scheduled run; the log header says 'manual'.
+    # Returns false when the job is unknown.
+    def run_now(path)
+      job = @jobs[path] or return false
+      launch(job, Time.now, trigger: 'manual')
+      true
+    end
+
+    # ----- job execution --------------------------------------------------
+
+    # Fire one run in a subprocess. Overlap policy: if the previous run
+    # of the SAME job is still alive, skip and note it in the job log -
+    # jobs that outlive their interval must not pile up. Different jobs
+    # run freely in parallel. The child runs the full normal hammer
+    # pipeline (Bundler, dotenv, before hooks, needs) in @root_dir with
+    # stdin closed, so anything interactive fails fast instead of
+    # hanging the scheduler.
+    def launch(job, at, trigger:)
+      @mutex.synchronize do
+        if job.running?
+          append_line(job, "[h:cron] #{at.strftime('%F %T')} skipped (#{trigger}) - previous run still active")
+          return
+        end
+        job.pid      = :starting
+        job.status   = 'running'
+        job.last_run = at
+        save_state
+      end
+
+      @threads << Thread.new do
+        begin
+          rotate_log(job)
+          FileUtils.mkdir_p(@log_dir)
+          File.open(log_path(job), 'a') do |log|
+            log.sync = true
+            log.puts "===== #{job.path} | #{trigger} | #{at.strftime('%F %T')} ====="
+            t0  = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            pid = Process.spawn(
+              { 'NO_COLOR' => '1', 'HAMMER_QUIET' => '1' },
+              @hammer_bin, job.path,
+              in: File::NULL, out: log, err: log, chdir: @root_dir
+            )
+            # Persist the real child pid right away - it's what lets a
+            # restarted server find this run again if we die mid-flight.
+            @mutex.synchronize do
+              job.pid = pid
+              save_state
+            end
+            _, status = Process.wait2(pid)
+            dur = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+            log.puts "===== exit #{status.exitstatus.inspect} | #{format('%.1f', dur)}s ====="
+            @mutex.synchronize do
+              job.pid       = nil
+              job.exit_code = status.exitstatus
+              job.duration  = dur
+              job.status    = status.success? ? 'ok' : 'failed'
+              save_state
+            end
+          end
+        rescue => e
+          @mutex.synchronize do
+            job.pid    = nil
+            job.status = 'error'
+            save_state
+          end
+          append_line(job, "[h:cron] run failed: #{e.class}: #{e.message}")
+        end
+      end
+    end
+
+    # ----- logs -----------------------------------------------------------
+
+    def log_path(job)
+      File.join(@log_dir, "#{job.file_slug}.log")
+    end
+
+    # Called before each run: past 1 MB the current log rolls to .log.1
+    # (POSIX rename clobbers the previous .1) and the run starts fresh.
+    # Max two files per job, ever.
+    def rotate_log(job)
+      path = log_path(job)
+      size = begin
+        File.size(path)
+      rescue Errno::ENOENT
+        0
+      end
+      File.rename(path, "#{path}.1") if size > MAX_LOG_BYTES
+    end
+
+    # ----- state file -----------------------------------------------------
+
+    # tmp/hammer/cron.state.json remembers last runs across restarts so a
+    # relaunched scheduler neither re-fires jobs that just ran nor
+    # forgets interval clocks. Also records our pid/port so a second
+    # `h:cron` (and the web UI) can see who is running.
+    def save_state
+      data = {
+        schema:     1,
+        pid:        Process.pid,
+        port:       @port,
+        started_at: (@started_at ||= Time.now).to_i,
+        jobs:       @jobs.transform_values do |j|
+          { last_run: j.last_run&.to_i, exit: j.exit_code, duration: j.duration,
+            status: j.status, pid: (j.pid if j.pid.is_a?(Integer)) }
+        end
+      }
+      FileUtils.mkdir_p(File.dirname(@state_path))
+      tmp = "#{@state_path}.tmp"
+      File.write(tmp, JSON.pretty_generate(data))
+      File.rename(tmp, @state_path)
+    end
+
+    # Tolerates a missing or corrupt file - scheduling state is
+    # best-effort, a fresh start is always safe. Jobs no longer declared
+    # in the Hammerfile simply are not restored (and get pruned on the
+    # next save).
+    def load_state
+      data = begin
+        JSON.parse(File.read(@state_path))
+      rescue Errno::ENOENT
+        return
+      rescue JSON::ParserError
+        warn Shell.paint("h:cron: ignoring corrupt #{@state_path}", :gray)
+        return
+      end
+      @saved_pid = data['pid']
+      (data['jobs'] || {}).each do |path, j|
+        job = @jobs[path] or next
+        job.last_run  = j['last_run'] ? Time.at(j['last_run']) : nil
+        job.exit_code = j['exit']
+        job.duration  = j['duration']
+        job.status    = j['status']
+        # A job saved as 'running' means the previous server went away
+        # mid-run. If its subprocess is still alive we keep reporting it
+        # as running (and the overlap guard keeps skipping new runs);
+        # otherwise the run's exit status is lost - mark it 'unknown'
+        # instead of leaving a stale 'running' badge forever.
+        next unless job.status == 'running'
+        if j['pid'] && process_alive?(j['pid'])
+          job.pid = j['pid']
+        else
+          job.pid    = nil
+          job.status = 'unknown'
+        end
+      end
+    end
+
+    # ----- service units ---------------------------------------------------
+
+    # Print a launchd plist (macOS) or systemd user unit (everything
+    # else) for running `h:cron` supervised. Unit text goes to stdout so
+    # it can be redirected into a file; install hints go to stderr.
+    def print_service_unit
+      if RUBY_PLATFORM.include?('darwin')
+        label = "com.lux-hammer.cron.#{File.basename(@root_dir)}"
+        puts <<~XML
+          <?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>Label</key><string>#{label}</string>
+            <key>ProgramArguments</key>
+            <array>
+              <string>#{@hammer_bin}</string>
+              <string>h:cron</string>
+              <string>--port=#{@port}</string>#{@pass ? "\n    <string>--pass=#{@pass}</string>" : ''}
+            </array>
+            <key>WorkingDirectory</key><string>#{@root_dir}</string>
+            <key>RunAtLoad</key><true/>
+            <key>KeepAlive</key><true/>
+            <key>StandardOutPath</key><string>#{@root_dir}/log/hammer/cron-server.log</string>
+            <key>StandardErrorPath</key><string>#{@root_dir}/log/hammer/cron-server.log</string>
+          </dict>
+          </plist>
+        XML
+        warn Shell.paint("# save to ~/Library/LaunchAgents/#{label}.plist, then:", :gray)
+        warn Shell.paint("#   launchctl load ~/Library/LaunchAgents/#{label}.plist", :gray)
+      else
+        puts <<~UNIT
+          [Unit]
+          Description=hammer h:cron job server (#{File.basename(@root_dir)})
+
+          [Service]
+          ExecStart=#{@hammer_bin} h:cron --port=#{@port}#{" --pass=#{@pass}" if @pass}
+          WorkingDirectory=#{@root_dir}
+          Restart=on-failure
+
+          [Install]
+          WantedBy=default.target
+        UNIT
+        warn Shell.paint('# save to ~/.config/systemd/user/hammer-cron.service, then:', :gray)
+        warn Shell.paint('#   systemctl --user enable --now hammer-cron', :gray)
+      end
+    end
+
+    # ----- snapshots for the web UI ----------------------------------------
+
+    # Plain-value copy of every job, taken under the mutex, so the web
+    # thread never renders half-updated state.
+    def snapshot
+      @mutex.synchronize do
+        @jobs.values.map do |j|
+          { path: j.path, desc: j.command.brief, cron: j.schedule.source,
+            last_run: j.last_run, status: j.status, exit_code: j.exit_code,
+            duration: j.duration, running: j.running?,
+            next_run: j.schedule.next_run(Time.now, last_run: j.last_run) }
+        end
+      end
+    end
+
+    def job?(path)
+      @jobs.key?(path)
+    end
+
+    private
+
+    # Refuse to start when the state file points at another live h:cron -
+    # two schedulers would double-fire every job. Best-effort (no lock
+    # file): kill(0) tells us whether that pid is still alive.
+    def ensure_single_instance!
+      return unless @saved_pid && @saved_pid != Process.pid
+      return unless process_alive?(@saved_pid)
+      raise Hammer::Error, "h:cron already running (pid #{@saved_pid}) - stop it first"
+    end
+
+    # kill(0) probes without signaling. EPERM means the pid exists but
+    # belongs to someone else - that still counts as alive. Best-effort:
+    # a recycled pid after reboot can false-positive, acceptable here.
+    def process_alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+
+    # Tick resolution: classic minute alignment, dropped to 1s when any
+    # interval job runs sub-minute (cron '10s') - those are the only
+    # schedules that can be due between minute boundaries.
+    def tick_step
+      sub_minute = @jobs.values.any? do |j|
+        j.schedule.interval && j.schedule.interval < 60
+      end
+      sub_minute ? 1 : 60
+    end
+
+    # This server restarted while a subprocess spawned by the previous
+    # one is still alive (restored from the state file). It is not our
+    # child, so wait2 is off the table - poll once a second until it
+    # disappears. Its exit status is lost, hence 'unknown'; the overlap
+    # guard keeps skipping new runs of the job until then.
+    def watch_orphan(job)
+      @threads << Thread.new do
+        sleep 1 while !@stop && process_alive?(job.pid)
+        unless @stop
+          @mutex.synchronize do
+            job.pid    = nil
+            job.status = 'unknown'
+            save_state
+          end
+          append_line(job, "[h:cron] orphaned run from previous server finished - exit status unknown")
+        end
+      end
+    end
+
+    # Sleep in <=1s slices until the next tick boundary so Ctrl-C is
+    # honored within a second. Returns the boundary Time, or nil on stop.
+    def wait_for_tick
+      step   = tick_step
+      target = (Time.now.to_i / step + 1) * step
+      while Time.now.to_i < target
+        return nil if @stop
+        sleep [target - Time.now.to_f, 1].min
+      end
+      Time.at(target)
+    end
+
+    # Due-checks read job state the runner threads mutate - grab the
+    # mutex for the read, launch outside it (launch re-locks itself).
+    def each_job_snapshot(&block)
+      @jobs.values.each(&block)
+    end
+
+    # Stop accepting HTTP, then give in-flight runs a short grace period
+    # to finish - a mid-backup kill is worse than a late exit. The
+    # subprocesses themselves are never signaled.
+    def shutdown!
+      Shell.say 'shutting down...', :gray
+      @web&.stop
+      @threads.each { |t| t.join(10) }
+      save_state
+    end
+
+    def append_line(job, line)
+      FileUtils.mkdir_p(@log_dir)
+      File.open(log_path(job), 'a') { |f| f.puts(line) }
+    end
+
+    def format_time(t)
+      t ? t.strftime('%F %T') : 'never'
+    end
+  end
+end

data/lib/hammer/cron_web.rb

@@ -0,0 +1,304 @@
+require 'socket'
+require 'cgi'
+require 'json'
+
+class Hammer
+  # Localhost web UI for Hammer::CronServer. Hand-rolled HTTP on stdlib
+  # TCPServer - the gem has no runtime dependencies and the protocol
+  # surface needed here is tiny: parse the request line, drain headers,
+  # route on verb+path, answer with Connection: close. No keep-alive, no
+  # chunked encoding, one short-lived thread per request so a slow
+  # client cannot block the scheduler or other viewers.
+  #
+  # Routes:
+  #   GET  /               jobs table (schedule, last/next run, status)
+  #   GET  /job/<path>     log viewer; ?file=1 shows the rotated log
+  #   POST /job/<path>/run trigger a manual run, redirect back (303)
+  #   GET  /json           live status as JSON, for scripting
+  class CronWeb
+    REFRESH_SECONDS ||= 10
+    TAIL_BYTES      ||= 65_536   # log viewer shows at most the last 64 KB
+
+    def initialize(server, port:, pass: nil)
+      @server = server
+      @port   = port
+      @pass   = pass && !pass.empty? ? pass : nil
+    end
+
+    # Actual bound port - differs from the requested one only when the
+    # caller asked for port 0 (tests grab a free ephemeral port that way).
+    def bound_port
+      @tcp&.addr&.fetch(1)
+    end
+
+    # Bind 127.0.0.1 only - the UI can trigger task runs, it must never
+    # listen on a public interface. Returns self so the caller can hold
+    # the instance for #stop.
+    def start
+      @tcp = TCPServer.new('127.0.0.1', @port)
+      @thread = Thread.new do
+        loop do
+          sock = begin
+            @tcp.accept
+          rescue IOError, Errno::EBADF
+            break   # #stop closed the listener
+          end
+          Thread.new(sock) do |s|
+            begin
+              handle(s)
+            rescue StandardError
+              nil   # a broken client must not take the UI down
+            ensure
+              s.close rescue nil
+            end
+          end
+        end
+      end
+      self
+    rescue Errno::EADDRINUSE
+      raise Hammer::Error, "h:cron web ui: port #{@port} is taken - pick another with --port"
+    end
+
+    # Closing the listener pops the accept loop out with IOError.
+    def stop
+      @tcp&.close
+      @thread&.join(2)
+    end
+
+    private
+
+    # Minimal HTTP: request line + headers, drain any Content-Length body
+    # (our POSTs carry none we care about), then route. With a --pass
+    # configured every route requires HTTP Basic auth first.
+    def handle(sock)
+      line = sock.gets or return
+      verb, target, = line.split(' ', 3)
+      length = 0
+      auth   = nil
+      while (h = sock.gets) && h.strip != ''
+        length = h.split(':', 2).last.to_i    if h =~ /\Acontent-length:/i
+        auth   = h.split(':', 2).last.strip   if h =~ /\Aauthorization:/i
+      end
+      sock.read(length) if length > 0
+
+      return unauthorized(sock) if @pass && !authorized?(auth)
+
+      path, query = target.to_s.split('?', 2)
+      route(sock, verb, CGI.unescape(path.to_s), query.to_s)
+    end
+
+    # Only the password half of `user:pass` is checked - any username
+    # works (`curl -u :secret`). Constant-time compare so the password
+    # can't be guessed byte-by-byte from response timing.
+    def authorized?(header)
+      return false unless header && header =~ /\ABasic (.+)\z/
+      decoded = begin
+        Regexp.last_match(1).unpack1('m')
+      rescue ArgumentError
+        return false
+      end
+      pass = decoded.to_s.split(':', 2)[1].to_s
+      secure_compare(pass, @pass)
+    end
+
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+      diff = 0
+      a.bytes.zip(b.bytes) { |x, y| diff |= x ^ y }
+      diff.zero?
+    end
+
+    # 401 + the WWW-Authenticate challenge that makes browsers pop the
+    # native login prompt.
+    def unauthorized(sock)
+      body = layout('unauthorized', '<p>401 - password required</p>')
+      sock.write "HTTP/1.1 401 Unauthorized\r\n" \
+                 "WWW-Authenticate: Basic realm=\"h:cron\"\r\n" \
+                 "Content-Type: text/html; charset=utf-8\r\n" \
+                 "Content-Length: #{body.bytesize}\r\n" \
+                 "Connection: close\r\n\r\n"
+      sock.write body
+    end
+
+    def route(sock, verb, path, query)
+      case
+      when verb == 'GET' && path == '/'
+        respond(sock, 200, layout('jobs', index_html))
+      when verb == 'GET' && path == '/json'
+        respond(sock, 200, JSON.pretty_generate(json_status), type: 'application/json')
+      when verb == 'POST' && path =~ %r{\A/job/(.+)/run\z}
+        job_path = Regexp.last_match(1)
+        if @server.run_now(job_path)
+          redirect(sock, "/job/#{CGI.escape(job_path)}")
+        else
+          respond(sock, 404, layout('not found', "<p>unknown job #{h(job_path)}</p>"))
+        end
+      when verb == 'GET' && path =~ %r{\A/job/(.+)\z}
+        job_path = Regexp.last_match(1)
+        if @server.job?(job_path)
+          respond(sock, 200, layout(job_path, job_html(job_path, rotated: query == 'file=1')))
+        else
+          respond(sock, 404, layout('not found', "<p>unknown job #{h(job_path)}</p>"))
+        end
+      else
+        respond(sock, 404, layout('not found', '<p>404</p>'))
+      end
+    end
+
+    # ----- responses -------------------------------------------------------
+
+    def respond(sock, status, body, type: 'text/html; charset=utf-8')
+      text = { 200 => 'OK', 303 => 'See Other', 404 => 'Not Found' }[status] || 'OK'
+      sock.write "HTTP/1.1 #{status} #{text}\r\n" \
+                 "Content-Type: #{type}\r\n" \
+                 "Content-Length: #{body.bytesize}\r\n" \
+                 "Connection: close\r\n\r\n"
+      sock.write body
+    end
+
+    # Post-redirect-get: the browser lands back on a plain GET, so a
+    # refresh never re-triggers the run.
+    def redirect(sock, location)
+      sock.write "HTTP/1.1 303 See Other\r\n" \
+                 "Location: #{location}\r\n" \
+                 "Content-Length: 0\r\n" \
+                 "Connection: close\r\n\r\n"
+    end
+
+    # ----- views -----------------------------------------------------------
+
+    def index_html
+      rows = @server.snapshot.map do |j|
+        badge = status_badge(j)
+        <<~ROW
+          <tr>
+            <td><a href="/job/#{CGI.escape(j[:path])}">#{h(j[:path])}</a></td>
+            <td><code>#{h(j[:cron])}</code></td>
+            <td>#{h(fmt_time(j[:last_run]))}</td>
+            <td>#{badge}</td>
+            <td>#{h(fmt_time(j[:next_run]))}</td>
+            <td>
+              <form method="post" action="/job/#{CGI.escape(j[:path])}/run">
+                <button#{j[:running] ? ' disabled' : ''}>run now</button>
+              </form>
+            </td>
+          </tr>
+        ROW
+      end
+      <<~HTML
+        <table>
+          <tr><th>task</th><th>schedule</th><th>last run</th><th>status</th><th>next run</th><th></th></tr>
+          #{rows.join}
+        </table>
+      HTML
+    end
+
+    def job_html(path, rotated: false)
+      job  = @server.snapshot.find { |j| j[:path] == path }
+      file = log_file(path, rotated: rotated)
+      log  = tail_file(file)
+      <<~HTML
+        <p><a href="/">&larr; all jobs</a></p>
+        <h2>#{h(path)}</h2>
+        <p>
+          <code>#{h(job[:cron])}</code> &middot;
+          #{status_badge(job)} &middot;
+          last run #{h(fmt_time(job[:last_run]))} &middot;
+          next run #{h(fmt_time(job[:next_run]))}
+          #{job[:duration] ? "&middot; took #{format('%.1f', job[:duration])}s" : ''}
+        </p>
+        <form method="post" action="/job/#{CGI.escape(path)}/run">
+          <button#{job[:running] ? ' disabled' : ''}>run now</button>
+        </form>
+        <p class="files">
+          #{rotated ? "<a href=\"/job/#{CGI.escape(path)}\">current log</a>" : '<b>current log</b>'} |
+          #{rotated ? '<b>rotated log</b>' : "<a href=\"/job/#{CGI.escape(path)}?file=1\">rotated log</a>"}
+        </p>
+        <pre>#{h(log)}</pre>
+      HTML
+    end
+
+    def layout(title, body)
+      <<~HTML
+        <!doctype html>
+        <html>
+        <head>
+          <meta charset="utf-8">
+          <meta http-equiv="refresh" content="#{REFRESH_SECONDS}">
+          <title>h:cron - #{h(title)}</title>
+          <style>
+            body { font: 14px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+                   margin: 2rem auto; max-width: 60rem; padding: 0 1rem; color: #222; }
+            h1 a { color: inherit; text-decoration: none; }
+            table { border-collapse: collapse; width: 100%; }
+            th, td { text-align: left; padding: .4rem .8rem; border-bottom: 1px solid #ddd; }
+            th { color: #888; font-weight: 600; }
+            code { background: #f4f4f4; padding: .1rem .3rem; border-radius: 3px; }
+            pre { background: #1a1a1a; color: #ddd; padding: 1rem; border-radius: 6px;
+                  overflow-x: auto; white-space: pre-wrap; word-break: break-all; }
+            button { cursor: pointer; }
+            .ok      { color: #2a7d2a; }
+            .failed, .error { color: #c02626; }
+            .running { color: #b8860b; }
+            .never, .unknown { color: #888; }
+            .files   { color: #888; }
+            footer   { color: #aaa; margin-top: 2rem; font-size: 12px; }
+            @media (prefers-color-scheme: dark) {
+              body { background: #111; color: #ccc; }
+              th, td { border-color: #333; }
+              code { background: #222; }
+            }
+          </style>
+        </head>
+        <body>
+          <h1><a href="/">h:cron</a></h1>
+          #{body}
+          <footer>hammer #{Hammer::VERSION} &middot; #{h(@server.root_dir)} &middot; refreshes every #{REFRESH_SECONDS}s</footer>
+        </body>
+        </html>
+      HTML
+    end
+
+    def status_badge(j)
+      label = j[:running] ? 'running' : (j[:status] || 'never ran')
+      css   = j[:running] ? 'running' : (j[:status] || 'never')
+      extra = !j[:running] && j[:exit_code] ? " (exit #{j[:exit_code]})" : ''
+      "<span class=\"#{h(css)}\">#{h(label)}#{h(extra)}</span>"
+    end
+
+    def json_status
+      @server.snapshot.map do |j|
+        j.merge(last_run: j[:last_run]&.to_i, next_run: j[:next_run]&.to_i)
+      end
+    end
+
+    # ----- helpers ----------------------------------------------------------
+
+    def log_file(path, rotated: false)
+      slug = path.tr(':', '-').gsub(/[^\w.-]/, '-')
+      file = File.join(@server.root_dir, 'log/hammer', "#{slug}.log")
+      rotated ? "#{file}.1" : file
+    end
+
+    # Last TAIL_BYTES of the file - enough for a viewer, cheap even when
+    # the log sits right under the 1 MB rotation cap.
+    def tail_file(file)
+      size = File.size(file)
+      File.open(file) do |f|
+        f.seek([size - TAIL_BYTES, 0].max)
+        data = f.read.to_s
+        size > TAIL_BYTES ? "... (truncated)\n#{data}" : data
+      end
+    rescue Errno::ENOENT
+      '(no log yet)'
+    end
+
+    def fmt_time(t)
+      t ? t.strftime('%F %T') : 'never'
+    end
+
+    def h(text)
+      CGI.escapeHTML(text.to_s)
+    end
+  end
+end

data/lib/lux-hammer.rb

@@ -2,6 +2,7 @@ require_relative 'hammer/shell'
 require_relative 'hammer/option'
 require_relative 'hammer/parser'
 require_relative 'hammer/command'
+require_relative 'hammer/cron'
 require_relative 'hammer/loader'
 require_relative 'hammer/builder'
 require_relative 'hammer/command_builder'
@@ -62,6 +63,7 @@ class Hammer
       sub.instance_variable_set(:@pending_options, [])
       sub.instance_variable_set(:@pending_alts, [])
       sub.instance_variable_set(:@pending_needs, [])
+      sub.instance_variable_set(:@pending_cron, nil)
     end
 
     # ----- class-level DSL for `def`-style commands ---------------------
@@ -80,6 +82,7 @@ class Hammer
     def opt(name, **o)   ; @pending_options << Option.new(name, **o) end
     def alt(*names)      ; @pending_alts.concat(names) end
     def needs(*names)    ; @pending_needs.concat(names) end
+    def cron(expr)       ; @pending_cron = expr end
 
     def method_added(method_name)
       super
@@ -90,6 +93,7 @@ class Hammer
       @pending_options.each  { |o| cmd.add_option(o) }
       @pending_alts.each     { |n| cmd.add_alt(n) }
       @pending_needs.each    { |n| cmd.add_need(n) }
+      cmd.set_cron(@pending_cron) if @pending_cron
 
       # If the method takes no args, call it without opts. Otherwise pass
       # opts. So both `def build` and `def build(opts)` work.
@@ -104,6 +108,7 @@ class Hammer
       @pending_options  = []
       @pending_alts     = []
       @pending_needs    = []
+      @pending_cron     = nil
     end
 
     # Resolved lazily on first read and memoized, so callers that need the
@@ -183,6 +188,7 @@ class Hammer
       @pending_options  = []
       @pending_alts     = []
       @pending_needs    = []
+      @pending_cron     = nil
     end
 
     # Open a namespace (group of commands). Everything inside the block
@@ -905,6 +911,7 @@ class Hammer
         Shell.say(stripped.empty? ? '' : "  #{stripped}")
       end unless cmd.desc.empty?
       Shell.say "  alias: #{cmd.alts.join(', ')}" unless cmd.alts.empty?
+      Shell.say "  cron: #{cmd.cron}" if cmd.cron
       unless cmd.options.empty?
         Shell.say ''
         Shell.say 'Options:', :yellow

data/recipes/llm.rb

@@ -178,7 +178,7 @@ namespace :prompt do
   def folders
     [
       ['local',  File.join(Dir.pwd, 'doc', 'command')],
-      ['global', File.expand_path('~/dev/skills/command')]
+      ['global', File.expand_path('~/dev/ai/command')]
     ]
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.3.14
+  version: 0.3.15
 platform: ruby
 authors:
 - Dino Reic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-27 00:00:00.000000000 Z
+date: 2026-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -42,6 +42,9 @@ files:
 - "./lib/hammer/builtins.rb"
 - "./lib/hammer/command.rb"
 - "./lib/hammer/command_builder.rb"
+- "./lib/hammer/cron.rb"
+- "./lib/hammer/cron_server.rb"
+- "./lib/hammer/cron_web.rb"
 - "./lib/hammer/dotenv.rb"
 - "./lib/hammer/loader.rb"
 - "./lib/hammer/option.rb"