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/README.md CHANGED
@@ -3,6 +3,9 @@
3
3
  > [!INFO]
4
4
  > See the [CHANGELOG](CHANGELOG.md) for the latest changes. The [examples directory](examples/) contains working `.loki` files demonstrating the full feature set.
5
5
 
6
+ > [!WARNING]
7
+ > Version 0.6.0 has breaking changes to scheduled tasks, watchers and `sh`. Read [Breaking Changes](https://madbomber.github.io/asgard/breaking-changes/) before you upgrade.
8
+
6
9
  <br>
7
10
  <table>
8
11
  <tr>
@@ -13,27 +16,30 @@
13
16
  <td width="60%" valign="top">
14
17
  <strong>Key Features</strong><br>
15
18
 
16
- - <strong>Thor-Powered CLI</strong> — every Thor DSL feature available inside <code>.loki</code> task files<br>
17
- - <strong>Task Dependencies</strong> — sequential, parallel, and mixed dependency graphs via <code>depends_on</code><br>
18
- - <strong>Concurrent Execution</strong> — parallel task groups run in native Ruby threads<br>
19
- - <strong>Subcommands</strong> — group related tasks under a named namespace<br>
20
- - <strong>Variables</strong> — shared configuration via Ruby class variables (<code>@@name</code>), visible across all tasks and subcommands<br>
21
- - <strong>`helper` DSL</strong> — define a method once, available in both class-level DSL calls (<code>header</code>) and inside task instance methods<br>
22
- - <strong>Shell Helpers</strong> — <code>sh</code> for any shell command or heredoc; <code>shebang</code> for polyglot scripts<br>
23
- - <strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code><br>
24
- - <strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories<br>
25
- - <strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files, loaded via <code>import</code> from your <code>.loki</code><br>
26
- - <strong>Scheduled Tasks</strong> — run any task periodically under launchd (macOS) or systemd timers (Linux) with <code>schedule</code> and <code>asgard schedule install</code><br>
27
- - <strong>Watched Files</strong> — run any task when files change with <code>watch</code> and <code>asgard watcher start</code>; the task reads what changed through <code>changes</code><br>
28
- - <strong>Built-in Flags</strong> — <code>--debug</code>, <code>--verbose</code>, <code>--version</code>, and <code>--doctor</code> built-in class options; header/footer DSL for static help text<br>
19
+ - <strong>Thor-Powered CLI</strong>: every Thor DSL feature available inside <code>.loki</code> task files<br>
20
+ - <strong>Task Dependencies</strong>: sequential, parallel, and mixed dependency graphs via <code>depends_on</code><br>
21
+ - <strong>Concurrent Execution</strong>: parallel task groups run in native Ruby threads<br>
22
+ - <strong>Subcommands</strong>: group related tasks under a named namespace<br>
23
+ - <strong>Variables</strong>: shared configuration via Ruby class variables (<code>@@name</code>), visible across all tasks and subcommands<br>
24
+ - <strong>`helper` DSL</strong>: define a method once, available in both class-level DSL calls (<code>header</code>) and inside task instance methods<br>
25
+ - <strong>Shell Helpers</strong>: <code>sh</code> (alias <code>shebang</code>) runs a command or heredoc under the default shell, or under any registered interpreter when you name one<br>
26
+ - <strong>Dotenv Support</strong>: load <code>.env</code> files into the environment with <code>dotenv</code><br>
27
+ - <strong>Auto-Discovery</strong>: <code>.loki</code> root marker searched from CWD upward through parent directories<br>
28
+ - <strong>Multi-File Tasks</strong>: split tasks across <code>*.loki</code> files, loaded via <code>import</code> from your <code>.loki</code><br>
29
+ - <strong>Scheduled Tasks</strong>: run any task periodically under launchd (macOS) or systemd timers (Linux) with <code>schedule</code> and <code>asgard schedule install</code><br>
30
+ - <strong>Watched Files</strong>: run any task when files change with <code>watch</code> and <code>asgard watcher start</code>; the task reads what changed through <code>changes</code><br>
31
+ - <strong>Background Jobs</strong>: <code>sh "mkdocs serve", background: true</code> starts a job that outlives asgard; <code>asgard jobs</code> lists, stops, restarts and cleans them<br>
32
+ - <strong>Built-in Flags</strong>: <code>--debug</code>, <code>--verbose</code>, <code>--version</code>, and <code>--doctor</code> built-in class options; header/footer DSL for static help text<br>
29
33
  </td>
30
34
  </tr>
31
35
  </table>
32
36
 
33
- <p>Asgard is a <a href="https://github.com/rails/thor">Thor</a>-based task runner for Ruby projects. Define tasks in <code>.loki</code> files, declare dependencies between them, and let Asgard handle ordering and concurrent execution. Anything Thor can do — subcommands, typed options, argument validation — is available inside a <code>.loki</code> file.</p>
37
+ <p>Asgard is a <a href="https://github.com/rails/thor">Thor</a>-based task runner for Ruby projects. Define tasks in <code>.loki</code> files, declare dependencies between them, and let Asgard handle ordering and concurrent execution. Anything Thor can do (subcommands, typed options, argument validation) is available inside a <code>.loki</code> file.</p>
34
38
 
35
39
  ## Installation
36
40
 
41
+ Asgard requires Ruby 4.0 or later. Scheduled tasks and the file watcher need macOS or Linux, background jobs need a POSIX system (`fork`, `setsid` and `/bin/sh`), and installing compiles one native extension, so a C++17 compiler must be available (Xcode's command-line tools or a distribution's `build-essential` package).
42
+
37
43
  ```bash
38
44
  gem install asgard
39
45
  ```
@@ -48,7 +54,7 @@ bundle add asgard
48
54
 
49
55
  ## Tasks
50
56
 
51
- Every `.loki` file defines tasks as methods inside `class Tasks`. The `Tasks` class is pre-defined by the gem — just reopen it and add methods.
57
+ Every `.loki` file defines tasks as methods inside `class Tasks`. The `Tasks` class is pre-defined by the gem; just reopen it and add methods.
52
58
 
53
59
  ### A task with no parameters
54
60
 
@@ -81,7 +87,7 @@ asgard hello Alice
81
87
 
82
88
  ### A task with a formal argument declaration
83
89
 
84
- Use `argument` for richer metadata — type checking, enums, and help text. **Warning: `argument` is a class-level declaration that applies to every task in the class**, not just the one below it. It is best suited for single-command CLIs or when every task genuinely shares the same positional input. In multi-task files, prefer method signature parameters instead.
90
+ Use `argument` for richer metadata: type checking, enums, and help text. **Warning: `argument` is a class-level declaration that applies to every task in the class**, not just the one below it. It is best suited for single-command CLIs or when every task genuinely shares the same positional input. In multi-task files, prefer method signature parameters instead.
85
91
 
86
92
  ```ruby
87
93
  class Tasks
@@ -142,7 +148,7 @@ end
142
148
 
143
149
  `depends_on` declares what must run before a task. Each dependency runs at most once per `asgard` invocation regardless of how many tasks declare it. Circular dependencies are caught at startup.
144
150
 
145
- `desc` and `depends_on` are independent — either can come first, both must appear before `def`.
151
+ `desc` and `depends_on` are independent: either can come first, but both must appear before `def`.
146
152
 
147
153
  ### Sequential dependencies
148
154
 
@@ -192,7 +198,7 @@ asgard test # lint ∥ typecheck → test
192
198
 
193
199
  ### Mixed sequential and parallel
194
200
 
195
- Mix bare symbols (sequential) and arrays (parallel) in a single `depends_on` call. Execution proceeds stage by stage — each stage must complete before the next begins:
201
+ Mix bare symbols (sequential) and arrays (parallel) in a single `depends_on` call. Execution proceeds stage by stage; each stage must complete before the next begins:
196
202
 
197
203
  ```ruby
198
204
  class Tasks
@@ -223,7 +229,7 @@ asgard ci executes:
223
229
  ci
224
230
  ```
225
231
 
226
- `depends_on` also accepts a `Proc`/lambda (or, equivalently, a block) instead of a fixed list, resolved once every `.loki` file has finished loading rather than immediately — useful when the list can't be known upfront, e.g. "every task whose name ends in `_check`," discovered across several files:
232
+ `depends_on` also accepts a `Proc`/lambda (or, equivalently, a block) instead of a fixed list, resolved once every `.loki` file has finished loading rather than immediately. This is useful when the list can't be known upfront, e.g. "every task whose name ends in `_check`," discovered across several files:
227
233
 
228
234
  ```ruby
229
235
  depends_on -> { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
@@ -232,7 +238,7 @@ def quality = puts "running every *_check task..."
232
238
  depends_on { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
233
239
  def quality2 = puts "same, as a block..."
234
240
 
235
- # do...end for a block spanning multiple statements — braces are for
241
+ # do...end for a block spanning multiple statements; braces are for
236
242
  # single-line blocks like the two above. The last expression is still what
237
243
  # gets returned and validated.
238
244
  depends_on do
@@ -244,7 +250,7 @@ end
244
250
  def quality3 = puts "same, minus the slow checks, as a multi-line block..."
245
251
  ```
246
252
 
247
- See [Dependencies](https://madbomber.github.io/asgard/dependencies/#dynamic-dependencies-proc-block-form) for the full explanation.
253
+ See [Dependencies](https://madbomber.github.io/asgard/dependencies/#dynamic-dependencies) for the full explanation.
248
254
 
249
255
  ---
250
256
 
@@ -266,13 +272,13 @@ class Tasks
266
272
  end
267
273
  ```
268
274
 
269
- Class variables are visible in all task instance methods and in subcommand subclasses — unlike class instance variables (`@name`), which are not accessible inside instance methods.
275
+ Class variables are visible in all task instance methods and in subcommand subclasses, unlike class instance variables (`@name`), which are not accessible inside instance methods.
270
276
 
271
277
  ---
272
278
 
273
279
  ## Helper methods
274
280
 
275
- Private methods are callable from any task in the same class but are never registered as commands — they won't appear in `--help` output and can't be invoked from the CLI.
281
+ Private methods are callable from any task in the same class but are never registered as commands: they won't appear in `--help` output and can't be invoked from the CLI.
276
282
 
277
283
  ```ruby
278
284
  class Tasks
@@ -297,6 +303,8 @@ class Tasks
297
303
  def package(ver)
298
304
  sh "tar czf pkg/myapp-#{ver}.tar.gz bin/"
299
305
  end
306
+
307
+ def version = File.read("VERSION").strip
300
308
  end
301
309
  ```
302
310
 
@@ -328,7 +336,7 @@ def self.version = File.read(...).match(...)[1].freeze
328
336
  no_commands { private def version = self.class.version }
329
337
  ```
330
338
 
331
- `helper` accepts positional arguments, keyword arguments, and blocks — any signature valid in a Ruby method definition:
339
+ `helper` accepts positional arguments, keyword arguments, and blocks: any signature valid in a Ruby method definition:
332
340
 
333
341
  ```ruby
334
342
  helper(:tag) { |name, ver, prefix: "v"| "#{prefix}#{name}-#{ver}" }
@@ -365,7 +373,7 @@ Add static text above and below the command list in `asgard help` output:
365
373
 
366
374
  ```ruby
367
375
  class Tasks
368
- header "my-project — build & release tasks"
376
+ header "my-project: build & release tasks"
369
377
  footer "See https://example.com/docs for details"
370
378
  end
371
379
  ```
@@ -389,7 +397,10 @@ end
389
397
  ```
390
398
 
391
399
  ```
400
+ asgard v0.6.0 The Mighty Thor and Loki working for you
401
+
392
402
  my-project
403
+
393
404
  deploy targets: staging, production
394
405
 
395
406
  Commands:
@@ -399,7 +410,12 @@ Options:
399
410
  ...
400
411
 
401
412
  See runbook at wiki/deploy
413
+
402
414
  Maintainer: you@example.com
415
+
416
+
417
+ Documentation ... https://madbomber.github.io/asgard
418
+ Github Repo ..... https://github.com/MadBomber/asgard
403
419
  ```
404
420
 
405
421
  Header and footer text is only shown for the general `asgard help` page, not for `asgard help <command>`.
@@ -429,7 +445,7 @@ end
429
445
 
430
446
  ## Shell helpers
431
447
 
432
- `sh` runs any shell command or multiline heredoc. `shebang` writes a script body to a tempfile and executes it with the given interpreter. Both exit with the command's status code on failure.
448
+ `sh` writes a script body to a tempfile and runs it with a registered interpreter; given a script alone it uses the `default_shell` (bash), for one line or a heredoc. `shebang` is the same method under a longer name, which many authors reserve for scripts in another language. Both return `true` and exit with the command's status code on failure.
433
449
 
434
450
  ```ruby
435
451
  class Tasks
@@ -462,7 +478,18 @@ class Tasks
462
478
  end
463
479
  ```
464
480
 
465
- Supported interpreters: `:python3`, `:python`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`. Any other symbol is passed directly to `system` with a `.tmp` extension.
481
+ Registered shells: `:bash`, `:sh`, `:python3`, `:python`, `:node`, `:ruby`, `:perl`. Any other symbol runs as itself from `PATH` with a `.tmp` extension, except zsh, fish, csh and tcsh, which get `.sh`, `.fish` and `.csh`. Register your own, with a pinned path or options in front of the script, with `shell`:
482
+
483
+ ```ruby
484
+ class Tasks
485
+ shell :bash, "/opt/homebrew/bin/bash" # what sh and shebang :bash run
486
+ shell :strict, "bash -eu -o pipefail"
487
+ shell :uv, "uv run --script", ext: ".py"
488
+ default_shell :strict # what sh and a nameless shebang run
489
+ end
490
+ ```
491
+
492
+ The name may be left out: `shell "/usr/local/bin/bash -c -w"` registers `:bash`, named after the executable, with the options as its `args`. `default_shell` registers and selects in one line the same way: `default_shell "/usr/local/bin/bash -c -w"`, or `default_shell :strict, "bash", args: "-eu -o pipefail"`. A bare `default_shell :bash` only selects and leaves a pinned entry alone.
466
493
 
467
494
  Pass `silent: true` to both `sh` and `shebang` to suppress the script echo:
468
495
 
@@ -478,7 +505,7 @@ PY
478
505
 
479
506
  ## Environment variables
480
507
 
481
- `dotenv` loads a `.env` file into the environment before tasks run. Use the `env` Kernel method to read environment variables inside task bodies — it accepts a symbol or string and upcases the key automatically:
508
+ `dotenv` loads a `.env` file into the environment before tasks run. Use the `env` Kernel method to read environment variables inside task bodies. It accepts a symbol or string and upcases the key automatically:
482
509
 
483
510
  ```ruby
484
511
  class Tasks
@@ -501,13 +528,13 @@ end
501
528
  |------|-----------|
502
529
  | `env(:port, "3000")` | Returns `"3000"` when `PORT` is unset |
503
530
  | `env(:api_key)` | Raises `KeyError` when `API_KEY` is missing |
504
- | `env("DATABASE_URL")` | String name works too — always upcased |
531
+ | `env("DATABASE_URL")` | String name works too; always upcased |
505
532
 
506
533
  ---
507
534
 
508
535
  ## Abbreviated command matching
509
536
 
510
- Every task is a Thor command, so you don't have to type the full name — Thor resolves any unambiguous prefix automatically, with no extra code:
537
+ Every task is a Thor command, so you don't have to type the full name: Thor resolves any unambiguous prefix automatically, with no extra code:
511
538
 
512
539
  ```ruby
513
540
  class Tasks
@@ -523,12 +550,12 @@ end
523
550
  ```
524
551
 
525
552
  ```bash
526
- asgard b # same as: asgard build — only task starting with "b"
553
+ asgard b # same as: asgard build (only task starting with "b")
527
554
  asgard depl # Ambiguous command depl matches [deploy, deploy_staging]
528
- asgard deploy # runs deploy — an exact match always wins, even over a shorter ambiguous prefix
555
+ asgard deploy # runs deploy; an exact match always wins, even over a shorter ambiguous prefix
529
556
  ```
530
557
 
531
- This is Thor's own dispatch behavior, not an Asgard feature — it applies to every task in every `.loki` file automatically. When a prefix matches more than one task, Thor lists the candidates instead of guessing; type enough of the name to disambiguate, or use `map` (below) to pin a short name that stays stable even if a later-added task would otherwise make it ambiguous.
558
+ This is Thor's own dispatch behavior, not an Asgard feature; it applies to every task in every `.loki` file automatically. When a prefix matches more than one task, Thor lists the candidates instead of guessing; type enough of the name to disambiguate, or use `map` (below) to pin a short name that stays stable even if a later-added task would otherwise make it ambiguous.
532
559
 
533
560
  ---
534
561
 
@@ -632,10 +659,12 @@ asgard schedule stop NAME # stop one entry (persists across reboots and ins
632
659
  asgard schedule start NAME # start a stopped entry, or install just this one
633
660
  asgard schedule trigger NAME # run an installed entry now
634
661
  asgard schedule log NAME [-f] # print (or follow) the entry's log
635
- asgard schedule remove # remove all of this project's entries
662
+ asgard schedule truncate_log [NAME] --lines M # keep the last M lines of the log (default 1000; no NAME: all; -n: dry run)
663
+ asgard schedule remove [NAME] # remove one entry, or all of this project's
664
+ asgard schedule prune [-n] # remove every project's entries whose directory is gone (-n: list only)
636
665
  ```
637
666
 
638
- `stop`, `start`, `trigger` and `log` also take an entry of another project
667
+ `stop`, `start`, `trigger`, `log` and `remove` also take an entry of another project
639
668
  (`list --all` shows them); write `project/name` when two projects share a name.
640
669
 
641
670
  Jobs run `asgard <task> [options]` from the directory holding `.loki`, with
@@ -667,9 +696,11 @@ Then manage the watcher with the built-in `watcher` command:
667
696
  ```bash
668
697
  asgard watcher start # watch this project in the background
669
698
  asgard watcher stop # stop it; a task already running finishes first
699
+ asgard watcher stop --force # stop it and end any running task
670
700
  asgard watcher list # watches, daemon state, each entry's last run (--all: every project's)
671
701
  asgard watcher preview # the command and environment each watch would run
672
702
  asgard watcher log [-f] # print (or follow) the watcher's log
703
+ asgard watcher truncate_log --lines M # keep the last M lines (default 1000) of watcher.log and watcher.log.1
673
704
  ```
674
705
 
675
706
  Each trigger runs `asgard <task>` from the project root with a fixed
@@ -679,6 +710,45 @@ overlaps itself. Saving a `.loki` file restarts the watcher with the new
679
710
  declarations. See [Watched Files](https://madbomber.github.io/asgard/watch/)
680
711
  for every keyword, the environment, and file locations.
681
712
 
713
+ ## Background jobs
714
+
715
+ A script runs in one of three modes. `sh "rake build"` is the foreground:
716
+ the task waits for it and a failure exits asgard. `sh "mkdocs serve",
717
+ background: true` starts a managed job: the task continues at once, the
718
+ job runs on in its own session with its output in a log, it is still
719
+ running when asgard exits, and `asgard jobs` manages it from then on. A
720
+ trailing `&` in the script is the third mode, detached: the shell exits,
721
+ asgard reports success and keeps no record, and the process is yours to
722
+ find and kill by hand.
723
+
724
+ ```ruby
725
+ class Tasks
726
+ desc "doc_server", "Serve the documentation"
727
+ def doc_server = sh "mkdocs serve", background: true # job doc_server-1
728
+
729
+ desc "servers", "Bring up the development stack"
730
+ def servers
731
+ sh "docker compose up postgres", background: true # servers-1
732
+ sh "bin/rails server", background: :api # api
733
+ end
734
+ end
735
+ ```
736
+
737
+ ```bash
738
+ asgard jobs list # running, exited with a status, or gone (--all: every project's)
739
+ asgard jobs stop servers # by job name, or by task and the tasks it depends on
740
+ asgard jobs log api -f # print (or follow) one job's log
741
+ asgard jobs truncate_log [NAME] --lines M # keep the last M lines of the log (default 1000; no NAME: all; -n: dry run)
742
+ asgard jobs restart api # stop it, then run its owning task again
743
+ asgard jobs clean # forget every job that is no longer running
744
+ ```
745
+
746
+ `stop` sends TERM to the job's whole process group and KILL after a
747
+ timeout. A job's pid is verified against its command line before anything
748
+ trusts it, so a pid reused after a reboot shows as `gone`, never as
749
+ running. See [Background Jobs](https://madbomber.github.io/asgard/jobs/)
750
+ for naming, the trampoline, and file locations.
751
+
682
752
  ## `method_option` types reference
683
753
 
684
754
  | Type | CLI example | Ruby value |
@@ -687,7 +757,7 @@ for every keyword, the environment, and file locations.
687
757
  | `:boolean` | `--force` / `--no-force` | `true` / `false` |
688
758
  | `:numeric` | `--count 3` | `3` |
689
759
  | `:array` | `--tags foo bar baz` | `["foo", "bar", "baz"]` |
690
- | `:hash` | `--vars KEY:val FOO:bar` | `{"KEY"=>"val", "FOO"=>"bar"}` |
760
+ | `:hash` | `--vars KEY:val FOO:bar` | `{"KEY" => "val", "FOO" => "bar"}` |
691
761
 
692
762
  Common `method_option` keys: `aliases`, `type`, `default`, `required`, `desc`, `enum`, `banner`.
693
763
 
@@ -706,7 +776,7 @@ myproject/
706
776
 
707
777
  ### Multiple files
708
778
 
709
- Split tasks across files — each reopens `class Tasks`:
779
+ Split tasks across files; each reopens `class Tasks`:
710
780
 
711
781
  ```
712
782
  myproject/
@@ -749,7 +819,7 @@ class Tasks
749
819
  end
750
820
  ```
751
821
 
752
- In a single-file project, `.loki` can be completely empty — its presence alone marks the project root. In a multi-file project, add at least an `import` call.
822
+ `.loki` is the only file asgard loads on its own, so in a single-file project it holds the tasks. In a multi-file project it needs at least the `import` calls that load the others, and may hold nothing else.
753
823
 
754
824
  ### Explicit loading
755
825
 
@@ -767,14 +837,43 @@ end
767
837
 
768
838
  ---
769
839
 
770
- ## `Asgard` module API
840
+ ## Tips
841
+
842
+ - **Start from working files.** The task files at this repository's root (`.loki`, `test_check.loki`), with the shared ones they load from the [`dev`](https://github.com/MadBomber/dev) repository (`quality.loki`, `gem_tasks.loki`, `git.loki`, `doc_tasks.loki`), are a real multi-file project: quality gates that return `:pass` or `:fail`, a background job, a subcommand group, a `helper` feeding the `header`, and deliberate overrides that `--doctor` reports. Copy what fits.
843
+
844
+ - **More examples.** [MadBomber/dev](https://github.com/MadBomber/dev) holds shared `.loki` libraries used across many repos: gem, git, Rails quality, schedule, status report and iTerm tasks. The [examples directory](examples/) here has one small file per feature.
845
+
846
+ - **One setup for every project.** Put the tasks, shells and helpers you want everywhere in `~/.loki`, then start each project's `.loki` with `import "~/.loki"`. Outside any project the same file is found by the walk up the tree, so those tasks work in any directory.
847
+
848
+ - **Give busy tasks a short name with `map`.** `map "t" => "test"` stays stable when a later task would otherwise make the prefix `t` ambiguous. Thor's prefix matching is handy; an alias is dependable.
849
+
850
+ - **Make bare `asgard` do the common thing.** `default_task :test` (or `:quality`, as this repo does) saves typing on the task you run most.
851
+
852
+ - **Flags go after the task name.** `asgard build --verbose` is the form to use. `--debug` and `--verbose` are also understood in front of a task name, so `asgard --verbose build` runs `build`; in front of any other word they run the `default_task` with that word as its argument. `--version` and `--doctor` go first.
853
+
854
+ - **See the tasks by file with `asgard --doctor`.** It lists every `.loki` file that loaded and, under each, the tasks that file defines with their line numbers, plus which `.loki` won the walk up the tree, what every `import` loaded, tasks hidden because they lack a `desc`, and definitions silently replaced by a later one. It works even when the `.loki` will not load.
855
+
856
+ - **See the commands as a tree with `asgard tree`.** Every command with its description, each subcommand group expanded under its own heading, header and footer included. `help` shows what you can type; `tree` shows how it is organised.
857
+
858
+ - **Keep helpers out of the command list.** A public method without a `desc` is a hidden task: it runs from the command line and as a dependency. Make helpers `private`, wrap them in `no_commands`, or define them with `helper`.
859
+
860
+ - **Pass results, not instance variables.** Parallel dependencies each run on their own copy of the task object, so an `@ivar` set in one never reaches the task that depends on it. Return a value and read it with `dep_result(:name)` or `dep_results`; [`examples/bad.loki`](examples/bad.loki) shows the trap.
861
+
862
+ - **Let gates report, let guards stop.** A quality gate returns `:fail` so every gate runs and the summary shows all failures at once. A guard such as [`examples/confirm.loki`](examples/confirm.loki) raises `Asgard::Error` so nothing after it runs. A dependency's return value never stops its dependent; only an exit, `abort` or `raise` does.
863
+
864
+ - **Name shell configurations, not shells.** The name you give `shell` is yours: `shell :strict, "bash -eu -o pipefail"` names a bash configuration that stops at the first failing line, and `shell :uv, "uv run --script", ext: ".py"` names a way of running Python. `sh` and `shebang` take a name as an optional first argument (`sh :strict, "..."`); without one they run the `default_shell`, so `default_shell :strict` makes every plain `sh` fail fast.
865
+
866
+ - **An AI agent is just another shell.** Register a coding agent's CLI with `shell` and a heredoc becomes the prompt: [`examples/robots/.loki`](examples/robots/.loki) wires up `claude -p` in one line, and its `ask` task sends a prompt with a plain `sh :claude, <<~PROMPT`. Any agent that reads a prompt from stdin fits the same way, so a task can review a diff, draft release notes or explain a failing test alongside the tasks that run them.
867
+
868
+ - **A graph of steps inside one task.** `depends_on` orders whole tasks. When one task needs its own fan-out and fan-in, with output passed from step to step, run a [simple_flow](https://github.com/MadBomber/simple_flow) pipeline in the task body: [`examples/simple_flow/.loki`](examples/simple_flow/.loki) shows one. Run each step's command with `IO.popen` or `system` and halt the pipeline on failure; `sh` inside a step would exit asgard before the pipeline could report.
869
+
870
+ - **Prefer `background: true` to a trailing `&`.** A managed job gets a name, a log and `asgard jobs stop`; a process detached with `&` leaves no record and must be found with `ps`.
871
+
872
+ - **Import conditionally.** `.loki` is plain Ruby: `import "quality_rails.loki" if ENV["RAILS_ROOT"]` keeps Rails-only gates out of non-Rails projects, and a block-form `depends_on` picks up whatever `*_check` tasks are loaded.
771
873
 
772
- | Method | Description |
773
- |---|---|
774
- | `Asgard.run!(argv)` | Entry point — finds `.loki`, loads task files, starts CLI |
775
- | `Asgard.find_task_file` | Returns a `Pathname` to `.loki` searching from CWD upward, or `nil` |
874
+ - **Trace loading when something is missing.** `RUBYOPT=-w asgard help` prints each file as `import` loads it; `ASGARD_TRACE=1` turns a one-line load error into the full backtrace with Ruby's "Did you mean?" hint.
776
875
 
777
- `run!` handles its own errors — a missing `.loki`, a circular dependency, or a `depends_on` that names a task that doesn't exist all produce a clean one-line message and exit 1.
876
+ More tips live in the manual at [Tips](https://madbomber.github.io/asgard/tips/).
778
877
 
779
878
  ---
780
879
 
@@ -782,10 +881,12 @@ end
782
881
 
783
882
  ```bash
784
883
  git clone git@github.com:MadBomber/asgard.git
884
+ git clone git@github.com:MadBomber/dev.git # shared task files, beside asgard
785
885
  cd asgard
786
886
  bundle install
787
- bundle exec rake test # run tests (95% coverage minimum enforced)
788
- bundle exec bin/asgard help # exercise the CLI against this gem's own .loki
887
+ bundle exec bin/asgard test_check # run tests (95% coverage minimum enforced)
888
+ bundle exec bin/asgard quality # every quality gate in parallel
889
+ bundle exec bin/asgard help # exercise the CLI against this gem's own .loki
789
890
  ```
790
891
 
791
892
  ## Contributing
data/bin/asgard CHANGED
@@ -1,5 +1,15 @@
1
1
  #!/usr/bin/env ruby
2
2
  # frozen_string_literal: true
3
3
 
4
+ # --version needs nothing but the constant, so answer it before loading
5
+ # Thor and the rest of the gem. Only before the task name: after it,
6
+ # --version is the task's own argument.
7
+ require_relative "../lib/asgard/leading_flag"
8
+ if Asgard.leading_flag?(ARGV, "--version")
9
+ require_relative "../lib/asgard/version"
10
+ puts Asgard::VERSION
11
+ exit
12
+ end
13
+
4
14
  require_relative "../lib/asgard"
5
15
  Asgard.run!(ARGV)
@@ -120,22 +120,30 @@ module Asgard
120
120
  end
121
121
 
122
122
  def _check_undefined_deps!(all_task_names)
123
- undefined = _deps.values.flatten.uniq - all_task_names
123
+ undefined = _dep_declarers.except(*all_task_names)
124
124
  return unless undefined.any?
125
125
 
126
- raise Asgard::Error, "undefined task(s) in depends_on: #{undefined.sort.join(', ')}"
126
+ details = undefined.sort.map do |dep, tasks|
127
+ "#{dep} (needed by #{tasks.sort.join(', ')})"
128
+ end
129
+ raise Asgard::Error, "undefined task(s) in depends_on: #{details.join(', ')}"
127
130
  end
128
131
 
129
132
  def _check_dep_arities!
130
- _deps.each_value do |stages|
131
- stages.flatten.each do |dep|
132
- meth = instance_method(dep.to_s)
133
- required = meth.parameters.count { |type, _| type == :req }
134
- next unless required.positive?
135
-
136
- raise Asgard::Error,
137
- "task '#{dep}' has #{required} required argument(s) and cannot be used as a dependency"
138
- end
133
+ _dep_declarers.sort.each do |dep, tasks|
134
+ required = instance_method(dep.to_s).parameters.count { |type, _| type == :req }
135
+ next unless required.positive?
136
+
137
+ raise Asgard::Error,
138
+ "task '#{dep}' has #{required} required argument(s) and cannot be used as a dependency " \
139
+ "(needed by #{tasks.sort.join(', ')})"
140
+ end
141
+ end
142
+
143
+ # Each dependency mapped to the tasks whose depends_on names it.
144
+ def _dep_declarers
145
+ _deps.each_with_object({}) do |(task, stages), declarers|
146
+ stages.flatten.uniq.each { |dep| (declarers[dep] ||= []) << task }
139
147
  end
140
148
  end
141
149