rascal 0.4.0 → 0.5.0

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 (44) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/test.yml +4 -4
  3. data/.ruby-version +1 -1
  4. data/AGENTS.md +4 -0
  5. data/CHANGELOG.md +74 -0
  6. data/CONTRIBUTING.md +139 -0
  7. data/Gemfile.common +0 -3
  8. data/Gemfile.lock +1 -47
  9. data/Guardfile +0 -9
  10. data/README.md +679 -76
  11. data/Rakefile +1 -7
  12. data/lib/rascal/cli/base.rb +41 -20
  13. data/lib/rascal/cli/clean.rb +3 -8
  14. data/lib/rascal/cli/environments.rb +1 -3
  15. data/lib/rascal/cli/main.rb +106 -17
  16. data/lib/rascal/cli/run.rb +6 -7
  17. data/lib/rascal/cli/shell.rb +3 -3
  18. data/lib/rascal/cli/status.rb +81 -0
  19. data/lib/rascal/cli/update.rb +8 -8
  20. data/lib/rascal/cli.rb +1 -0
  21. data/lib/rascal/command_script.rb +83 -0
  22. data/lib/rascal/docker/command_containers.rb +101 -0
  23. data/lib/rascal/docker/container.rb +82 -101
  24. data/lib/rascal/docker/image.rb +71 -0
  25. data/lib/rascal/docker/interface.rb +4 -2
  26. data/lib/rascal/docker/network.rb +12 -0
  27. data/lib/rascal/docker/volume.rb +17 -10
  28. data/lib/rascal/docker.rb +11 -4
  29. data/lib/rascal/environment.rb +164 -40
  30. data/lib/rascal/gitlab/config_file.rb +199 -0
  31. data/lib/rascal/gitlab/environment_builder.rb +204 -0
  32. data/lib/rascal/gitlab/jobs.rb +299 -0
  33. data/lib/rascal/gitlab/variables.rb +155 -0
  34. data/lib/rascal/gitlab.rb +16 -0
  35. data/lib/rascal/io_helper.rb +11 -0
  36. data/lib/rascal/service.rb +52 -9
  37. data/lib/rascal/version.rb +1 -1
  38. data/lib/rascal.rb +2 -1
  39. data/rascal.gemspec +3 -2
  40. metadata +15 -8
  41. data/bin/cucumber +0 -29
  42. data/cucumber.yml +0 -1
  43. data/lib/rascal/environments_definition/gitlab.rb +0 -146
  44. data/lib/rascal/environments_definition.rb +0 -23
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d916ce222f77cd89927ad3ac8ceb56da9d34d87f2f808938b6c796ce92ab3d8b
4
- data.tar.gz: 070e9c46b5f33074260638ba1b2e5bb19844c515461788ae904d4b1e72690a7e
3
+ metadata.gz: b86e32f15a29579cd4db96a2b811995aedea25da03dccedcef016c004ad02a27
4
+ data.tar.gz: 9c427e0a5729653c4addd075371cc2d0198180ff89c264bede269705ebc06612
5
5
  SHA512:
6
- metadata.gz: 7cd38cd621c764d5d8548e4093abc1be639713efc2294b7e80b7fec5d7cdb37648569258c6b8725b604ddcbc756b5916d26b2e6577f8e33a03b100d522b5d957
7
- data.tar.gz: '00299e9e4c118a754e0b5227c04d2400d7424a551cddaebc24a1fb85c5649e6c7913835e26754f73d663a4ab50b345ed322198f6f4552c3e3f21d318196cf511'
6
+ metadata.gz: 18e64ccdc952397b8036e90ca053fc118d3416cb94622ab60440edfda1374d5a756d2e700fa8129b6c68058b4df906d810382c60b456f09f91b19a874e1c5214
7
+ data.tar.gz: f90cd9a5c12b4da475c2cef16d6f8f4b6c471fd1b268ba83d0d474b2698f11c5ecfc38893612e1f8145a6bd5b1d25580641b9ed941ce00683f58d61e430325af
@@ -13,16 +13,16 @@ jobs:
13
13
  fail-fast: false
14
14
  matrix:
15
15
  include:
16
- - ruby: 3.2.0
16
+ - ruby: '3.3'
17
17
  gemfile: Gemfile
18
- - ruby: 3.4.1
18
+ - ruby: '3.4'
19
19
  gemfile: Gemfile
20
- - ruby: 4.0.6
20
+ - ruby: '4.0'
21
21
  gemfile: Gemfile
22
22
  env:
23
23
  BUNDLE_GEMFILE: "${{ matrix.gemfile }}"
24
24
  steps:
25
- - uses: actions/checkout@v2
25
+ - uses: actions/checkout@v4
26
26
  - name: Install ruby
27
27
  uses: ruby/setup-ruby@v1
28
28
  with:
data/.ruby-version CHANGED
@@ -1 +1 @@
1
- 3.4.8
1
+ 4.0.9
data/AGENTS.md ADDED
@@ -0,0 +1,4 @@
1
+ # Instructions for agents
2
+
3
+ Read [CONTRIBUTING.md](CONTRIBUTING.md) before you change rascal. It explains how rascal is built,
4
+ where changes go, how to test them, and the conventions to follow.
data/CHANGELOG.md CHANGED
@@ -4,6 +4,80 @@ All notable changes to this project will be documented here.
4
4
 
5
5
  Rascal follows semantic versioning. This has little consequence pre 1.0, so expect breaking changes.
6
6
 
7
+ ## 0.5.0 (2026-11-20)
8
+
9
+ ### Breaking changes
10
+
11
+ - Require Ruby 3.3 or newer for rascal itself. Projects can still use any Ruby in their images.
12
+ - Predefine the variables `CI`, `GITLAB_CI`, `CI_JOB_NAME`, `CI_PROJECT_NAME`, `CI_PROJECT_DIR` and
13
+ `CI_BUILDS_DIR`, like GitLab does. **This may change how your app and tools behave in a rascal
14
+ environment**, if they check for `CI` or `GITLAB_CI`. Override or remove them in the `.rascal` block if needed.
15
+ - Let a job override `default:`, like GitLab does. Rascal used to do it the other way around.
16
+ - rascal's own messages, like `Starting container for ...` and image downloads, go to stderr, so a
17
+ command's stdout only has the command's output.
18
+ - After starting services, wait until each accepts connections on one of its exposed ports, or
19
+ on `HEALTHCHECK_TCP_PORT` from its variables, before running the command. Set the timeout
20
+ (30 seconds by default) with `services_timeout` in the `.rascal` block.
21
+ - `rascal clean` also removes the anonymous volumes of service containers, like the data volumes of
22
+ postgres and redis, which used to pile up.
23
+ - `before_shell`, the command and `after_shell` run on separate lines of a script instead of being
24
+ joined with `;`, so entries may end in `&` or a comment.
25
+
26
+ ### GitLab compatibility
27
+
28
+ - Read `.gitlab-ci.yml` files with global `variables:` or `workflow:`, which rascal used to mistake
29
+ for jobs, like `include:` and `stages:`. The deprecated top-level `image`,
30
+ `services`, `cache`, `before_script` and `after_script` now act like the same keys in `default:`.
31
+ - Support `extends:`, `inherit:`, `!reference`, local files from `include:`, and files with a `spec:` header.
32
+ - Support services given as a plain image name, services with several aliases (`alias: db,postgres`),
33
+ and services without an alias, which get the host names GitLab derives from their image.
34
+ - Expand variables in variables, image names and service names, like GitLab does
35
+ (`$NAME`, `${NAME}`, `%NAME%`, `$$`). Global `variables:` apply to every job.
36
+ - Support `entrypoint` for a job's image. rascal's settings can override only the entrypoint, like
37
+ `jobs: rspec: image: { entrypoint: [''] }`, keeping the job's image.
38
+ - Job names like `2.6`, which YAML reads as numbers, work in `.rascal: jobs:`.
39
+
40
+ ### Working with environments
41
+
42
+ - Add `rascal status`, which shows what rascal made of a job's config, and what of the environment
43
+ exists in Docker, like whether a service runs or how it exited, or what the image's entrypoint is.
44
+ `--json` prints it for scripts.
45
+ - Add the options `--env NAME=VALUE`, `--unset-env NAME` and `--ssh-agent` to `rascal run` and
46
+ `rascal shell`, which change the container for a single command, like for updating dependencies.
47
+ Options may also come after the environment's name.
48
+ - In the `.rascal` block, a variable can extend the job's value, like `RUBYOPT: $RUBYOPT -W:deprecated`,
49
+ or remove a variable, like `CI: null`.
50
+ - Read settings for rascal from a `.rascal.yml` next to `.gitlab-ci.yml`, which extends the `.rascal`
51
+ block. Use it for settings that should not be part of the project's CI config.
52
+ - With `ssh_agent: true` in the `.rascal` block, make the host's SSH agent and known hosts available
53
+ in the container, so it can fetch private dependencies over SSH. It is off by default, since any
54
+ code in the container can use the agent's keys while a command runs.
55
+ - Give files that commands create in the project back to the host user. They used to belong to root.
56
+ - Let Git in the container work with the project, which it used to refuse as belonging to another user.
57
+ - `rascal run` passes stdin to the command when it comes from a file or a pipe.
58
+ - When rascal gets a signal while running a command, it removes the command's container, which kept
59
+ running before. `rascal clean` removes such containers left over from earlier versions or `kill -9`.
60
+ - Several commands can start the same environment at once.
61
+
62
+ ### Messages
63
+
64
+ - Explain what is wrong when a job has no image, its image uses an undefined variable, its
65
+ `extends:` templates cannot be resolved, or its `services_timeout` is not a number.
66
+ `rascal clean` and `rascal environments` still work for such jobs, and `rascal update --all` skips them.
67
+ - Warn about variables that reference undefined variables, like ones set in the project's CI/CD
68
+ settings, and about includes rascal cannot read.
69
+ - Suggest `docker login` when an image cannot be pulled for lack of credentials, explain what to do
70
+ when an image does not exist in its registry, and explain where rascal looked for `.gitlab-ci.yml`.
71
+ - Point to the logs of services that stopped, like when their settings are wrong.
72
+ - Explain each command in `rascal help <command>`, which calls the argument a job, like the README.
73
+
74
+
75
+ ## 0.4.1 (2026-07-30)
76
+
77
+ - Recreate a service container whose network no longer exists, instead of failing
78
+ to start it.
79
+
80
+
7
81
  ## 0.4.0 (2026-07-30)
8
82
 
9
83
  - Add `rascal run ENVIRONMENT -- COMMAND`, which runs a single command in an
data/CONTRIBUTING.md ADDED
@@ -0,0 +1,139 @@
1
+ # Working on rascal
2
+
3
+ This guide is for people and AI agents who change rascal. For using rascal, see the
4
+ [README](README.md).
5
+
6
+
7
+ ## Setup
8
+
9
+ You need Ruby 3.3 or newer and a running Docker daemon. Install the dependencies with
10
+ `bundle install`.
11
+
12
+ To try your working copy on a project, run its executable from the project directory, with the Ruby
13
+ from rascal's `.ruby-version` (it needs the gems from `bundle install`, not the project's):
14
+
15
+ ```sh
16
+ cd ~/projects/myapp
17
+ mise exec ruby@4.0.9 -- ruby ~/projects/rascal/exe/rascal run rspec -- bundle exec rspec
18
+ ```
19
+
20
+
21
+ ## How rascal is built
22
+
23
+ A command like `rascal run rspec -- rake` flows through four layers. Each change usually belongs in
24
+ one of them.
25
+
26
+ | Layer | Code | Responsibility |
27
+ |---|---|---|
28
+ | Command line | `lib/rascal/cli/` | `Main` defines the commands and options with Thor. Each command has a small class that finds the job and calls the environment. |
29
+ | CI config | `lib/rascal/gitlab/` | Turns `.gitlab-ci.yml` into an `Environment` for a job, like GitLab would read it. |
30
+ | Environment | `lib/rascal/environment.rb`, `service.rb`, `command_script.rb` | Starts a job's services, runs commands, cleans up, reports status. |
31
+ | Docker | `lib/rascal/docker/` | Everything that calls `docker`. |
32
+
33
+ `IOHelper` decides where output goes: `say` writes to stdout, which belongs to the command's output,
34
+ `info` and `warning` write rascal's own messages to stderr.
35
+
36
+ ### CI config: `Rascal::Gitlab`
37
+
38
+ - `ConfigFile` reads the YAML with its local `include:` files, and marks `!reference` tags.
39
+ - `Jobs` resolves each job like GitLab does (`extends:`, `default:`, `inherit:`, `!reference`), and
40
+ applies rascal's settings from the `.rascal` block and `.rascal.yml` on top. The result is a
41
+ `Job`: the job's config, its variables in layers, and its problems and warnings.
42
+ - `EnvironmentBuilder` turns a `Job` into an `Environment`: Docker names, volumes, the image, the
43
+ services and their aliases, and the expanded variables.
44
+ - `Variables` expands variable references like GitLab does.
45
+
46
+ Where a change goes:
47
+
48
+ - **A GitLab keyword that changes how jobs combine,** like `extends:`, goes into `Jobs`. A new global
49
+ keyword must be added to `Jobs::GLOBAL_KEYS`, or rascal takes it for a job.
50
+ - **A keyword rascal should use,** like a service's `entrypoint`, is read in `EnvironmentBuilder` and
51
+ passed on to `Environment` or `Service`, and from there to `Docker::*`.
52
+ - **A rascal setting** is read like a keyword. Also validate it as a problem (see
53
+ `EnvironmentBuilder#services_timeout`), show it in `Environment#status` and `CLI::Status`, and
54
+ document it in the README's Configuration section. If it may hold a `!reference`, add it to
55
+ `Jobs::KEYS_WITH_REFERENCES`.
56
+ - **An option for a single command** goes into `Main.command_environment_options` and
57
+ `Base#command_overrides`.
58
+
59
+ When unsure how GitLab treats something, look at GitLab's source (`lib/gitlab/ci/`), which the code
60
+ comments point to.
61
+
62
+ Problems and warnings are a core idea. A **problem** keeps a job's environment from starting, like a
63
+ missing image, but `rascal clean`, `environments` and `status` still work for it. A **warning** is
64
+ printed before each command, since it may make commands fail. Both are collected per job while
65
+ building the environment. Only a file rascal cannot read at all, like broken YAML, raises an error.
66
+
67
+ ### Environment and Docker
68
+
69
+ - `Environment` starts the network and services under a lock (so parallel commands do not start them
70
+ twice), waits for services that are still starting, and runs each command in a new container.
71
+ - `CommandScript` writes the bash script around a command: waiting for services, `before_shell`, the
72
+ command, `after_shell`, and giving files back to the host user.
73
+ - `Service` is one service of a job, in a long-lived `Docker::Container`.
74
+ - `Docker::Image` downloads images and reads their exposed ports and entrypoint.
75
+ `Docker::CommandContainers` runs the one-off containers of commands, and removes them when rascal
76
+ gets a signal. `Docker::Network` and `Docker::Volume` are what their names say.
77
+ - `Docker::Interface` is the only place that runs `docker` (except a signal handler, which must not).
78
+ Specs replace it with a mock.
79
+
80
+
81
+ ## Tests
82
+
83
+ All tests are RSpec specs, of three kinds:
84
+
85
+ | Tests | Location | What they cover | Speed |
86
+ |---|---|---|---|
87
+ | Unit specs | `spec/rascal/`, named like the class | Reading CI configs, variables, the command script, and other logic. Most tests belong here. How jobs combine goes into `gitlab/jobs_spec.rb`, how rascal uses a job into `gitlab/environment_builder_spec.rb`. Both write a `.gitlab-ci.yml` with the helpers in `spec/support/gitlab.rb`. | Fast |
88
+ | CLI specs | `spec/cli/`, one file per command, plus `starting_an_environment_spec.rb` | The command line, with a mocked Docker (`spec/support/docker_mock.rb`) that records which `docker` commands rascal would call. Also what real Docker cannot show easily, like `rascal shell` with a TTY or broken networks. | Fast |
89
+ | Integration specs | `spec/integration/` | The real `rascal` executable against a real Docker daemon. | About 30 seconds, plus pulling small images on the first run |
90
+
91
+ ```sh
92
+ bundle exec rake # everything, like CI does
93
+ bundle exec rspec --tag ~integration # only the fast specs
94
+ bundle exec rspec --tag integration # only the integration specs
95
+ ```
96
+
97
+ The integration specs fail with an explanation when Docker is not running. They do not skip, so a
98
+ green run always means everything was tested. Every spec in `spec/integration/` is tagged with
99
+ `integration: true` automatically.
100
+
101
+ Test each behavior once, at the cheapest level that can show it works:
102
+
103
+ - Reading and resolving CI configs belongs in unit specs, with one example per variation.
104
+ - What rascal does with Docker belongs in integration specs, for key paths and for behavior only
105
+ real Docker can show, like a job reaching its services by their alias, or exit statuses passing
106
+ through. Do not add one for every variation of a CI config.
107
+ - CLI specs cover the rest: command line errors and output, and situations that are hard to create
108
+ with real Docker.
109
+
110
+ Each integration spec creates a project directory named `rascal-it-<random>` in the system's temp
111
+ directory, and removes it together with its containers, networks and volumes afterwards. If you abort
112
+ a run, you can remove leftovers with:
113
+
114
+ ```sh
115
+ docker ps --all --filter name=rascal-rascal-it- --quiet | xargs -r docker rm --force
116
+ docker network ls --filter name=rascal-rascal-it- --quiet | xargs -r docker network rm
117
+ docker volume ls --filter name=rascal-rascal-it- --quiet | xargs -r docker volume rm
118
+ ```
119
+
120
+ If a run was aborted while a container was writing files, a leftover `rascal-it-*` directory in the
121
+ temp directory may contain files owned by root, which need `sudo rm -rf` to remove.
122
+
123
+
124
+ ## Conventions
125
+
126
+ - **Read CI configs like GitLab.** Where rascal reads `.gitlab-ci.yml`, it should behave like GitLab,
127
+ so a project needs no changes to its CI config for rascal. Settings for rascal go into the
128
+ `.rascal` block or `.rascal.yml`.
129
+ - **Help people out of trouble.** When something is likely to go wrong, prefer, in this order: a
130
+ message that explains the cause and the remedy; a troubleshooting entry in the README; a command
131
+ that fixes it. Fix things automatically only when there is no doubt that they are wrong, like files
132
+ owned by root in the project, since surprising changes confuse people and agents.
133
+ - **Keep messages and the README in sync.** Troubleshooting entries in the README are headed by the
134
+ text of the message they explain, so people find them by searching for the message.
135
+ - **Document what users notice.** Update the README, the command help in `lib/rascal/cli/main.rb`
136
+ where it applies, and add a line to the "Unreleased" section of `CHANGELOG.md` for every change in
137
+ behavior.
138
+ - **Do not cache Docker state to save time.** Stale state causes worse problems than a few
139
+ milliseconds per `docker` call.
data/Gemfile.common CHANGED
@@ -7,9 +7,6 @@ gemspec
7
7
 
8
8
  gem 'rake', '~> 13.0'
9
9
  gem 'rspec'
10
- gem 'cucumber'
11
- gem 'aruba'
12
10
  gem 'logger'
13
11
 
14
12
  gem 'guard-rspec'
15
- gem 'guard-cucumber'
data/Gemfile.lock CHANGED
@@ -1,49 +1,13 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- rascal (0.4.0)
4
+ rascal (0.5.0)
5
5
  thor (>= 1.0.0)
6
6
 
7
7
  GEM
8
8
  remote: https://rubygems.org/
9
9
  specs:
10
- aruba (0.14.14)
11
- childprocess (>= 0.6.3, < 4.0.0)
12
- contracts (~> 0.9)
13
- cucumber (>= 1.3.19)
14
- ffi (~> 1.9)
15
- rspec-expectations (>= 2.99)
16
- thor (>= 0.19, < 2.0)
17
- bigdecimal (3.1.9)
18
- builder (3.3.0)
19
- childprocess (3.0.0)
20
10
  coderay (1.1.3)
21
- contracts (0.17.3)
22
- cucumber (9.2.1)
23
- builder (~> 3.2)
24
- cucumber-ci-environment (> 9, < 11)
25
- cucumber-core (> 13, < 14)
26
- cucumber-cucumber-expressions (~> 17.0)
27
- cucumber-gherkin (> 24, < 28)
28
- cucumber-html-formatter (> 20.3, < 22)
29
- cucumber-messages (> 19, < 25)
30
- diff-lcs (~> 1.5)
31
- mini_mime (~> 1.1)
32
- multi_test (~> 1.1)
33
- sys-uname (~> 1.2)
34
- cucumber-ci-environment (10.0.1)
35
- cucumber-core (13.0.3)
36
- cucumber-gherkin (>= 27, < 28)
37
- cucumber-messages (>= 20, < 23)
38
- cucumber-tag-expressions (> 5, < 7)
39
- cucumber-cucumber-expressions (17.1.0)
40
- bigdecimal
41
- cucumber-gherkin (27.0.0)
42
- cucumber-messages (>= 19.1.4, < 23)
43
- cucumber-html-formatter (21.9.0)
44
- cucumber-messages (> 19, < 28)
45
- cucumber-messages (22.0.0)
46
- cucumber-tag-expressions (6.1.2)
47
11
  diff-lcs (1.5.1)
48
12
  ffi (1.17.1)
49
13
  formatador (1.1.0)
@@ -57,9 +21,6 @@ GEM
57
21
  shellany (~> 0.0)
58
22
  thor (>= 0.18.1)
59
23
  guard-compat (1.2.1)
60
- guard-cucumber (3.0.0)
61
- cucumber (>= 3.1)
62
- nenv (>= 0.1)
63
24
  guard-rspec (4.7.3)
64
25
  guard (~> 2.1)
65
26
  guard-compat (~> 1.1)
@@ -70,8 +31,6 @@ GEM
70
31
  logger (1.7.0)
71
32
  lumberjack (1.2.8)
72
33
  method_source (1.0.0)
73
- mini_mime (1.1.5)
74
- multi_test (1.1.0)
75
34
  nenv (0.3.0)
76
35
  notiffany (0.1.3)
77
36
  nenv (~> 0.1)
@@ -97,17 +56,12 @@ GEM
97
56
  rspec-support (~> 3.12.0)
98
57
  rspec-support (3.12.0)
99
58
  shellany (0.0.1)
100
- sys-uname (1.3.1)
101
- ffi (~> 1.1)
102
59
  thor (1.3.2)
103
60
 
104
61
  PLATFORMS
105
62
  ruby
106
63
 
107
64
  DEPENDENCIES
108
- aruba
109
- cucumber
110
- guard-cucumber
111
65
  guard-rspec
112
66
  logger
113
67
  rake (~> 13.0)
data/Guardfile CHANGED
@@ -14,12 +14,3 @@ guard :rspec, cmd: 'bundle exec rspec', notification: false, failed_mode: :focus
14
14
  ruby = dsl.ruby
15
15
  dsl.watch_spec_files_for(ruby.lib_files)
16
16
  end
17
-
18
- guard 'cucumber', all_on_start: false, all_after_pass: false, notification: false do
19
- watch(%r{^features/.+\.feature$})
20
- watch(%r{^features/support/.+$}) { "features" }
21
-
22
- watch(%r{^features/step_definitions/(.+)_steps\.rb$}) do |m|
23
- Dir[File.join("**/#{m[1]}.feature")][0] || "features"
24
- end
25
- end