asgard 0.5.1 → 0.6.1

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.
Files changed (106) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +272 -99
  3. data/README.md +147 -46
  4. data/bin/asgard +10 -0
  5. data/lib/asgard/base/dependency_graph.rb +19 -11
  6. data/lib/asgard/base/dispatch.rb +272 -32
  7. data/lib/asgard/base/registry.rb +7 -3
  8. data/lib/asgard/base/task_dsl.rb +6 -0
  9. data/lib/asgard/base.rb +147 -9
  10. data/lib/asgard/declarations.rb +21 -0
  11. data/lib/asgard/doctor/report.rb +5 -1
  12. data/lib/asgard/doctor/task_sections.rb +11 -3
  13. data/lib/asgard/doctor.rb +41 -31
  14. data/lib/asgard/jobs/commands.rb +183 -0
  15. data/lib/asgard/jobs/declaration.rb +149 -0
  16. data/lib/asgard/jobs/launcher.rb +109 -0
  17. data/lib/asgard/jobs/state.rb +195 -0
  18. data/lib/asgard/jobs/stopper.rb +141 -0
  19. data/lib/asgard/jobs.rb +25 -0
  20. data/lib/asgard/kernel_methods.rb +25 -30
  21. data/lib/asgard/leading_flag.rb +26 -0
  22. data/lib/asgard/log.rb +90 -0
  23. data/lib/asgard/pid.rb +113 -0
  24. data/lib/asgard/schedule/commands.rb +68 -18
  25. data/lib/asgard/schedule/declaration.rb +158 -26
  26. data/lib/asgard/schedule/job_files.rb +24 -0
  27. data/lib/asgard/schedule/launchd.rb +57 -21
  28. data/lib/asgard/schedule/systemd.rb +72 -28
  29. data/lib/asgard/schedule/table.rb +48 -26
  30. data/lib/asgard/schedule.rb +49 -9
  31. data/lib/asgard/shell.rb +366 -44
  32. data/lib/asgard/state_dir.rb +90 -0
  33. data/lib/asgard/tasks.rb +8 -0
  34. data/lib/asgard/version.rb +1 -1
  35. data/lib/asgard/watch/changes.rb +26 -1
  36. data/lib/asgard/watch/commands.rb +63 -13
  37. data/lib/asgard/watch/daemon.rb +347 -52
  38. data/lib/asgard/watch/declaration.rb +135 -40
  39. data/lib/asgard/watch/dispatcher.rb +61 -10
  40. data/lib/asgard/watch/mailbox.rb +50 -0
  41. data/lib/asgard/watch/reporter.rb +54 -32
  42. data/lib/asgard/watch/spawn.rb +43 -18
  43. data/lib/asgard/watch/state.rb +93 -27
  44. data/lib/asgard/watch/worker.rb +44 -9
  45. data/lib/asgard/watch.rb +4 -11
  46. data/lib/asgard.rb +100 -16
  47. metadata +170 -186
  48. data/.envrc +0 -6
  49. data/.github/workflows/deploy-github-pages.yml +0 -52
  50. data/.loki +0 -39
  51. data/.reek.yml +0 -166
  52. data/.rubocop.yml +0 -163
  53. data/Archspec.rb +0 -24
  54. data/CLAUDE.md +0 -139
  55. data/COMMITS.md +0 -196
  56. data/bin/console +0 -11
  57. data/bin/setup +0 -8
  58. data/doc_tasks.loki +0 -21
  59. data/docs/api.md +0 -368
  60. data/docs/assets/css/custom.css +0 -93
  61. data/docs/assets/images/asgard.jpg +0 -0
  62. data/docs/changelog.md +0 -1
  63. data/docs/dependencies.md +0 -313
  64. data/docs/environment.md +0 -129
  65. data/docs/examples.md +0 -194
  66. data/docs/getting-started.md +0 -181
  67. data/docs/helpers.md +0 -262
  68. data/docs/index.md +0 -87
  69. data/docs/options.md +0 -224
  70. data/docs/schedule.md +0 -106
  71. data/docs/shell.md +0 -237
  72. data/docs/subcommands.md +0 -181
  73. data/docs/task-files.md +0 -407
  74. data/docs/tasks.md +0 -326
  75. data/docs/variables.md +0 -338
  76. data/docs/watch.md +0 -123
  77. data/examples/.env +0 -4
  78. data/examples/.envrc +0 -3
  79. data/examples/.loki +0 -24
  80. data/examples/bad.loki +0 -63
  81. data/examples/concurrent.loki +0 -58
  82. data/examples/confirm.loki +0 -48
  83. data/examples/db_subcommands.loki +0 -74
  84. data/examples/depends_on_block/bad/.loki +0 -51
  85. data/examples/depends_on_block/good/.loki +0 -83
  86. data/examples/do.loki +0 -45
  87. data/examples/env_usage.loki +0 -27
  88. data/examples/kitchen_sink.loki +0 -210
  89. data/examples/server_subcommands.loki +0 -65
  90. data/examples/subdir/.loki +0 -12
  91. data/examples/subdir/import_demo.loki +0 -14
  92. data/examples/subdir/import_up_demo.loki +0 -18
  93. data/examples/watcher_examples/.envrc +0 -3
  94. data/examples/watcher_examples/.loki +0 -54
  95. data/examples/watcher_examples/README.md +0 -112
  96. data/examples/watcher_examples/bin/hello +0 -3
  97. data/examples/watcher_examples/data/records.json +0 -1
  98. data/examples/watcher_examples/docs/drafts/ideas.md +0 -5
  99. data/examples/watcher_examples/docs/index.md +0 -4
  100. data/examples/watcher_examples/lib/greeter.rb +0 -7
  101. data/gem_tasks.loki +0 -51
  102. data/git.loki +0 -13
  103. data/mkdocs.yml +0 -166
  104. data/quality.loki +0 -266
  105. data/quality_rails.loki +0 -47
  106. data/xyzzy.loki +0 -12
data/lib/asgard/shell.rb CHANGED
@@ -1,59 +1,381 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'English'
3
+ require "English"
4
+ require "shellwords"
5
+ require_relative "pid"
4
6
  require "tempfile"
7
+ require_relative "schedule/declaration"
5
8
 
6
9
  module Asgard
10
+ # `shebang` is the one way a task runs something that isn't Ruby. The script
11
+ # is written to a tempfile and the file is handed to an interpreter from the
12
+ # `shells` registry, so one line and fifty lines take the same path:
13
+ #
14
+ # shebang :bash, "rake build"
15
+ # shebang :python3, <<~PY
16
+ # print("hi")
17
+ # PY
18
+ #
19
+ # The name may be left out, and `sh script` is the same call: both run the
20
+ # `default_shell`, which starts as :bash. The registry maps a name to the
21
+ # executable, the arguments placed before the script, and the tempfile
22
+ # extension:
23
+ #
24
+ # Tasks.shells[:bash] # => { path: "bash", args: [], ext: ".sh" }
25
+ #
26
+ # `shell` at class level adds or replaces an entry. A name that isn't
27
+ # registered runs as itself, found on PATH, with a `.tmp` extension.
7
28
  module Shell
8
- # Run a shell script. Multiline strings are passed to bash -c; single-line
9
- # strings are passed to system directly. Exits with the command's status
10
- # code on failure.
29
+ # The extension a declaration gets when `ext:` is omitted, keyed by the
30
+ # basename of its executable. Node needs `.js` to load ES modules.
31
+ DEFAULT_EXTENSIONS = {
32
+ "bash" => ".sh", "sh" => ".sh", "zsh" => ".sh", "fish" => ".fish", "csh" => ".csh", "tcsh" => ".csh",
33
+ "python3" => ".py", "python" => ".py",
34
+ "node" => ".js", "ruby" => ".rb", "perl" => ".pl"
35
+ }.freeze
36
+
37
+ SEEDED_SHELLS = %w[bash sh python3 python node ruby perl].freeze
38
+
39
+ class << self
40
+ # The registry: name => { path:, args:, ext: }. One table for every
41
+ # Tasks subclass, seeded with the interpreters above.
42
+ def shells
43
+ @shells ||= SEEDED_SHELLS.to_h { |name| [name.to_sym, entry(name)] }
44
+ end
45
+
46
+ # The shell `sh` and a nameless `shebang` run; :bash until a .loki says
47
+ # otherwise.
48
+ def default_shell(name = nil)
49
+ @default_shell = name.to_sym if name
50
+ @default_shell ||= :bash
51
+ end
52
+
53
+ # Restore the seeded registry and default (tests).
54
+ def reset_shells!
55
+ @shells = nil
56
+ @default_shell = nil
57
+ end
58
+
59
+ # Build a normalized entry. A String +path+ is split with Shellwords:
60
+ # the first word is the executable, the rest are arguments and come
61
+ # before +args+, which may be a String (also Shellwords-split) or an
62
+ # Array. A Pathname +path+ is the executable as is, spaces and all.
63
+ # +ext+ is derived from the executable's basename when omitted.
64
+ def entry(path, args: nil, ext: nil)
65
+ words = path_words(path)
66
+ raise ArgumentError, "shell path is empty" if words.empty?
67
+
68
+ executable = words.shift
69
+ {
70
+ path: executable,
71
+ args: (words + split_args(args)).freeze,
72
+ ext: ext || DEFAULT_EXTENSIONS.fetch(File.basename(executable), ".tmp")
73
+ }.freeze
74
+ end
75
+
76
+ def split_args(args)
77
+ case args
78
+ when nil then []
79
+ when String then Shellwords.split(args)
80
+ else Array(args).map(&:to_s)
81
+ end
82
+ end
83
+
84
+ # The executable and any leading arguments a path gives: a Pathname
85
+ # names one file and is never split; anything else is a String with
86
+ # shell quoting.
87
+ def path_words(path)
88
+ return path.to_s.empty? ? [] : [path.to_s] if path.is_a?(Pathname)
89
+
90
+ Shellwords.split(path.to_s)
91
+ end
92
+
93
+ # The name a bare path registers under: the executable's basename.
94
+ # "/usr/local/bin/bash -c -w" is :bash, "uv run --script" is :uv.
95
+ def name_for(entry) = File.basename(entry[:path]).to_sym
96
+
97
+ # The file an entry's executable names, or nil: a path with a
98
+ # directory part must be an executable file as given (no ~ or PATH
99
+ # expansion, since none happens when it runs); a bare name must be
100
+ # found on +env_path+.
101
+ def resolve(executable, env_path = ENV.fetch("PATH", nil))
102
+ return Schedule.which(executable, env_path) unless executable.include?(File::SEPARATOR)
103
+
104
+ executable if File.file?(executable) && File.executable?(executable)
105
+ end
106
+
107
+ # +entry+ when its executable resolves; ArgumentError naming the
108
+ # shell otherwise, so a .loki fails as it loads rather than with an
109
+ # exit 127 the first time a task runs.
110
+ def validate!(name, entry, env_path = ENV.fetch("PATH", nil))
111
+ return entry if resolve(entry[:path], env_path)
112
+
113
+ problem = entry[:path].include?(File::SEPARATOR) ? "is not an executable file" : "is not an executable on PATH"
114
+ raise ArgumentError, "shell #{name.inspect}: #{entry[:path]} #{problem}"
115
+ end
116
+
117
+ # The entry for +name+, or a bare fallback that runs +name+ itself as
118
+ # found on PATH.
119
+ def shell_for(name)
120
+ shells.fetch(name.to_sym) { { path: name.to_s, args: [].freeze, ext: DEFAULT_EXTENSIONS.fetch(name.to_s, ".tmp") }.freeze }
121
+ end
122
+
123
+ # The argv that runs +file+ with +shell+.
124
+ def argv(shell, file)
125
+ [shell[:path], *shell[:args], file]
126
+ end
127
+
128
+ # A process's exit code as a shell reports it: its status, or 128
129
+ # plus the signal number when a signal ended it.
130
+ def exit_code(status) = status.exitstatus || (128 + status.termsig)
131
+ end
132
+
133
+ module ClassMethods
134
+ def shells = Shell.shells
135
+
136
+ # `default_shell :zsh` selects the shell `sh` runs, leaving the
137
+ # registry alone; with no argument it returns the current name. Any
138
+ # other form registers first, through `shell`, then selects:
139
+ #
140
+ # default_shell "/usr/local/bin/bash -c -w" # :bash
141
+ # default_shell :strict, "bash", args: "-eu -o pipefail"
142
+ # default_shell :zsh, args: "-f" # path is the name
143
+ def default_shell(name_or_path = nil, path = nil, args: nil, ext: nil)
144
+ return Shell.default_shell unless name_or_path
145
+
146
+ selecting = name_or_path.is_a?(Symbol) && !(path || args || ext)
147
+ Shell.default_shell(selecting ? selectable!(name_or_path) : shell(name_or_path, path, args:, ext:))
148
+ end
149
+
150
+ # Register a shell and return its name. With a Symbol first:
151
+ #
152
+ # shell :strict, "bash -eu -o pipefail"
153
+ # shell :uv, "uv run --script", ext: ".py"
154
+ # shell :fish # fish from PATH, defaults
155
+ #
156
+ # With a bare path (String or Pathname) the name is the executable's
157
+ # basename, and any options in the string are parsed into args:
158
+ #
159
+ # shell "/usr/local/bin/bash -c -w" # :bash, args ["-c", "-w"]
160
+ #
161
+ # The executable must exist: an executable file at that path, or a
162
+ # bare name found on PATH. Otherwise ArgumentError, as the .loki loads.
163
+ def shell(name_or_path, path = nil, args: nil, ext: nil)
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)
170
+ Shell.shells[name] = Shell.validate!(name, entry)
171
+ name
172
+ end
173
+
174
+ private
175
+
176
+ # +name+ when it is registered or runs as itself from PATH; otherwise
177
+ # ArgumentError as the .loki loads, as `shell` does for a bad path.
178
+ def selectable!(name)
179
+ return name if Shell.shells.key?(name)
180
+
181
+ Shell.validate!(name, Shell.shell_for(name))
182
+ name
183
+ end
184
+ end
185
+
186
+ def self.included(base) = base.extend(ClassMethods)
187
+
188
+ # The scripts `sh` is running right now, so that INT or TERM sent to
189
+ # asgard alone (`kill <pid>`, a process manager) reaches them too:
190
+ # asgard passes the signal on, waits for them, then exits with 128
191
+ # plus the signal's number. Only the child's own pid is signalled,
192
+ # never a process group, since the children share asgard's group.
11
193
  #
12
- # Pass exec: true to replace the current process instead of forking —
13
- # useful for a task's final, long-running command (e.g. a dev server)
14
- # so the asgard/ruby process doesn't sit resident in memory alongside it.
15
- def sh(script, silent: false, exec: false)
16
- script = script.strip
17
- $stdout.puts script unless silent
18
- argv = shell_argv(script)
19
-
20
- if exec
21
- $stdout.flush
22
- Kernel.exec(*argv)
23
- else
24
- exit($CHILD_STATUS.exitstatus) unless system(*argv)
25
- end
26
- end
27
-
28
- # Write +script+ to a tempfile and execute it with +interpreter+.
29
- # Useful for embedding Python, Node, Ruby, or any shebang-style body.
30
- def shebang(interpreter, script, silent: false)
31
- extensions = {
32
- python3: ".py", python: ".py",
33
- node: ".js",
34
- ruby: ".rb",
35
- perl: ".pl",
36
- bash: ".sh", sh: ".sh"
37
- }
38
- ext = extensions.fetch(interpreter.to_sym, ".tmp")
39
-
40
- $stdout.puts script unless silent
41
-
42
- Tempfile.create(["asgard_", ext]) do |f|
43
- f.write(script)
44
- f.flush
45
- system(interpreter.to_s, f.path)
46
- exit($CHILD_STATUS.exitstatus) unless $CHILD_STATUS.success?
194
+ # Ctrl-C at a terminal already reaches every process in the foreground
195
+ # group, children included, so the signal is passed on only to a child
196
+ # still running GRACE seconds later: a script that stops on its own
197
+ # Ctrl-C is not signalled a second time.
198
+ module Children
199
+ SIGNALS = %w[INT TERM].freeze
200
+ GRACE = 0.3
201
+
202
+ @pids = [].freeze # swapped whole, never changed: the trap reads it without a lock
203
+ @active = 0
204
+ @previous = {}
205
+ @received = nil
206
+ @mutex = Mutex.new
207
+
208
+ class << self
209
+ # The signal that arrived while a script ran, or nil.
210
+ attr_reader :received
211
+
212
+ # Runs +argv+ as a child and returns its Process::Status, or nil
213
+ # when it could not be started.
214
+ def run(argv)
215
+ enter
216
+ pid = Process.spawn(*argv)
217
+ add(pid)
218
+ Process.wait2(pid).last
219
+ rescue SystemCallError
220
+ nil
221
+ ensure
222
+ remove(pid) if pid
223
+ leave
224
+ end
225
+
226
+ # A pid asgard may signal: an Integer above 1 that is not its own.
227
+ def signalable?(pid) = pid.is_a?(Integer) && pid > 1 && pid != Process.pid
228
+
229
+ def alive?(pid) = signalable?(pid) && Pid.alive?(pid)
230
+
231
+ # 128 plus +signal+'s number, as a shell reports it; nil for nil.
232
+ def exit_status_for(signal) = signal && (128 + Signal.list.fetch(signal))
233
+
234
+ # The status asgard exits with after a signal, or nil.
235
+ def exit_status = exit_status_for(received)
236
+
237
+ # Sends +signal+ to every child still running, then to everything
238
+ # each child started. A shell killed while it waits does not pass
239
+ # the signal on, so the command it was running would be left
240
+ # behind. The tree is read before any signal, since a child that
241
+ # dies hands its own children to init.
242
+ def forward(signal, table = process_table)
243
+ @pids.each do |pid|
244
+ [pid, *descendants_of(pid, table)].each { |target| signal(signal, target) }
245
+ end
246
+ end
247
+
248
+ # Every process below +pid+ in +table+ ([pid, parent pid] pairs),
249
+ # nearest first.
250
+ def descendants_of(pid, table)
251
+ children = table.filter_map { |child, parent| child if parent == pid }
252
+ children + children.flat_map { |child| descendants_of(child, table) }
253
+ end
254
+
255
+ # [pid, parent pid] for every process in +ps_output+ (one pair per
256
+ # line); lines that are not two numbers are dropped.
257
+ def process_table(ps_output = ps_listing)
258
+ ps_output.to_s.lines.filter_map do |line|
259
+ pair = line.split.map { Integer(it, exception: false) }
260
+ pair if pair.size == 2 && pair.all?
261
+ end
262
+ end
263
+
264
+ # Every process's pid and parent pid as +ps+ prints them, or "" when
265
+ # ps cannot run (a slim image without procps). It rescues on its own:
266
+ # a default argument is evaluated outside the method's rescue, so a
267
+ # missing ps would otherwise escape forward before any signal went out.
268
+ def ps_listing(ps = Pid::PS)
269
+ IO.popen([ps, "-A", "-o", "pid=,ppid="], err: File::NULL, &:read)
270
+ rescue SystemCallError
271
+ ""
272
+ end
273
+
274
+ def signal(signal, pid)
275
+ Process.kill(signal, pid) if alive?(pid)
276
+ rescue Errno::ESRCH
277
+ nil
278
+ end
279
+
280
+ private
281
+
282
+ def add(pid) = @mutex.synchronize { @pids = [*@pids, pid].freeze }
283
+ def remove(pid) = @mutex.synchronize { @pids = (@pids - [pid]).freeze }
284
+
285
+ # The first script to start installs the traps; the last to finish
286
+ # puts the previous handlers back.
287
+ def enter = @mutex.synchronize { install_traps if (@active += 1) == 1 }
288
+ def leave = @mutex.synchronize { restore_traps if (@active -= 1).zero? }
289
+
290
+ # A signal asgard was started ignoring (INT under `cmd &`) stays
291
+ # ignored.
292
+ def install_traps
293
+ @received = nil
294
+ SIGNALS.each do |signal|
295
+ previous = Signal.trap(signal) { on_signal(signal) }
296
+ previous == "IGNORE" ? Signal.trap(signal, previous) : @previous[signal] = previous || "DEFAULT"
297
+ end
298
+ end
299
+
300
+ def restore_traps
301
+ @previous.each { |signal, handler| Signal.trap(signal, handler) }
302
+ @previous = {}
303
+ end
304
+
305
+ # Runs in trap context, where a Mutex cannot be taken: the thread
306
+ # does the waiting and the signalling.
307
+ def on_signal(signal)
308
+ @received ||= signal
309
+ Thread.new do
310
+ sleep GRACE
311
+ forward(signal)
312
+ end
313
+ end
47
314
  end
48
315
  end
49
316
 
317
+ # One shebang call: the shell name the task gave, its registry entry and
318
+ # the stripped script.
319
+ Run = Data.define(:name, :shell, :script) do
320
+ def ext = shell[:ext]
321
+ def argv(file) = Shell.argv(shell, file)
322
+ def missing_message = "asgard: shell #{name.inspect} not found: #{argv('...').shelljoin}"
323
+
324
+ # Says the shell is missing and exits 127. $stderr.puts, not warn:
325
+ # warn is silent under -W0 and this must show.
326
+ def missing!
327
+ $stderr.puts missing_message # rubocop:disable Style/StderrPuts
328
+ exit 127
329
+ end
330
+ end
331
+
332
+ # Write +script+ to a tempfile and run it with the shell registered as
333
+ # +name+, or with the default shell when only the script is given.
334
+ # Returns true; exits with the command's status code on failure. `sh`
335
+ # is the same method under a shorter name (see the alias below).
336
+ #
337
+ # background: true starts the script as a job named after the calling
338
+ # task (`doc_server-1`); a Symbol or String names the job itself. The
339
+ # call returns a Jobs::Job at once and the job outlives asgard; see
340
+ # `asgard jobs`.
341
+ def shebang(name_or_script, script = nil, silent: false, background: nil)
342
+ name, script = script ? [name_or_script, script] : [Shell.default_shell, name_or_script]
343
+ run = Run.new(name:, shell: Shell.shell_for(name), script: script.strip)
344
+ job = _background_job_name(background)
345
+ $stdout.puts run.script unless silent
346
+ job ? _start_job(run, job, silent:) : _run_script(run)
347
+ end
348
+ alias_method :sh, :shebang # rubocop:disable Style/Alias -- the method form reads as the API statement it is
349
+
50
350
  private
51
351
 
52
- # The argv passed to system/exec for +script+: multi-line scripts run
53
- # through `bash -c` so assignments carry across lines; single-line
54
- # scripts run directly.
55
- def shell_argv(script)
56
- script.include?("\n") ? ["bash", "-c", script] : [script]
352
+ # The job name a background: value asks for; only `true` consumes a
353
+ # sequence number, and only inside a task body.
354
+ def _background_job_name(background)
355
+ return nil unless background
356
+
357
+ task = current_task
358
+ sequence = _next_job_sequence if background == true && task
359
+ Jobs.job_name(background, task:, sequence:)
360
+ end
361
+
362
+ def _start_job(run, name, silent:)
363
+ root = Asgard.project_root
364
+ state = Jobs::State.new(project: Schedule.project_slug(root), root:)
365
+ Jobs::Launcher.start(run, name:, task: current_task, state:, silent:)
366
+ end
367
+
368
+ def _run_script(run)
369
+ Tempfile.create(["asgard_", run.ext]) do |f|
370
+ f.write(run.script)
371
+ f.flush
372
+ status = Children.run(run.argv(f.path))
373
+ run.missing! unless status
374
+ signalled = Children.exit_status
375
+ exit(signalled) if signalled
376
+ exit(Shell.exit_code(status)) unless status.success?
377
+ true
378
+ end
57
379
  end
58
380
  end
59
381
  end
@@ -0,0 +1,90 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "fileutils"
4
+ require "json"
5
+ require "tempfile"
6
+
7
+ module Asgard
8
+ # The layout every kind of per-project state shares: a directory per
9
+ # project under $XDG_STATE_HOME/asgard/<kind>/<project-slug>/ (by default
10
+ # ~/.local/state), a file in it naming the project root so a machine-wide
11
+ # listing can find every project without loading its .loki, and JSON
12
+ # records written whole then renamed. The watcher files its state under
13
+ # "watch" and background jobs under "jobs".
14
+ module StateDir
15
+ ROOT_FILE = "root"
16
+
17
+ # The size a log may reach before it is rotated, unless ASGARD_LOG_MAX
18
+ # (bytes) says otherwise.
19
+ LOG_MAX = 10 * 1024 * 1024
20
+
21
+ module_function
22
+
23
+ def base_dir(kind, home: Dir.home, env: ENV)
24
+ File.join(env["XDG_STATE_HOME"] || File.join(home, ".local", "state"), "asgard", kind.to_s)
25
+ end
26
+
27
+ # Every project with a state directory under base, as [slug, root] pairs.
28
+ def all(kind = nil, base: base_dir(kind))
29
+ Dir.glob(File.join(base, "*", ROOT_FILE)).map do |file|
30
+ [File.basename(File.dirname(file)), File.read(file).strip]
31
+ end
32
+ end
33
+
34
+ # Written whole then renamed, so a reader never sees a partial file.
35
+ # The tempfile is a dotfile: a "*.json" glob or a name pattern that
36
+ # lists records never picks up one that is still being written.
37
+ def write_json(path, value)
38
+ dir = File.dirname(path)
39
+ FileUtils.mkdir_p(dir)
40
+ Tempfile.create([".asgard", ".json"], dir) do |file|
41
+ file.write(JSON.pretty_generate(value))
42
+ file.flush
43
+ File.rename(file.path, path)
44
+ end
45
+ end
46
+
47
+ # The parsed record, or nil when there is none or it is not JSON (a
48
+ # disk that filled up, a hand edit): one bad file must not take down
49
+ # every listing that reads it.
50
+ def read_json(path)
51
+ return nil unless File.exist?(path)
52
+
53
+ JSON.parse(File.read(path), symbolize_names: true)
54
+ rescue JSON::ParserError
55
+ nil
56
+ end
57
+
58
+ # The log size limit: ASGARD_LOG_MAX when it is a positive number of
59
+ # bytes, else LOG_MAX.
60
+ def log_limit(env = ENV)
61
+ bytes = Integer(env["ASGARD_LOG_MAX"].to_s, exception: false)
62
+ bytes&.positive? ? bytes : LOG_MAX
63
+ end
64
+
65
+ # Moves +path+ to +path+.1 (replacing an older one) once it is larger
66
+ # than +max_bytes+; the new name when it did, else nil. A task still
67
+ # writing to the old file carries on into path.1, and the next line
68
+ # starts a fresh file.
69
+ def rotate(path, max_bytes:)
70
+ return nil unless File.exist?(path) && File.size(path) > max_bytes
71
+
72
+ File.rename(path, "#{path}.1")
73
+ "#{path}.1"
74
+ end
75
+
76
+ # Creates +dir+, readable by its owner only (logs and job scripts can
77
+ # hold secrets), and records the project root in it.
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)
86
+ FileUtils.mkdir_p(dir, mode: 0o700)
87
+ File.chmod(0o700, dir)
88
+ end
89
+ end
90
+ end
data/lib/asgard/tasks.rb CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  require_relative "schedule"
4
4
  require_relative "watch"
5
+ require_relative "jobs"
5
6
 
6
7
  # Tasks is the single conventional entry point for all .loki files.
7
8
  # It is pre-defined by the gem so .loki files never need to declare a class.
@@ -18,11 +19,13 @@ class Tasks < Asgard::Base
18
19
  type: :boolean,
19
20
  default: false,
20
21
  desc: "Enable debug mode ($DEBUG = true)"
22
+ no_negate :debug
21
23
 
22
24
  class_option :verbose,
23
25
  type: :boolean,
24
26
  default: false,
25
27
  desc: "Enable verbose output ($VERBOSE = true)"
28
+ no_negate :verbose
26
29
 
27
30
  class_option :version,
28
31
  type: :boolean,
@@ -53,4 +56,9 @@ class Tasks < Asgard::Base
53
56
  subcommand "_watcher", Asgard::Watch::Commands
54
57
  map "watcher" => :_watcher
55
58
  Asgard::Watch::Commands.commands.each_value { |command| command.ancestor_name = "watcher" }
59
+
60
+ desc "jobs SUBCOMMAND", "List, stop and restart the background jobs started with `sh ..., background: true`"
61
+ subcommand "_jobs", Asgard::Jobs::Commands
62
+ map "jobs" => :_jobs
63
+ Asgard::Jobs::Commands.commands.each_value { |command| command.ancestor_name = "jobs" }
56
64
  end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Asgard
4
- VERSION = "0.5.1"
4
+ VERSION = "0.6.1"
5
5
  end
@@ -1,13 +1,18 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "json"
4
+
3
5
  module Asgard
4
6
  # The files a watcher trigger saw change, as three lists of paths relative
5
7
  # to the project root. The watcher hands them to the task through three
6
8
  # environment variables (newline-separated, since paths may hold spaces
7
9
  # or colons); the `changes` Kernel method reads them back. Every list is
8
10
  # empty when the task is run by hand, so one task body serves both.
11
+ # Lists too big for the environment come in a JSON file named by
12
+ # ASGARD_CHANGES_FILE instead.
9
13
  class Changes < Data.define(:modified, :added, :removed)
10
14
  VARIABLES = { modified: "ASGARD_MODIFIED", added: "ASGARD_ADDED", removed: "ASGARD_REMOVED" }.freeze
15
+ FILE_VARIABLE = "ASGARD_CHANGES_FILE"
11
16
 
12
17
  class << self
13
18
  # The changes behind this process, read once from ENV. Tests and a
@@ -17,7 +22,20 @@ module Asgard
17
22
  def forget = @current = nil
18
23
 
19
24
  # Parses the trigger variables; a missing one is an empty list.
20
- def from_env(env = ENV) = new(**VARIABLES.to_h { |member, variable| [member, env[variable].to_s.split("\n")] })
25
+ def from_env(env = ENV)
26
+ file = env[FILE_VARIABLE].to_s
27
+ return from_file(file) unless file.empty?
28
+
29
+ new(**VARIABLES.to_h { |member, variable| [member, env[variable].to_s.split("\n")] })
30
+ end
31
+
32
+ # The lists a spilled trigger wrote; empty once the file is gone.
33
+ def from_file(path)
34
+ lists = JSON.parse(File.read(path), symbolize_names: true)
35
+ new(**VARIABLES.keys.to_h { |member| [member, Array(lists[member])] })
36
+ rescue Errno::ENOENT
37
+ new
38
+ end
21
39
  end
22
40
 
23
41
  def initialize(modified: [], added: [], removed: [])
@@ -40,6 +58,13 @@ module Asgard
40
58
 
41
59
  module_function
42
60
 
61
+ # One Changes holding every path of +list+, each kind in first-seen
62
+ # order without repeats: what several triggers that waited for the same
63
+ # busy task hand its next run.
64
+ def merge_changes(list)
65
+ Changes.new(**Changes.members.to_h { |member| [member, list.flat_map(&member).uniq] })
66
+ end
67
+
43
68
  # A listener batch ({ modified:, added:, removed: }) narrowed to the
44
69
  # kinds in events (a Set from normalize_events), as a Changes; nil
45
70
  # when nothing is left, so the dispatcher skips the trigger.