asgard 0.6.0 → 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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 0ce55713997e41bcc3531ce3b34765e872184ab435aaa310eecc45625240c840
4
- data.tar.gz: 0913ae51128056486619cf7655479dd28c6298300699ee307e6ec88a0c5e6d6d
3
+ metadata.gz: 85973c05998f33573be66e0a12887f0973cef57f7feff49edb06fb5b46529e60
4
+ data.tar.gz: 6786b757be5156a6fbadd5093e088da594da241811cc924c3dcd1bd685c10e0b
5
5
  SHA512:
6
- metadata.gz: 416c0a47d231bc39c1b14351d48edaa75a00538f3ee5a9f6e0b2aeb78ca63badc72e77f1d6010f4e50e7235d22f436e93ae5b6c7a9719851ca82bfe43a8338bb
7
- data.tar.gz: 7426f8fdd9fc2f56655f2584685b91634890cc8ccb84ef0c0a01ec25d8e7085770f2e0ce5fbedfe6da89ac01c552b938b5dc87fa0efc9ec5242acbac1f963348
6
+ metadata.gz: 35c24c5f4b4a11e6e5f0572f7cfabc62e53e5d14ea68cbf2d23f4182f33a245c8227d40f9cbb56f9e5a53521887cd31a368fba00cd5d6078d0244736bc7df509
7
+ data.tar.gz: ea3622dcc0fe74eb7fdea4153fcb676b683107a25b80612e4d5343efdac8b07d64ed465f8f24ba092904c49aa3d71a3752b5fba7be96b961d81614af93a48ba4
data/CHANGELOG.md CHANGED
@@ -5,6 +5,97 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [Unreleased]
9
+
10
+ ## [0.6.1] - 2026-11-14
11
+
12
+ Two changes can break a script that runs asgard: `--doctor` exits 1 when
13
+ it reports problems, and `--debug` or `--verbose` before a task name now
14
+ runs that task. See
15
+ [Breaking Changes](https://madbomber.github.io/asgard/breaking-changes/#061).
16
+
17
+ ### Added
18
+
19
+ - **A DSL word outside `class Tasks` gets a hint**: `desc` or `depends_on` at the top level of a `.loki` now ends the load-error line with a reminder that they go inside `class Tasks ... end`.
20
+ - **The gem links its docs site and issue tracker**: the gemspec sets
21
+ `documentation_uri` and `bug_tracker_uri`, so the RubyGems page links to
22
+ [the docs site](https://madbomber.github.io/asgard) and the
23
+ [GitHub issues](https://github.com/MadBomber/asgard/issues).
24
+ - **The docs site serves `llms.txt`**:
25
+ [/llms.txt](https://madbomber.github.io/asgard/llms.txt) lists every docs
26
+ page with a one-line description, in the [llms.txt](https://llmstxt.org)
27
+ format.
28
+ - **`truncate_log` shortens logs in place**: `asgard schedule truncate_log
29
+ [NAME]`, `asgard watcher truncate_log` and `asgard jobs truncate_log [NAME]`
30
+ keep the last `--lines M` lines (default 1000; `0` empties the log), rewriting
31
+ the file in place so a running writer keeps appending to it. A truncate
32
+ cut short by Ctrl-C, a signal or a failed write still leaves a whole log.
33
+ `--dry-run` (`-n`) reports what would be removed without changing anything.
34
+ - **Two new guides in the docs**: [A dependency with
35
+ arguments](https://madbomber.github.io/asgard/dependencies/#a-dependency-with-arguments)
36
+ shows how to give a dependency the arguments it needs, and
37
+ [`examples/simple_flow`](https://madbomber.github.io/asgard/examples/#simple_flow)
38
+ runs a fan-out and fan-in of steps inside one task with
39
+ [simple_flow](https://github.com/MadBomber/simple_flow).
40
+
41
+ ### Changed
42
+
43
+ - **BREAKING: `asgard --doctor` exits 1 when it reports problems**,
44
+ including overridden task definitions, so scripts and CI can use it as a
45
+ check. Warnings alone still exit 0. A script that ran `--doctor` and
46
+ ignored what it reported now fails on those problems
47
+ ([#13](https://github.com/MadBomber/asgard/issues/13)).
48
+ - **BREAKING: `--debug` and `--verbose` before a task name run that task**:
49
+ `asgard --verbose build` is now `asgard build --verbose`. It used to print
50
+ the help for `build`, or, in a project with a `default_task`, run the
51
+ default task with `build` as its argument. In front of a word that is not a
52
+ task the flags still run the default task with that word
53
+ ([#27](https://github.com/MadBomber/asgard/issues/27)).
54
+ - **The repository's own task files load from a shared checkout**: the root
55
+ `.loki` runs `import_up "dev/.loki"` to load the quality, gem, git and docs
56
+ tasks of [MadBomber/dev](https://github.com/MadBomber/dev), and the local
57
+ `test_check.loki` replaces two of them with asgard's own test runner.
58
+ `xyzzy.loki` is gone; those replacements are now the worked example of an
59
+ override in the docs. `quality_rails.loki` is gone too; conditional imports
60
+ stay in the docs as an example. Without `dev` cloned beside asgard, the
61
+ root `.loki` aborts with a message naming the repository to clone. The gem
62
+ itself is unchanged.
63
+ - **One parent-directory walk**: `loki_up`, `import_up` and `--doctor`'s
64
+ marker search use `Pathname#ascend` instead of three hand-rolled loops; what
65
+ they find is unchanged ([#19](https://github.com/MadBomber/asgard/issues/19)).
66
+ - **Schedule and watcher take the project root from `Asgard.project_root`**,
67
+ as jobs already did, so all three act on the same project
68
+ ([#26](https://github.com/MadBomber/asgard/issues/26)).
69
+ - **CI runs on Node 24 actions**: the workflows use `actions/checkout@v7`
70
+ and `actions/setup-python@v7`, replacing the deprecated Node 20 majors
71
+ ([#29](https://github.com/MadBomber/asgard/issues/29)).
72
+ - **Schedule log directories are private**: `asgard schedule install`
73
+ creates the log directory 0700 (and tightens an existing one), as the
74
+ watch and jobs state directories already are.
75
+
76
+ ### Fixed
77
+
78
+ - **A task called with arguments it cannot take runs nothing**: the usage
79
+ error is reported before the task's dependencies run, not after them
80
+ ([#27](https://github.com/MadBomber/asgard/issues/27)).
81
+ - **A `helper` with a reserved name is reported at its `.loki` line**, not at
82
+ asgard's own `task_dsl.rb`, and is refused before anything is defined
83
+ ([#25](https://github.com/MadBomber/asgard/issues/25)).
84
+ - **`bin/console` and the `console` task load on Ruby 4**: the Gemfile lists
85
+ `irb`, which is no longer a default gem ([#28](https://github.com/MadBomber/asgard/issues/28)).
86
+ - **`truncate_log NAME` on an entry with no log yet is not an error**: a declared schedule or recorded job that has not written its log says `NAME has no log yet (PATH); nothing to truncate` and exits 0 ([#18](https://github.com/MadBomber/asgard/issues/18)).
87
+ - **A background job started right after it ended starts again**, instead
88
+ of being reported as already running while its old shell exits.
89
+ - **`asgard --doctor` reports a `.loki` that calls `exit` or `abort`** as a
90
+ load failure instead of exiting with no report.
91
+ - **Dependency errors name the task(s) that declared them**: an undefined
92
+ dependency ([#14](https://github.com/MadBomber/asgard/issues/14)) and a
93
+ dependency that takes required arguments both end with
94
+ `(needed by ci, release)`.
95
+ - **The test suite passes with no locale set**: output read back from a
96
+ child `asgard` is tagged UTF-8, so a shell without `LANG` or `LC_ALL` no
97
+ longer fails the tests that compare it.
98
+
8
99
  ## [0.6.0] - 2026-10-31
9
100
 
10
101
  Upgrading from 0.5.x? Read
@@ -462,6 +553,8 @@ reinstalled after.
462
553
  - 100% test coverage enforced via SimpleCov (95% minimum threshold)
463
554
  - Quality task in `.loki` runs flog after tests
464
555
 
556
+ [Unreleased]: https://github.com/MadBomber/asgard/compare/v0.6.1...HEAD
557
+ [0.6.1]: https://github.com/MadBomber/asgard/compare/v0.6.0...v0.6.1
465
558
  [0.6.0]: https://github.com/MadBomber/asgard/compare/v0.5.1...v0.6.0
466
559
  [0.5.1]: https://github.com/MadBomber/asgard/compare/v0.4.1...v0.5.1
467
560
  [0.4.1]: https://github.com/MadBomber/asgard/compare/v0.4.0...v0.4.1
data/README.md CHANGED
@@ -659,6 +659,7 @@ asgard schedule stop NAME # stop one entry (persists across reboots and ins
659
659
  asgard schedule start NAME # start a stopped entry, or install just this one
660
660
  asgard schedule trigger NAME # run an installed entry now
661
661
  asgard schedule log NAME [-f] # print (or follow) the entry's log
662
+ asgard schedule truncate_log [NAME] --lines M # keep the last M lines of the log (default 1000; no NAME: all; -n: dry run)
662
663
  asgard schedule remove [NAME] # remove one entry, or all of this project's
663
664
  asgard schedule prune [-n] # remove every project's entries whose directory is gone (-n: list only)
664
665
  ```
@@ -699,6 +700,7 @@ asgard watcher stop --force # stop it and end any running task
699
700
  asgard watcher list # watches, daemon state, each entry's last run (--all: every project's)
700
701
  asgard watcher preview # the command and environment each watch would run
701
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
702
704
  ```
703
705
 
704
706
  Each trigger runs `asgard <task>` from the project root with a fixed
@@ -736,6 +738,7 @@ end
736
738
  asgard jobs list # running, exited with a status, or gone (--all: every project's)
737
739
  asgard jobs stop servers # by job name, or by task and the tasks it depends on
738
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)
739
742
  asgard jobs restart api # stop it, then run its owning task again
740
743
  asgard jobs clean # forget every job that is no longer running
741
744
  ```
@@ -836,7 +839,7 @@ end
836
839
 
837
840
  ## Tips
838
841
 
839
- - **Start from working files.** The task files at this repository's root (`.loki`, `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 a deliberate override for `--doctor`. Copy what fits.
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.
840
843
 
841
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.
842
845
 
@@ -846,7 +849,7 @@ end
846
849
 
847
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.
848
851
 
849
- - **Flags go after the task name.** `asgard build --verbose` runs the task; `asgard --verbose build` prints the help for `build`. Only `--version` and `--doctor` go first.
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.
850
853
 
851
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.
852
855
 
@@ -862,6 +865,8 @@ end
862
865
 
863
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.
864
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
+
865
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`.
866
871
 
867
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.
@@ -876,6 +881,7 @@ More tips live in the manual at [Tips](https://madbomber.github.io/asgard/tips/)
876
881
 
877
882
  ```bash
878
883
  git clone git@github.com:MadBomber/asgard.git
884
+ git clone git@github.com:MadBomber/dev.git # shared task files, beside asgard
879
885
  cd asgard
880
886
  bundle install
881
887
  bundle exec bin/asgard test_check # run tests (95% coverage minimum enforced)
@@ -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
 
@@ -74,6 +74,13 @@ module Asgard
74
74
  Thor::Options.new(bare, {}, false, true).parse(raw).to_h
75
75
  end
76
76
 
77
+ # Whether a method with these +parameters+ (Method#parameters) can be
78
+ # called with +count+ positional arguments.
79
+ def self.accepts?(parameters, count)
80
+ kinds = parameters.map(&:first)
81
+ count >= kinds.count(:req) && (kinds.include?(:rest) || count <= kinds.count { %i[req opt].include?(it) })
82
+ end
83
+
77
84
  # A copy of +option+ that parses the same words but has no default.
78
85
  def self.without_default(option)
79
86
  Thor::Option.new(option.name, type: option.type, aliases: option.aliases, enum: option.enum,
@@ -125,7 +132,7 @@ module Asgard
125
132
 
126
133
  # Dispatch hook: resolves and runs all deps (in parallel where declared)
127
134
  # before executing the target command.
128
- def invoke_command(command, *)
135
+ def invoke_command(command, args = [])
129
136
  $DEBUG = true if options[:debug]
130
137
  $VERBOSE = true if options[:verbose]
131
138
  target = command.name.to_sym
@@ -139,8 +146,8 @@ module Asgard
139
146
  error = nil
140
147
  begin
141
148
  result = _in_task_frame(target) do
142
- resolved_deps = _run_deps_for(target)
143
- _with_dep_results(resolved_deps) { command.run(self, *) }
149
+ resolved_deps = _callable_with?(target, args) ? _run_deps_for(target) : {}
150
+ _with_dep_results(resolved_deps) { command.run(self, args) }
144
151
  end
145
152
  rescue Exception => e # rubocop:disable Lint/RescueException -- an exit or interrupt ends the task too
146
153
  # Captured here, not read from $! in an ensure: $! still holds a
@@ -231,6 +238,13 @@ module Asgard
231
238
  end
232
239
  end
233
240
 
241
+ # False when +args+ cannot be the task's arguments. Its dependencies
242
+ # are then skipped, so the usage error Thor prints for the call is
243
+ # all that happens.
244
+ def _callable_with?(target, args)
245
+ !respond_to?(target, true) || Dispatch.accepts?(method(target).parameters, args.size)
246
+ end
247
+
234
248
  def _run_deps_for(target)
235
249
  stages = self.class._deps[target]
236
250
  return {} unless stages&.any?
@@ -38,7 +38,13 @@ module Asgard
38
38
  Dotenv.load(path) if File.exist?(path)
39
39
  end
40
40
 
41
+ # A reserved name is refused before anything is defined, at the .loki
42
+ # line that called helper rather than at the define_method below.
41
43
  def helper(name, &)
44
+ if _reserved_name?(name.to_sym)
45
+ here = caller_locations(1, 1).first
46
+ _raise_reserved_name!(name, here.path, here.lineno)
47
+ end
42
48
  define_singleton_method(name, &)
43
49
  no_commands { private define_method(name) { |*args, **kwargs, &blk| self.class.send(name, *args, **kwargs, &blk) } }
44
50
  end
data/lib/asgard/base.rb CHANGED
@@ -118,13 +118,20 @@ module Asgard
118
118
  end
119
119
 
120
120
  def _check_reserved_name!(method_name)
121
- thor = RESERVED_NAMES.include?(method_name)
122
- return unless thor || ASGARD_HELPERS.include?(method_name)
121
+ return unless _reserved_name?(method_name)
123
122
 
124
123
  file, line = instance_method(method_name).source_location
125
124
  remove_method(method_name) # leave the original in place, so the class still dispatches
126
- what = thor ? "a name Thor reserves" : "an asgard helper"
127
- raise Asgard::Error, "'#{method_name}' at #{file}:#{line} is #{what} and cannot be a task or helper; rename it"
125
+ _raise_reserved_name!(method_name, file, line)
126
+ end
127
+
128
+ # Whether +name+ is one a task or helper cannot take.
129
+ def _reserved_name?(name) = RESERVED_NAMES.include?(name) || ASGARD_HELPERS.include?(name)
130
+
131
+ # Raises the reserved-name error for +name+, defined at +file+:+line+.
132
+ def _raise_reserved_name!(name, file, line)
133
+ what = RESERVED_NAMES.include?(name) ? "a name Thor reserves" : "an asgard helper"
134
+ raise Asgard::Error, "'#{name}' at #{file}:#{line} is #{what} and cannot be a task or helper; rename it"
128
135
  end
129
136
 
130
137
  # `private def helper = ...` makes the method private only after
@@ -55,9 +55,13 @@ module Asgard
55
55
  end
56
56
  end
57
57
 
58
+ def problem_count
59
+ @findings.count { |finding| finding.level == :error } + override_count
60
+ end
61
+
58
62
  def summary_line
59
63
  by_level = @findings.group_by(&:level)
60
- errors = (by_level[:error]&.size || 0) + override_count
64
+ errors = problem_count
61
65
  warns = by_level[:warn]&.size || 0
62
66
  return colorize(32, "No problems found.") if errors.zero? && warns.zero?
63
67
  return colorize(33, "No problems found (#{warns} warning(s)).") if errors.zero?
data/lib/asgard/doctor.rb CHANGED
@@ -29,23 +29,14 @@ module Asgard
29
29
  build_task_sections
30
30
  report_dependencies
31
31
  print_report
32
+ problem_count.zero? ? 0 : 1
32
33
  end
33
34
 
34
35
  # Every ".loki" marker from +dir+ up to the filesystem root, nearest
35
- # first — mirrors loki_up's walk, but collects every match instead of
36
+ # first — the same walk as loki_up, but collects every match instead of
36
37
  # stopping at the first (so shadowed ancestor markers can be reported).
37
38
  def self.ancestor_markers(dir)
38
- markers = []
39
- current = Pathname.new(dir)
40
- loop do
41
- candidate = current + ".loki"
42
- markers << candidate.to_s if candidate.file?
43
- parent = current.parent
44
- break if parent == current
45
-
46
- current = parent
47
- end
48
- markers
39
+ Pathname.new(dir).ascend.map { it + ".loki" }.select(&:file?).map(&:to_s)
49
40
  end
50
41
 
51
42
  # method_name => [[file, line], ...] entries defined more than once —
@@ -57,6 +48,23 @@ module Asgard
57
48
  end
58
49
  end
59
50
 
51
+ # The "load failed" line for whatever stopped the .loki chain loading.
52
+ # An exit or abort raises SystemExit; a bare exit (or raise SystemExit)
53
+ # carries only a default message, so only the status is worth showing then.
54
+ def self.load_failure(error)
55
+ return "load failed: #{error.class}: #{error.message}" unless error.is_a?(SystemExit)
56
+
57
+ detail = ": #{error.message}" unless ["exit", error.class.to_s].include?(error.message)
58
+ "load failed: #{error.class} (status #{error.status})#{detail}"
59
+ end
60
+
61
+ # What ImportTracer saw one import or import_up do: the line the report
62
+ # prints for it, and the .loki files it loaded.
63
+ def record_import(message, added = [])
64
+ @imports << message
65
+ @loaded_files.concat(added)
66
+ end
67
+
60
68
  private
61
69
 
62
70
  def report_markers
@@ -77,16 +85,16 @@ module Asgard
77
85
  return unless @marker
78
86
 
79
87
  Kernel.prepend(ImportTracer)
80
- ImportTracer.doctor = self
88
+ ImportTracer.observe(self)
81
89
  @loaded_files << @marker
82
90
 
83
91
  before = Asgard::Base._asgard_subclasses.dup
84
92
  Asgard.load_root(@marker)
85
93
  @new_subclasses = (Asgard::Base._asgard_subclasses - before + [Tasks]).uniq
86
- rescue StandardError, ScriptError => e
87
- @findings << Finding.new(level: :error, message: "load failed: #{e.class}: #{e.message}")
94
+ rescue StandardError, ScriptError, SystemExit => e
95
+ @findings << Finding.new(level: :error, message: self.class.load_failure(e))
88
96
  ensure
89
- ImportTracer.doctor = nil
97
+ ImportTracer.observe(nil)
90
98
  end
91
99
 
92
100
  def report_imports
@@ -103,18 +111,16 @@ module Asgard
103
111
  end
104
112
  end
105
113
 
106
- def record_import(message, added = [])
107
- @imports << message
108
- @loaded_files.concat(added)
109
- end
110
-
111
114
  # Prepended onto Kernel for the process lifetime of `asgard --doctor`
112
115
  # (Asgard.run! exits right after Doctor#run, so it's never unprepended)
113
116
  # to observe every import/import_up call, whether typed at the top
114
117
  # level of a .loki file or reached indirectly through another import.
115
118
  module ImportTracer
116
119
  class << self
117
- attr_accessor :doctor
120
+ # The Doctor that records each import, or nil when none is running.
121
+ attr_reader :doctor
122
+
123
+ def observe(doctor) = @doctor = doctor
118
124
  end
119
125
 
120
126
  def import(path)
@@ -122,7 +128,7 @@ module Asgard
122
128
  before = $LOADED_FEATURES.dup
123
129
  result = super(path, from: loc)
124
130
  added = ImportTracer.loki_files($LOADED_FEATURES - before)
125
- ImportTracer.doctor&.send(:record_import, ImportTracer.trace_message("import", path, added), added) unless
131
+ ImportTracer.doctor&.record_import(ImportTracer.trace_message("import", path, added), added) unless
126
132
  loc&.absolute_path&.end_with?("kernel_methods.rb")
127
133
  result
128
134
  end
@@ -131,7 +137,7 @@ module Asgard
131
137
  before = $LOADED_FEATURES.dup
132
138
  result = super
133
139
  added = ImportTracer.loki_files($LOADED_FEATURES - before)
134
- ImportTracer.doctor&.send(:record_import, ImportTracer.trace_message("import_up", name, added), added)
140
+ ImportTracer.doctor&.record_import(ImportTracer.trace_message("import_up", name, added), added)
135
141
  result
136
142
  end
137
143
 
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require "time"
4
+ require_relative "../log"
4
5
 
5
6
  # warn is silent when $VERBOSE is nil and bypasses $stderr in Ruby 4.0 (see
6
7
  # base/task_dsl.rb); these messages are for the user, so they always print.
@@ -24,11 +25,14 @@ module Asgard
24
25
  # One `list` row per record, with what the job is doing now.
25
26
  def rows(state) = state.records.map { |record| row(record, state) }
26
27
 
28
+ # verified? goes first: a job that ends between the reads shows
29
+ # its exit, never "gone", and a code read means its time is there.
27
30
  def row(record, state)
28
- name = record[:name]
29
- exited = state.exit_time(name)
30
- status = Jobs.status(exit_code: state.exit_code(name), verified: state.verified?(record),
31
- leftovers: State.leftovers?(record, exited_at: exited))
31
+ name = record[:name]
32
+ verified = state.verified?(record)
33
+ code = state.exit_code(name)
34
+ exited = state.exit_time(name)
35
+ status = Jobs.status(exit_code: code, verified:, leftovers: State.leftovers?(record, exited_at: exited))
32
36
  seconds = (exited - Time.iso8601(record[:started])).round(1) if status.is_a?(Array)
33
37
  { name:, task: record[:task], pid: record[:pid], state: Jobs.describe_status(status, seconds:),
34
38
  started: Time.iso8601(record[:started]).strftime("%Y-%m-%d %H:%M:%S"), command: record[:command] }
@@ -66,6 +70,17 @@ module Asgard
66
70
 
67
71
  def record_for!(name) = state.read_record(name) || abort("jobs: no such job: #{name} (see `asgard jobs list`)")
68
72
 
73
+ # Whether +path+ is NAME's log to truncate. A job on record that has
74
+ # not written a log yet says so and is skipped; any other name aborts.
75
+ def log_to_truncate?(name, path)
76
+ found = File.file?(path)
77
+ abort "jobs: no such job log: #{name}" if name.include?("/") || !(found || state.read_record(name))
78
+ return true if found
79
+
80
+ $stderr.puts "#{name} has no log yet (#{path}); nothing to truncate"
81
+ false
82
+ end
83
+
69
84
  def stopper = Stopper.new(timeout: options[:timeout] || Stopper::TIMEOUT)
70
85
 
71
86
  # The records `stop` ends, newest start first, and the names that
@@ -73,13 +88,16 @@ module Asgard
73
88
  # depends on, which needs this project's .loki loaded.
74
89
  def stop_targets(names)
75
90
  records, unknown =
76
- if every_project? then [all_states.values.flat_map(&:records), []]
77
- elsif names.empty? then [state.records, []]
91
+ if names.empty? || options[:all] then [listed_states.values.flat_map(&:records), []]
78
92
  else Jobs.resolve(names, state.records, closure: ->(task) { Jobs.closure(task, Tasks._deps) })
79
93
  end
80
94
  [records.sort_by { |record| [record[:started].to_s, record[:name].to_s] }.reverse, unknown]
81
95
  end
82
96
 
97
+ # The states `list` and a bare `stop` cover, by title: every
98
+ # project's, or this one's under no title.
99
+ def listed_states = every_project? ? all_states : { nil => state }
100
+
83
101
  def no_jobs_message
84
102
  return "No jobs have been started on this machine." if every_project?
85
103
 
@@ -91,7 +109,7 @@ module Asgard
91
109
  desc "list", "Show this project's jobs: running, exited with a status, or gone (--all: every project's)"
92
110
  method_option :all, aliases: "-a", type: :boolean, desc: "List every project's jobs, not just this one's"
93
111
  def list
94
- states = every_project? ? all_states : { nil => state }
112
+ states = listed_states
95
113
  Commands.skipped_lines(states.values).each { |line| $stderr.puts line }
96
114
  groups = states.transform_values { |each_state| Commands.rows(each_state) }.reject { |_, rows| rows.empty? }
97
115
  return puts(no_jobs_message) if groups.empty?
@@ -124,6 +142,19 @@ module Asgard
124
142
  IO.copy_stream(path, $stdout)
125
143
  end
126
144
 
145
+ desc "truncate_log [NAME]", "Keep the last M lines of a job log; no NAME truncates every job log of this project"
146
+ method_option :lines, type: :string, default: "1000", banner: "M", desc: "Lines to keep per log; 0 empties it"
147
+ method_option :dry_run, aliases: "-n", type: :boolean, desc: "Report what would be removed without changing logs"
148
+ def truncate_log(name = nil)
149
+ Log.line_count(options[:lines]) # reject a bad --lines even when there is no log to truncate
150
+ paths = name ? [state.log_path(name)] : Dir.glob(File.join(Asgard.glob_escape(state.dir), "*.log"))
151
+ return if name && !log_to_truncate?(name, paths.first)
152
+
153
+ Log.truncate_logs(paths, lines: options[:lines], dry_run: options[:dry_run])
154
+ rescue ArgumentError, SystemCallError, IOError => e
155
+ abort "jobs: #{e.message}"
156
+ end
157
+
127
158
  desc "restart NAME", "Stop the job, then run its owning task again"
128
159
  method_option :timeout, aliases: "-t", type: :numeric, desc: "Seconds to wait after TERM before KILL (default #{Stopper::TIMEOUT})"
129
160
  def restart(name)
@@ -29,24 +29,29 @@ module Asgard
29
29
  # is alive and runs the trampoline whose command line carries the
30
30
  # script path. A reused pid after a reboot fails this, and so does
31
31
  # one that is now asgard itself, and so does a record that is not
32
- # a job's (Jobs.valid_record?). A ps that cannot tell raises
32
+ # a job's (Jobs.valid_record?). Once the trampoline has written the
33
+ # status (not just opened the file) its pid no longer counts, though
34
+ # its shell may not have exited yet; ps asks first, so a status
35
+ # written in between is still seen. A ps that cannot tell raises
33
36
  # Pid::Unusable rather than calling every job gone.
34
37
  def verified?(record)
35
38
  return false unless Jobs.valid_record?(record)
36
39
 
37
40
  Pid.require_ps!
38
- Pid.matches?(record[:pid], record[:script], self_ok: false) || survives?(record)
41
+ trampoline = Pid.matches?(record[:pid], record[:script], self_ok: false) && !File.size?(status_file(record))
42
+ trampoline || survives?(record)
39
43
  end
40
44
 
41
- # Whether the job outlived its trampoline: some process in its group
42
- # still runs the script. A group id is never reused while the group
43
- # has members, so a match is still the job we started.
44
- def survives?(record, ps: Pid.method(:group_command_lines))
45
+ # Whether the script still runs apart from the trampoline: some
46
+ # other process in its group carries the script path (the script's
47
+ # shell, or a subshell it backgrounded). A group id is never reused
48
+ # while the group has members, so a match is still the job we started.
49
+ def survives?(record, ps: Pid.method(:group_processes))
45
50
  pgid = record[:pgid]
46
51
  script = record[:script].to_s
47
52
  return false unless job_group?(pgid) && !script.empty?
48
53
 
49
- ps.call(pgid).any? { |command| command.include?(script) }
54
+ ps.call(pgid).any? { |member| member.pid != record[:pid] && member.command.include?(script) }
50
55
  end
51
56
 
52
57
  # Whether +pgid+ could be a job's group at all: a group id above 1
@@ -22,16 +22,10 @@ module Kernel
22
22
  def changes = Asgard::Changes.current
23
23
  module_function :changes
24
24
 
25
+ # The nearest +name+ in the current directory or an ancestor, as a
26
+ # Pathname, or nil. A directory by that name is not it.
25
27
  def loki_up(name = ".loki")
26
- dir = Pathname.new(Dir.pwd)
27
- loop do
28
- candidate = dir + name
29
- return candidate if candidate.file? # a directory by that name is not it
30
- parent = dir.parent
31
- break if parent == dir
32
- dir = parent
33
- end
34
- nil
28
+ Pathname.new(Dir.pwd).ascend.map { it + name }.find(&:file?)
35
29
  end
36
30
  module_function :loki_up
37
31
 
@@ -68,16 +62,12 @@ module Kernel
68
62
  # in is part of a path, not a pattern.
69
63
  def import_up(name = ".loki")
70
64
  if Asgard.glob?(name)
71
- dir = Dir.pwd
72
- loop do
65
+ Pathname.new(Dir.pwd).ascend do |dir|
73
66
  matches = Dir.glob(name, base: dir)
74
- unless matches.empty?
75
- warn "import_up: #{name} → #{dir}" if verbose? || debug?
76
- return matches.map { |p| import(Asgard.glob_escape(File.join(dir, p))) }.any?
77
- end
78
- parent = File.dirname(dir)
79
- break if parent == dir
80
- dir = parent
67
+ next if matches.empty?
68
+
69
+ warn "import_up: #{name} → #{dir}" if verbose? || debug?
70
+ return matches.map { |p| import(Asgard.glob_escape(File.join(dir, p))) }.any?
81
71
  end
82
72
  warn "import_up: #{name} not found" if debug?
83
73
  return false
@@ -7,4 +7,20 @@ module Asgard
7
7
  # before the first word that is not one (the task name). After it, the
8
8
  # word belongs to the task, which may take --version as an argument.
9
9
  def self.leading_flag?(argv, flag) = argv.take_while { |word| word.start_with?("-") }.include?(flag)
10
+
11
+ # The options that set a global for whatever task runs, so they read the
12
+ # same on either side of the task name.
13
+ GLOBAL_FLAGS = %w[--debug --verbose].freeze
14
+
15
+ # +argv+ with the task name first: leading GLOBAL_FLAGS move behind the
16
+ # word they precede when the block says that word names a task. Thor
17
+ # hands a command line that starts with an option to the default task,
18
+ # so without this `asgard --verbose build` never reaches `build`.
19
+ def self.task_first(argv)
20
+ flags = argv.take_while { |word| GLOBAL_FLAGS.include?(word) }
21
+ word = argv[flags.size]
22
+ return argv if flags.empty? || word.nil? || !yield(word)
23
+
24
+ [word, *flags, *argv.drop(flags.size + 1)]
25
+ end
10
26
  end