asgard 0.6.0 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -14,6 +14,25 @@ module Asgard
14
14
  PADDING = 1 # spaces either side of a cell
15
15
  EXTRA = PADDING * 2 # what a column adds to its content
16
16
 
17
+ # The color of a styled cell, by its column.
18
+ COLORS = {
19
+ state: ->(state) { { "active" => :green, "running" => :green, "stopped" => :yellow }.fetch(state.split.first, :red) },
20
+ last_exit: ->(last_exit) { last_exit.match?(/\A(?:[1-9]\d*\b|signal )/) ? :red : :dim }
21
+ }.freeze
22
+
23
+ # +widths+ (padding included) made to fit +limit+ columns of screen:
24
+ # the widest of the +flexible+ columns gives up a character at a time
25
+ # until the table fits or that column is down to MIN_WIDTH.
26
+ def self.fit(widths, flexible:, limit:)
27
+ widths = widths.dup
28
+ loop do
29
+ widest = flexible.max_by { |index| widths[index] }
30
+ return widths unless widths.sum + widths.size + 1 > limit && widths[widest] > MIN_WIDTH
31
+
32
+ widths[widest] -= 1
33
+ end
34
+ end
35
+
17
36
  # Columns available for output: the terminal's when io is one, else
18
37
  # $COLUMNS, else a roomy default (piped output shouldn't wrap at 80).
19
38
  def self.terminal_width(io = $stdout, env: ENV, default: 120)
@@ -36,14 +55,11 @@ module Asgard
36
55
  def initialize(rows, color:, width:, headers: HEADERS, keys: KEYS, flexible: FLEXIBLE)
37
56
  require "pastel"
38
57
 
39
- @headers = headers
40
- @flexible = flexible
41
- @styled = { state: keys.index(:state), last_exit: keys.index(:last_exit) }.compact
42
- @cells = rows.map { |row| row.values_at(*keys).map(&:to_s) }
43
- @pastel = Pastel.new(enabled: color)
44
- @width = width
45
- @column_widths = natural_widths
46
- shrink_widest while overflowing? && shrinkable?
58
+ @headers = headers
59
+ @styled = COLORS.keys.to_h { |column| [column, keys.index(column)] }.compact
60
+ @cells = rows.map { |row| row.values_at(*keys).map(&:to_s) }
61
+ @pastel = Pastel.new(enabled: color)
62
+ @column_widths = Table.fit(natural_widths, flexible:, limit: width)
47
63
  end
48
64
 
49
65
  def render
@@ -74,24 +90,12 @@ module Asgard
74
90
 
75
91
  def natural_widths = [@headers, *@cells].transpose.map { |column| column.max_by(&:length).length + EXTRA }
76
92
 
77
- def overflowing? = total_width > @width
78
-
79
- def widest_flexible = @flexible.max_by { |index| @column_widths[index] }
80
-
81
- def shrinkable? = @column_widths[widest_flexible] > MIN_WIDTH
82
-
83
- def shrink_widest = @column_widths[widest_flexible] -= 1
84
-
85
93
  # The state and last-exit cells colored, wherever keys: put them.
86
94
  def styled(cells)
87
95
  cells = cells.dup
88
- @styled.each { |column, index| cells[index] = @pastel.decorate(cells[index], send(:"#{column}_color", cells[index])) }
96
+ @styled.each { |column, index| cells[index] = @pastel.decorate(cells[index], COLORS.fetch(column).call(cells[index])) }
89
97
  cells
90
98
  end
91
-
92
- def state_color(state) = { "active" => :green, "running" => :green, "stopped" => :yellow }.fetch(state.split.first, :red)
93
-
94
- def last_exit_color(last_exit) = last_exit.match?(/\A(?:[1-9]\d*\b|signal )/) ? :red : :dim
95
99
  end
96
100
  end
97
101
  end
@@ -31,7 +31,7 @@ module Asgard
31
31
  def declare(task, **) = Declarations.record(declarations, place(normalize(task, **)), "schedule")
32
32
 
33
33
  # The name a command derives (a normalize result's task and args).
34
- def plain_name(spec) = command_slug(spec[:task], spec[:args])
34
+ def plain_name(spec) = command_slug([spec[:task], *spec[:args]])
35
35
 
36
36
  # Whether +spec+ has the plain name its command derives, rather than
37
37
  # an as: name or a hashed one.
@@ -43,7 +43,7 @@ module Asgard
43
43
  derived_name?(one) && derived_name?(other) && one.values_at(:task, :args) != other.values_at(:task, :args)
44
44
  end
45
45
 
46
- def with_hashed_name(spec) = spec.merge(name: hashed_slug(spec[:task], spec[:args]))
46
+ def with_hashed_name(spec) = spec.merge(name: hashed_slug([spec[:task], *spec[:args]]))
47
47
 
48
48
  # Whether +spec+'s plain name was already given up by a rival in
49
49
  # +declarations+, one now under its hashed name, so +spec+ takes its
data/lib/asgard/shell.rb CHANGED
@@ -161,9 +161,12 @@ module Asgard
161
161
  # The executable must exist: an executable file at that path, or a
162
162
  # bare name found on PATH. Otherwise ArgumentError, as the .loki loads.
163
163
  def shell(name_or_path, path = nil, args: nil, ext: nil)
164
- name, path = split_shell_args(name_or_path, path)
165
- entry = Shell.entry(path, args:, ext:)
166
- name ||= Shell.name_for(entry)
164
+ # A Symbol first is the name, and its path defaults to the name
165
+ # itself; a String or Pathname first is the path, and the name
166
+ # comes from the entry.
167
+ name = name_or_path if name_or_path.is_a?(Symbol)
168
+ entry = Shell.entry(name ? path || name.to_s : name_or_path, args:, ext:)
169
+ name ||= Shell.name_for(entry)
167
170
  Shell.shells[name] = Shell.validate!(name, entry)
168
171
  name
169
172
  end
@@ -178,15 +181,6 @@ module Asgard
178
181
  Shell.validate!(name, Shell.shell_for(name))
179
182
  name
180
183
  end
181
-
182
- # The [name, path] of a `shell` call: a Symbol first is the name, and
183
- # its path defaults to the name itself; a String or Pathname first is
184
- # the path, and the name comes from the entry.
185
- def split_shell_args(name_or_path, path)
186
- return [nil, name_or_path] unless name_or_path.is_a?(Symbol)
187
-
188
- [name_or_path, path || name_or_path.to_s]
189
- end
190
184
  end
191
185
 
192
186
  def self.included(base) = base.extend(ClassMethods)
@@ -76,9 +76,15 @@ module Asgard
76
76
  # Creates +dir+, readable by its owner only (logs and job scripts can
77
77
  # hold secrets), and records the project root in it.
78
78
  def record_root(dir, root)
79
+ private_dir(dir)
80
+ File.write(File.join(dir, ROOT_FILE), "#{root}\n")
81
+ end
82
+
83
+ # Creates +dir+ (and any missing parents) readable by its owner only,
84
+ # tightening an existing one: mkdir_p's mode: applies only to what it creates.
85
+ def private_dir(dir)
79
86
  FileUtils.mkdir_p(dir, mode: 0o700)
80
87
  File.chmod(0o700, dir)
81
- File.write(File.join(dir, ROOT_FILE), "#{root}\n")
82
88
  end
83
89
  end
84
90
  end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Asgard
4
- VERSION = "0.6.0"
4
+ VERSION = "0.6.2"
5
5
  end
@@ -15,8 +15,8 @@ module Asgard
15
15
  FILE_VARIABLE = "ASGARD_CHANGES_FILE"
16
16
 
17
17
  class << self
18
- # The changes behind this process, read once from ENV. Tests and a
19
- # watcher-run task that re-execs call forget to read them again.
18
+ # The changes behind this process, read once from ENV. Call forget
19
+ # to read them again; the tests do so after changing ENV.
20
20
  def current = @current ||= from_env
21
21
 
22
22
  def forget = @current = nil
@@ -2,6 +2,7 @@
2
2
 
3
3
  require "shellwords"
4
4
  require "time"
5
+ require_relative "../log"
5
6
 
6
7
  # warn is silent when $VERBOSE is nil and bypasses $stderr in Ruby 4.0 (see
7
8
  # base/task_dsl.rb); these messages are for the user, so they always print.
@@ -57,7 +58,7 @@ module Asgard
57
58
  no_commands do
58
59
  def watches = Watch.declarations
59
60
 
60
- def watch_root = @watch_root ||= File.realpath((Asgard.find_task_file&.dirname || Pathname.pwd).to_s)
61
+ def watch_root = @watch_root ||= Asgard.project_root
61
62
 
62
63
  def watch_project = @watch_project ||= Schedule.project_slug(watch_root)
63
64
 
@@ -245,6 +246,15 @@ module Asgard
245
246
 
246
247
  IO.copy_stream(path, $stdout)
247
248
  end
249
+
250
+ desc "truncate_log", "Keep the last M lines of this project's watcher logs; --lines 0 empties them"
251
+ method_option :lines, type: :string, default: "1000", banner: "M", desc: "Lines to keep per log; 0 empties it"
252
+ method_option :dry_run, aliases: "-n", type: :boolean, desc: "Report what would be removed without changing logs"
253
+ def truncate_log
254
+ Log.truncate_logs([state.log_path, "#{state.log_path}.1"], lines: options[:lines], dry_run: options[:dry_run])
255
+ rescue ArgumentError, SystemCallError, IOError => e
256
+ abort "watcher: #{e.message}"
257
+ end
248
258
  end
249
259
  end
250
260
  end
@@ -21,6 +21,18 @@ module Asgard
21
21
  def initialize(pending: nil, **) = super
22
22
  end
23
23
 
24
+ # What a daemon is given to work with, so a test can stand in for any
25
+ # of it (see Daemon#initialize).
26
+ Tools = Data.define(:listen, :exec, :out, :dispatcher, :validate, :grace)
27
+
28
+ # What has been asked of a running daemon: to stop, to end its tasks
29
+ # by force (and when that began), or to reload the task files.
30
+ Requests = Struct.new(:stopping, :force, :forced_at, :reload)
31
+
32
+ # What a run holds while it is up: the project lock, the report queue,
33
+ # and the reporter and dispatcher with their threads.
34
+ Pipeline = Struct.new(:lock, :reports, :reporter, :dispatcher, :reporter_thread, :dispatcher_thread)
35
+
24
36
  LOKI_DEBOUNCE = 0.5
25
37
 
26
38
  # Seconds between the TERM a second stop sends running tasks and the
@@ -36,21 +48,12 @@ module Asgard
36
48
  # root); grace: is FORCE_GRACE.
37
49
  def initialize(config, listen: Daemon.listen_module, exec: Kernel.method(:exec), out: $stdout, dispatcher: Dispatcher,
38
50
  validate: Daemon.method(:loki_valid?), grace: FORCE_GRACE)
39
- @config = config
40
- @listen = listen
41
- @exec = exec
42
- @out = out
43
- @inbox = Queue.new
44
- @listeners = []
45
- @stopping = false
46
- @force = false
47
- @forced_at = nil
48
- @reload = false
49
- @reporter = nil
50
- @dispatcher = nil
51
- @dispatcher_class = dispatcher
52
- @validate = validate
53
- @grace = grace
51
+ @config = config
52
+ @tools = Tools.new(listen:, exec:, out:, dispatcher:, validate:, grace:)
53
+ @inbox = Queue.new
54
+ @listeners = []
55
+ @requests = Requests.new(false, false, nil, false)
56
+ @pipeline = Pipeline.new
54
57
  end
55
58
 
56
59
  class << self
@@ -94,7 +97,7 @@ module Asgard
94
97
 
95
98
  # Waits for a worker to end; one that died has nothing to wait for.
96
99
  def join_worker(ractor)
97
- ractor.respond_to?(:join) ? ractor.join : ractor.take
100
+ ractor.join
98
101
  rescue Ractor::Error
99
102
  nil
100
103
  end
@@ -199,7 +202,7 @@ module Asgard
199
202
  check_tasks!
200
203
  Dir.chdir(@config.root)
201
204
  state = @config.state.prepare
202
- @lock = state.lock or raise Error, "another watcher is already running for this project (#{state.lock_path} is held)"
205
+ @pipeline.lock = state.lock or raise Error, "another watcher is already running for this project (#{state.lock_path} is held)"
203
206
  state.write_declarations(@config.declarations.values)
204
207
  trap_signals
205
208
  begin
@@ -215,17 +218,17 @@ module Asgard
215
218
  # Asks run to stop; the trap handler calls this. A second call, while
216
219
  # running tasks are still awaited, asks for them to be ended too.
217
220
  def stop
218
- @force = true if @stopping
219
- @stopping = true
221
+ @requests.force = true if @requests.stopping
222
+ @requests.stopping = true
220
223
  end
221
224
 
222
225
  # Asks run to replace the process with a fresh `watcher run` so new
223
226
  # declarations take effect, once running tasks have exited. The
224
227
  # .loki listener calls this from its own thread, so it only sets a
225
228
  # flag.
226
- def reload = @reload = true
229
+ def reload = @requests.reload = true
227
230
 
228
- def next_action = Daemon.next_action(stopping: @stopping, reload: @reload)
231
+ def next_action = Daemon.next_action(stopping: @requests.stopping, reload: @requests.reload)
229
232
 
230
233
  # Waits for a stop, or for a reload into a project that would run. A
231
234
  # .loki saved with an error, or one that renames a watched task or
@@ -234,10 +237,10 @@ module Asgard
234
237
  def wait_for_stop_or_good_reload
235
238
  loop do
236
239
  sleep 0.2 while next_action == :wait
237
- return if next_action == :stop || @validate.call(@config.context.asgard, @config.root)
240
+ return if next_action == :stop || @tools.validate.call(@config.context.asgard, @config.root)
238
241
 
239
242
  say "watcher: the task files do not load or declare no runnable watch; keeping the running declarations"
240
- @reload = false
243
+ @requests.reload = false
241
244
  end
242
245
  end
243
246
 
@@ -253,7 +256,7 @@ module Asgard
253
256
  stop_listening
254
257
  unless next_action == :reload
255
258
  say "watcher: stopped"
256
- return @lock.close
259
+ return @pipeline.lock.close
257
260
  end
258
261
 
259
262
  say "watcher: reloading"
@@ -287,18 +290,18 @@ module Asgard
287
290
  def abandon(state)
288
291
  @listeners.each { |listener| Daemon.quietly { listener.stop } }
289
292
  @inbox.push(nil)
290
- @dispatcher&.workers&.each_value { |worker| Daemon.close_queue(worker[:mailbox]) }
291
- @reports&.push(nil)
293
+ @pipeline.dispatcher&.workers&.each_value { |worker| Daemon.close_queue(worker[:mailbox]) }
294
+ @pipeline.reports&.push(nil)
292
295
  state.clear
293
- @lock.close
296
+ @pipeline.lock.close
294
297
  end
295
298
 
296
299
  # The new process inherits the held lock, so no other start can slip
297
300
  # in between this daemon and its replacement, and is told where the
298
301
  # pending changes are (nil unsets the variable).
299
302
  def exec_with_lock(pending)
300
- fd = @lock.fileno
301
- @exec.call({ State::LOCK_ENV => fd.to_s, State::PENDING_ENV => pending }, @config.context.asgard, "watcher", "run", fd => fd)
303
+ fd = @pipeline.lock.fileno
304
+ @tools.exec.call({ State::LOCK_ENV => fd.to_s, State::PENDING_ENV => pending }, @config.context.asgard, "watcher", "run", fd => fd)
302
305
  end
303
306
 
304
307
  # Writes the pending list for the next daemon; its path, or nil when
@@ -320,16 +323,17 @@ module Asgard
320
323
  # follows the log through rotation (and is unbuffered), so the
321
324
  # daemon's own messages never land in a rotated-away file.
322
325
  def start_pipeline(state)
323
- log = state.log_path
324
- @log_outputs = [@out, $stderr].uniq.select { |io| Daemon.writes_to?(io, log) }
325
- Daemon.reopen_log(@log_outputs, log)
326
+ log = state.log_path
327
+ outputs = [@tools.out, $stderr].uniq.select { |io| Daemon.writes_to?(io, log) }
328
+ Daemon.reopen_log(outputs, log)
326
329
  # Workers push from their Ractors; the reporter thread pops here, in
327
330
  # the main Ractor, which the Mailbox wakes on every push.
328
- @reports = Ractor.make_shareable(Mailbox.new(RactorQueue.new(capacity: 1024), Ractor.current))
329
- @reporter = Reporter.new(@reports, log:, state:, on_rotate: -> { Daemon.reopen_log(@log_outputs, log) })
330
- @dispatcher = @dispatcher_class.new(@config.declarations, @config.context, reports: @reports)
331
- @reporter_thread = @reporter.start
332
- @dispatcher_thread = @dispatcher.start(@inbox)
331
+ reports = Ractor.make_shareable(Mailbox.new(RactorQueue.new(capacity: 1024), Ractor.current))
332
+ @pipeline.reports = reports
333
+ @pipeline.reporter = Reporter.new(reports, log:, state:, on_rotate: -> { Daemon.reopen_log(outputs, log) })
334
+ @pipeline.dispatcher = @tools.dispatcher.new(@config.declarations, @config.context, reports:)
335
+ @pipeline.reporter_thread = @pipeline.reporter.start
336
+ @pipeline.dispatcher_thread = @pipeline.dispatcher.start(@inbox)
333
337
  end
334
338
 
335
339
  def build_listeners = @config.declarations.values.flat_map { |spec| spec[:dirs].map { |dir| listener_for(spec, dir) } }
@@ -338,14 +342,14 @@ module Asgard
338
342
  # callback pushes [entry name, batch] onto the inbox.
339
343
  def listener_for(spec, dir)
340
344
  name = spec[:name]
341
- @listen.to(dir, **Daemon.listen_options(spec, dir)) do |modified, added, removed|
345
+ @tools.listen.to(dir, **Daemon.listen_options(spec, dir)) do |modified, added, removed|
342
346
  @inbox.push([name, { modified:, added:, removed: }])
343
347
  end
344
348
  end
345
349
 
346
350
  def loki_listener
347
351
  only = Daemon.loki_pattern(@config.root, $LOADED_FEATURES)
348
- @listen.to(@config.root, only:, ignore: Watch.ignores_for(".", []), wait_for_delay: LOKI_DEBOUNCE, relative: true) { reload }
352
+ @tools.listen.to(@config.root, only:, ignore: Watch.ignores_for(".", []), wait_for_delay: LOKI_DEBOUNCE, relative: true) { reload }
349
353
  end
350
354
 
351
355
  def trap_signals
@@ -355,8 +359,8 @@ module Asgard
355
359
  # One line of the daemon's own output, written out at once: an exec
356
360
  # would otherwise drop what is still buffered.
357
361
  def say(line)
358
- @out.puts line
359
- @out.flush
362
+ @tools.out.puts line
363
+ @tools.out.flush
360
364
  end
361
365
 
362
366
  # Upstream first, so nothing is in flight when it returns: the
@@ -366,12 +370,12 @@ module Asgard
366
370
  # every report is written. The dropped triggers as [entry, lists].
367
371
  def shutdown(state)
368
372
  @inbox.push(nil)
369
- @dispatcher_thread.join
370
- workers = @dispatcher.workers.values
373
+ @pipeline.dispatcher_thread.join
374
+ workers = @pipeline.dispatcher.workers.values
371
375
  dropped = workers.flat_map { |worker| Daemon.close_queue(worker[:mailbox]) }
372
376
  wait_for_workers(workers.map { |worker| worker[:ractor] })
373
- @reports.push(nil)
374
- @reporter_thread.join
377
+ @pipeline.reports.push(nil)
378
+ @pipeline.reporter_thread.join
375
379
  state.clear
376
380
  dropped.filter_map { |item| [item[:entry], item[:changes]] if item.is_a?(Hash) }
377
381
  end
@@ -387,9 +391,9 @@ module Asgard
387
391
  # worker has ended, ending the tasks after a second stop (escalate).
388
392
  def wait_for_workers(ractors, interval: 1.0)
389
393
  waiters = ractors.map { |ractor| Thread.new { Daemon.join_worker(ractor) } }
390
- say "watcher: INT or TERM again ends the running tasks" if @stopping && !@reporter.running.empty?
394
+ say "watcher: INT or TERM again ends the running tasks" if @requests.stopping && !@pipeline.reporter.running.empty?
391
395
  loop do
392
- pids = @reporter.running
396
+ pids = @pipeline.reporter.running
393
397
  say "watcher: waiting for pid #{pids.join(', ')}" unless pids.empty?
394
398
  break if waiters.all? { |waiter| waiter.join(interval) }
395
399
 
@@ -401,13 +405,13 @@ module Asgard
401
405
  # then KILL to any still running once the grace period has passed.
402
406
  # Each group is signalled only through Daemon.signal_task.
403
407
  def escalate
404
- return unless @force
408
+ return unless @requests.force
405
409
 
406
410
  now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
407
- signal = Daemon.escalation(@forced_at, now, @grace) or return
408
- @forced_at ||= now
411
+ signal = Daemon.escalation(@requests.forced_at, now, @tools.grace) or return
412
+ @requests.forced_at ||= now
409
413
  say "watcher: killing running tasks (#{signal})"
410
- @reporter.running_tasks.each { |pid, task| Daemon.signal_task(signal, pid, task) }
414
+ @pipeline.reporter.running_tasks.each { |pid, task| Daemon.signal_task(signal, pid, task) }
411
415
  end
412
416
  end
413
417
  end
@@ -65,16 +65,23 @@ module Asgard
65
65
  def asgard_process?(pid, *words, command: nil) = Pid.matches?(pid, "asgard", *words, command:)
66
66
  end
67
67
 
68
+ # The watcher's log file: appends a line, rotating first (StateDir.rotate)
69
+ # when the file has passed limit bytes, and telling on_rotate when it did.
70
+ LogFile = Struct.new(:path, :limit, :on_rotate) do
71
+ def append(line)
72
+ on_rotate&.call if StateDir.rotate(path, max_bytes: limit)
73
+ File.open(path, "a") { |file| file.puts(line) }
74
+ end
75
+ end
76
+
68
77
  # state: responds to write_entry(name, record). max_log: is the size
69
78
  # past which the log is rotated (StateDir.rotate); on_rotate: is
70
79
  # called after each rotation, so the daemon can move its own output
71
80
  # to the new log.
72
81
  def initialize(reports, log:, state:, max_log: StateDir.log_limit, on_rotate: nil)
73
- @reports = reports
74
- @log = log
75
- @max_log = max_log
76
- @on_rotate = on_rotate
77
- @state = state
82
+ @reports = reports
83
+ @log = LogFile.new(log, max_log, on_rotate)
84
+ @state = state
78
85
  @records = {}
79
86
  @running = {} # pid => task
80
87
  @mutex = Mutex.new
@@ -97,8 +104,7 @@ module Asgard
97
104
  trigger = kind == :trigger
98
105
  line = Reporter.log_line(report, behind: trigger ? running_for(report[:task]) : nil)
99
106
  track(report) if %i[spawn exit].include?(kind)
100
- @on_rotate&.call if StateDir.rotate(@log, max_bytes: @max_log)
101
- File.open(@log, "a") { |file| file.puts(line) }
107
+ @log.append(line)
102
108
  rescue SystemCallError, IOError => e
103
109
  $stderr.puts "watcher: could not write #{kind} report for #{report[:entry]}: #{e.message}" # rubocop:disable Style/StderrPuts
104
110
  end
@@ -66,10 +66,10 @@ module Asgard
66
66
  # a trigger runs the very asgard that started the watcher whatever PATH
67
67
  # says, wrapped in direnv exec when available so .envrc loads in the
68
68
  # task's process.
69
- def argv(spec, context)
69
+ def argv(task, context)
70
70
  direnv = context.direnv
71
71
  wrapper = direnv ? [direnv, "exec", context.root] : []
72
- [*wrapper, context.asgard, spec[:task]]
72
+ [*wrapper, context.asgard, task]
73
73
  end
74
74
 
75
75
  # The asgard executable to run: the one running now when it is an
@@ -90,7 +90,7 @@ module Asgard
90
90
  # it as :changes_file only when they did.
91
91
  def description(spec, changes, context, changes_file: nil)
92
92
  env = environment(spec, changes, context, changes_file:)
93
- desc = { entry: spec[:name], task: spec[:task], argv: argv(spec, context), env:,
93
+ desc = { entry: spec[:name], task: spec[:task], argv: argv(spec[:task], context), env:,
94
94
  root: context.root, log: context.log, changes: changes.to_h }
95
95
  desc[:changes_file] = changes_file if env.key?(Changes::FILE_VARIABLE)
96
96
  Ractor.make_shareable(desc)
@@ -41,10 +41,16 @@ module Asgard
41
41
  # the reports and the spawner (all shareable) and nothing else, and
42
42
  # pops through a Mailbox so it sleeps while idle: whoever pushes onto
43
43
  # +queue+ must wake it, through Mailbox.new(queue, the_ractor).
44
+ # Ruby's "Ractor API is experimental" warning is silenced here, or it
45
+ # would open every watcher.log; the daemon runs no user code.
44
46
  def self.start(queue, reports, spawner: Spawner)
47
+ experimental = Warning[:experimental]
48
+ Warning[:experimental] = false
45
49
  Ractor.new(queue, reports, spawner) do |inbox, outbox, runner|
46
50
  Asgard::Watch::Worker.new(Asgard::Watch::Mailbox.new(inbox, Ractor.current), outbox, spawner: runner).run
47
51
  end
52
+ ensure
53
+ Warning[:experimental] = experimental
48
54
  end
49
55
 
50
56
  def initialize(queue, reports, spawner: Spawner, clock: Process)
data/lib/asgard.rb CHANGED
@@ -11,7 +11,7 @@ require_relative "asgard/doctor"
11
11
 
12
12
  module Asgard
13
13
  # Search the current directory and its ancestors for a .loki task file.
14
- # Returns the path string, or nil if not found.
14
+ # Returns its Pathname, or nil if not found.
15
15
  def self.find_task_file
16
16
  loki_up
17
17
  end
@@ -33,8 +33,10 @@ module Asgard
33
33
 
34
34
  # `asgard schedule list`, `asgard watcher list` and `asgard jobs list`
35
35
  # report every project's entries, so they work from a directory with no
36
- # .loki above it.
37
- def self.machine_wide?(argv) = [%w[schedule list], %w[watcher list], %w[jobs list], %w[jobs]].include?(argv.first(2))
36
+ # .loki above it, with or without leading global flags.
37
+ def self.machine_wide?(argv)
38
+ [%w[schedule list], %w[watcher list], %w[jobs list], %w[jobs]].include?(argv.drop_while { global_flag?(it) }.first(2))
39
+ end
38
40
 
39
41
  # The root .loki is loaded directly rather than through `import`, so
40
42
  # record it the way import would. Otherwise an `import_up` in a child
@@ -58,7 +60,19 @@ module Asgard
58
60
  return "#{first} (#{error.class})" if error.is_a?(SyntaxError) && first.match?(LOKI_FRAME)
59
61
 
60
62
  where = Array(error.backtrace).lazy.filter_map { |frame| frame[LOKI_FRAME, 1] }.first
61
- [where, "#{first} (#{error.class})"].compact.join(": ")
63
+ hint = "; asgard's DSL (desc, depends_on, schedule, ...) goes inside class Tasks ... end" if dsl_outside_tasks?(error)
64
+ [where, "#{first} (#{error.class})#{hint}"].compact.join(": ")
65
+ end
66
+
67
+ # Whether +error+ is a Tasks class method (desc, depends_on, ...) called
68
+ # at the top level of a task file, outside `class Tasks ... end`.
69
+ def self.dsl_outside_tasks?(error)
70
+ return false unless error.is_a?(NameError) && error.receiver.equal?(TOPLEVEL_BINDING.receiver)
71
+
72
+ name = error.name or return false
73
+ Tasks.respond_to?(name, true) && !Object.respond_to?(name, true)
74
+ rescue ArgumentError # a NameError built without a receiver
75
+ false
62
76
  end
63
77
 
64
78
  # Loads the task files; anything they raise ends asgard with one line
@@ -83,8 +97,7 @@ module Asgard
83
97
  end
84
98
  return unless leading_flag?(argv, "--doctor")
85
99
 
86
- Asgard::Doctor.new.run
87
- exit
100
+ exit(Asgard::Doctor.new.run)
88
101
  end
89
102
 
90
103
  # Finds and loads the task files and checks every class they defined.
@@ -96,12 +109,39 @@ module Asgard
96
109
  ((Asgard::Base._asgard_subclasses - before) + [Tasks]).uniq.each(&:validate_deps!)
97
110
  end
98
111
 
112
+ # Whether +word+ is what Thor would take as a task name: a task, a mapped
113
+ # name, or an abbreviation of either. A task's full name counts with
114
+ # dashes for underscores (deploy-app) and when the task is hidden, as
115
+ # Thor runs both; Thor expands no abbreviation to a hidden task. Options,
116
+ # the gem's reserved `_` names and the empty word (a prefix of every
117
+ # task) are not.
118
+ def self.task_word?(word, tasks = Tasks)
119
+ return false if word.empty? || word.start_with?("-", "_")
120
+
121
+ tasks.all_commands.key?(word.tr("-", "_")) || tasks.send(:find_command_possibilities, word).any?
122
+ end
123
+
124
+ HELP_FLAGS = %w[--help -h].freeze
125
+
126
+ # `asgard TASK --help` (or -h) as `asgard help TASK`, so the task shows
127
+ # its help instead of running with --help as its argument. Only when
128
+ # nothing but global flags comes with the help flag.
129
+ def self.help_first(argv, tasks = Tasks)
130
+ word, *rest = argv
131
+ return argv unless word && rest.intersect?(HELP_FLAGS) && rest.all? { HELP_FLAGS.include?(it) || global_flag?(it) }
132
+ return argv unless task_word?(word, tasks)
133
+
134
+ ["help", word, *(rest - HELP_FLAGS)]
135
+ end
136
+
99
137
  # Main entry point invoked by the asgard executable.
100
138
  def self.run!(argv)
101
139
  answer_flags(argv)
102
140
  boot(argv)
103
141
  Tasks._reset_ran!
104
142
  pin_project_root(project_root)
143
+ argv = help_first(task_first(argv) { |word| task_word?(word) })
144
+ Tasks.check_default_task!(argv)
105
145
  result = Tasks.start(argv)
106
146
  # Quality-gate convention: a task signals failure by returning :fail
107
147
  # (see dev/quality.loki's *_check tasks). Surface that as a nonzero
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: asgard
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.6.0
4
+ version: 0.6.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Dewayne VanHoozer
@@ -106,10 +106,10 @@ dependencies:
106
106
  - !ruby/object:Gem::Version
107
107
  version: "0.2"
108
108
  description: |
109
- A powerful Ruby-based task runner for any kind of project with task dependency tracking
110
- and concurrent execution of designated tasks. Uses Thor for its rich CLI options, with
111
- dotenv, sh/shebang helpers, importable task files, scheduled execution of tasks via
112
- launchd (macOS) or systemd timers (Linux), a file watcher and background jobs.
109
+ A powerful Ruby-based task runner for any kind of project with task dependency tracking
110
+ and concurrent execution of designated tasks. Uses Thor for its rich CLI options, with
111
+ dotenv, sh/shebang helpers, importable task files, scheduled execution of tasks via
112
+ launchd (macOS) or systemd timers (Linux), a file watcher and background jobs.
113
113
  email:
114
114
  - dewayne@vanhoozer.me
115
115
  executables:
@@ -140,6 +140,7 @@ files:
140
140
  - lib/asgard/jobs/stopper.rb
141
141
  - lib/asgard/kernel_methods.rb
142
142
  - lib/asgard/leading_flag.rb
143
+ - lib/asgard/log.rb
143
144
  - lib/asgard/pid.rb
144
145
  - lib/asgard/schedule.rb
145
146
  - lib/asgard/schedule/commands.rb
@@ -171,6 +172,8 @@ metadata:
171
172
  homepage_uri: "https://github.com/madbomber/asgard"
172
173
  source_code_uri: "https://github.com/madbomber/asgard"
173
174
  changelog_uri: "https://github.com/madbomber/asgard/blob/main/CHANGELOG.md"
175
+ documentation_uri: "https://madbomber.github.io/asgard"
176
+ bug_tracker_uri: "https://github.com/madbomber/asgard/issues"
174
177
  rubygems_mfa_required: "true"
175
178
  rdoc_options: []
176
179
  require_paths:
@@ -188,7 +191,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
188
191
  - !ruby/object:Gem::Version
189
192
  version: "0"
190
193
  requirements: []
191
- rubygems_version: 4.1.0.beta3
194
+ rubygems_version: 4.1.0
192
195
  specification_version: 4
193
196
  summary: A powerful Ruby-based task runner
194
197
  test_files: []