@miroshnik/elves 2026.1106.1 → 2026.1109.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.
- package/README.md +1 -1
- package/bin/elves.ts +4 -4
- package/package.json +2 -2
- package/skills/task-env/SKILL.md +13 -11
- package/skills/task-env/reference.md +67 -11
- package/skills/task-env/scripts/task-env.ts +243 -49
package/README.md
CHANGED
|
@@ -300,7 +300,7 @@ Project checks — `lint`, `typecheck`, `test`, `test:*` — go through the mach
|
|
|
300
300
|
|
|
301
301
|
### [`task-env`](skills/task-env/SKILL.md) — a task's environment: its Compose stack and addresses `*.localhost`
|
|
302
302
|
|
|
303
|
-
A task's stack is the Docker Compose project `<project>-<N>`: parallel sessions of one project keep their own apps and databases without touching each other. One proxy per machine — Traefik in Docker — gives containers of task stacks the addresses `http://<service>.<N>.<project>.localhost` by their labels: no host port per app, and different hosts keep their own cookies, so parallel sessions and the owner's browser don't log each other out. A container without labels isn't published, a stopped one leaves the routes; `check -g` and the session start name whether the proxy runs, with the command to start it. `task-env up` brings the task's stack up by the number in the branch — the project's compose file plus the proxy's labels for the HTTP services named in `.agents/elves.json` — and prints the addresses; `task-env e2e` brings the e2e stack `<project>-<N>-e2e` up anew with clean volumes and runs the command with its addresses in `TASK_ENV_*` variables; `task-env down` takes both stacks of the task down with their volumes — `github task close` calls it; `task-env prune` finds the stacks of closed tasks left on the machine by the tasks' state on GitHub and takes them down; a stack that didn't come up is named by the failed service, its state and the end of its log. The project's `check` holds the compose file to the isolation rules — no `container_name`, no fixed host port, volumes and networks without `name:` and `external`, code by relative paths — and names each violation with the rule and the service; it reads `docker compose config`, so every form of writing is covered.
|
|
303
|
+
A task's stack is the Docker Compose project `<project>-<N>`: parallel sessions of one project keep their own apps and databases without touching each other. One proxy per machine — Traefik in Docker — gives containers of task stacks the addresses `http://<service>.<N>.<project>.localhost` by their labels: no host port per app, and different hosts keep their own cookies, so parallel sessions and the owner's browser don't log each other out. A container without labels isn't published, a stopped one leaves the routes; `check -g` and the session start name whether the proxy runs, with the command to start it. `task-env up` brings the task's stack up by the number in the branch — the project's compose file plus the proxy's labels for the HTTP services named in `.agents/elves.json` — and prints the addresses; `task-env e2e` brings the e2e stack `<project>-<N>-e2e` up anew with clean volumes and runs the command with its addresses in `TASK_ENV_*` variables; `task-env down` takes both stacks of the task down with their volumes and the images they built — `github task close` calls it; `task-env prune` finds the stacks of closed tasks left on the machine by the tasks' state on GitHub and takes them down; a stack that didn't come up is named by the failed service, its state and the end of its log. The project's `check` holds the compose file to the isolation rules — no `container_name`, no fixed host port, volumes and networks without `name:` and `external`, code by relative paths — and names each violation with the rule and the service; it reads `docker compose config`, so every form of writing is covered.
|
|
304
304
|
|
|
305
305
|
`task-env up | e2e | down | prune` · `task-env proxy up | down | status` · `task-env check [<dir>]`
|
|
306
306
|
|
package/bin/elves.ts
CHANGED
|
@@ -209,7 +209,7 @@ breaks task isolation, standards and architecture have no test:spec script or th
|
|
|
209
209
|
Elves clone too) with "batch": true runs a workflow on a PR into a batch branch — on.pull_request lets a batch branch in,
|
|
210
210
|
its gate is the checks before a commit and pr premerge (ci.md of the spec skill, «Batches»), 2 — the check is unavailable; the machine's copy and a project's package version are compared with the latest release (from the npm
|
|
211
211
|
package — by restarting from the latest release's package), a --link clone — with origin/main. For a project names the
|
|
212
|
-
mode (auto) and the language, holds the compose file to the task isolation rules (❌ per violation, ○ — not checked: no
|
|
212
|
+
mode (auto) and the language, holds the compose file to the task isolation rules (❌ per violation, ! — a warning, ○ — not checked: no
|
|
213
213
|
docker compose; the task-env skill), names a test that runs standards and architecture again next to test:spec (○, the
|
|
214
214
|
ready test without them) and warns (!) if a script in slot calls turbo and turbo.json doesn't pass the queue variables
|
|
215
215
|
to tasks (the exit code stays the same); for the machine the elves command missing or of another release is falling
|
|
@@ -1668,8 +1668,8 @@ interface Result {
|
|
|
1668
1668
|
|
|
1669
1669
|
/**
|
|
1670
1670
|
* The project's compose file against the task isolation rules (the task-env skill, tests/capabilities/task-env/stacks): a `❌`
|
|
1671
|
-
* line per violation, `○` — not checked (no docker compose, the config doesn't parse):
|
|
1672
|
-
* exit code of `check` doesn't change. No compose file — no lines, the script doesn't start. The script runs under the
|
|
1671
|
+
* line per violation, `!` — a warning, `○` — not checked (no docker compose, the config doesn't parse): neither is a
|
|
1672
|
+
* violation, and the exit code of `check` doesn't change. No compose file — no lines, the script doesn't start. The script runs under the
|
|
1673
1673
|
* same Bun as the installer.
|
|
1674
1674
|
*/
|
|
1675
1675
|
function composeCheck(root: string): { lines: string[]; violations: boolean } {
|
|
@@ -1678,8 +1678,8 @@ function composeCheck(root: string): { lines: string[]; violations: boolean } {
|
|
|
1678
1678
|
const r = spawnSync(process.execPath, ["--no-env-file", TASK_ENV, "check", root], { encoding: "utf8", timeout: TASK_ENV_TIMEOUT });
|
|
1679
1679
|
const notChecked = (why: string) => ({ lines: [` ○ ${file}: not checked — ${why}`], violations: false });
|
|
1680
1680
|
if (r.error) return notChecked(`task-env: ${r.error.message}`);
|
|
1681
|
-
if (r.status === 0) return { lines: [], violations: false };
|
|
1682
1681
|
const lines = r.stdout.split("\n").filter(Boolean).map((l) => ` ${l}`);
|
|
1682
|
+
if (r.status === 0) return { lines: lines.filter((l) => l.startsWith(" !")), violations: false };
|
|
1683
1683
|
if (r.status === 1 || (r.status === 2 && lines.length)) return { lines, violations: r.status === 1 };
|
|
1684
1684
|
return notChecked(`task-env: ${r.stderr.trim().split("\n")[0] || `exit code ${r.status ?? r.signal}`}`);
|
|
1685
1685
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@miroshnik/elves",
|
|
3
|
-
"version": "2026.
|
|
3
|
+
"version": "2026.1109.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Elves — a development flow with AI agents: shared rules and skills for any agent; install — bunx @miroshnik/elves install -g; the installer and skill scripts — TypeScript under Bun, tests — bun test in tests/",
|
|
6
6
|
"repository": {
|
|
@@ -72,5 +72,5 @@
|
|
|
72
72
|
"eslint-plugin-boundaries": "^7.2.0",
|
|
73
73
|
"knip": "^6.41.0"
|
|
74
74
|
},
|
|
75
|
-
"gitHead": "
|
|
75
|
+
"gitHead": "a09166687dccfad2f880d3f299812d5d9fd04de6"
|
|
76
76
|
}
|
package/skills/task-env/SKILL.md
CHANGED
|
@@ -18,7 +18,7 @@ no host port per app, no port search. The scheme and the reasons — epic
|
|
|
18
18
|
```bash
|
|
19
19
|
bun --no-env-file <skill dir>/scripts/task-env.ts up [<N>] [--profile <p>]... # the task's stack by the branch, its addresses
|
|
20
20
|
bun --no-env-file <skill dir>/scripts/task-env.ts e2e [--profile <p>]... [-- <command>] # the e2e stack anew, the command with its addresses
|
|
21
|
-
bun --no-env-file <skill dir>/scripts/task-env.ts down [<N>] # the task's stacks with their volumes
|
|
21
|
+
bun --no-env-file <skill dir>/scripts/task-env.ts down [<N>] # the task's stacks with their volumes and built images
|
|
22
22
|
bun --no-env-file <skill dir>/scripts/task-env.ts prune # stacks of the project's closed tasks
|
|
23
23
|
bun --no-env-file <skill dir>/scripts/task-env.ts proxy up # start it (or bring it to the compose file), wait until healthy
|
|
24
24
|
bun --no-env-file <skill dir>/scripts/task-env.ts proxy status # 0 — running, 1 — not running (the start command), 2 — no Docker
|
|
@@ -57,7 +57,8 @@ The settings — `env.http` in the project's `.agents/elves.json`, a service →
|
|
|
57
57
|
```
|
|
58
58
|
|
|
59
59
|
A service of `env.http` that isn't in the compose file — a `!` line, not an error. No `env.http` — no labels, no
|
|
60
|
-
proxy, only published ports.
|
|
60
|
+
proxy, only published ports. `env.memoryMb` — what the stack needs, measured: a stack the Docker VM can't fit doesn't
|
|
61
|
+
come up (`reference.md`, "The Docker VM's memory").
|
|
61
62
|
|
|
62
63
|
**The app's own address** — from the compose file: `up` and `e2e` give Compose's process the address of each
|
|
63
64
|
`env.http` service in `TASK_ENV_<SERVICE>_URL` (the names the e2e command gets), and the compose file passes them to the app — a base URL,
|
|
@@ -80,9 +81,10 @@ variables live only in the environment of the script's Compose process — no `.
|
|
|
80
81
|
goes into `build.args` the same way: Compose interpolates them too.
|
|
81
82
|
|
|
82
83
|
**The override** — the proxy's labels for the `env.http` services (a database isn't published), on Compose's stdin,
|
|
83
|
-
not a file; the script joins those services to the proxy's network itself, without their short name
|
|
84
|
-
|
|
85
|
-
|
|
84
|
+
not a file; the script joins those services to the proxy's network itself, without their short name; still, the short
|
|
85
|
+
name of an `env.http` service isn't guaranteed inside the stack — address it by the container name
|
|
86
|
+
`${COMPOSE_PROJECT_NAME}-<service>-1` (`check` warns with `!`); `up` starts the proxy first if it isn't running —
|
|
87
|
+
reference.md, "Override and compose files"; the labels — reference.md, "Labels of a task stack's service".
|
|
86
88
|
|
|
87
89
|
**e2e** — `<project>-<N>-e2e`, apart from the dev stack of the task: `down --volumes` and `up` again on every run, so
|
|
88
90
|
the run starts on clean volumes; then the command runs on the host (the current directory, the script's environment)
|
|
@@ -98,12 +100,12 @@ with the addresses of the e2e stack:
|
|
|
98
100
|
`e2e` only brings the stack up. The stack stays until the next run: a failed run is examined on it
|
|
99
101
|
(`docker compose -p <project>-<N>-e2e logs`).
|
|
100
102
|
|
|
101
|
-
**down** — both stacks of the task with their volumes
|
|
102
|
-
the main checkout's aren't touched; `task close` of the `github` skill calls
|
|
103
|
-
stacks down". **prune** — the stacks of the project's closed tasks left on the
|
|
104
|
-
a question: a closed task's stack is nobody's; what is left —
|
|
105
|
-
didn't come up** — code 1, each failed service with its state
|
|
106
|
-
Exit codes — reference.md, "Exit codes".
|
|
103
|
+
**down** — both stacks of the task with their volumes and the images they built (pulled ones stay); without a number —
|
|
104
|
+
the branch's task; other tasks' stacks and the main checkout's aren't touched; `task close` of the `github` skill calls
|
|
105
|
+
it — reference.md, "Taking a task's stacks down". **prune** — the stacks of the project's closed tasks left on the
|
|
106
|
+
machine go with their volumes and built images, without a question: a closed task's stack is nobody's; what is left —
|
|
107
|
+
reference.md, "Stacks of closed tasks". **A stack that didn't come up** — code 1, each failed service with its state
|
|
108
|
+
and log — reference.md, "A stack that didn't come up". Exit codes — reference.md, "Exit codes".
|
|
107
109
|
|
|
108
110
|
**Machine queue** — a bring-up is heavy work: `up` and `e2e` hold a place in the `slot` queue until the containers
|
|
109
111
|
are healthy, the e2e command runs outside it; a package.json script with its own `docker compose up` — `check` names it.
|
|
@@ -24,6 +24,15 @@ chance. Connected by hand, a container is named in the proxy's network only by i
|
|
|
24
24
|
`<stack>-<service>-<n>`, and the short name stays in the stack's own networks. The connect goes between creating and
|
|
25
25
|
starting: Traefik sees the network on the start event, and the next `up` doesn't recreate the container.
|
|
26
26
|
|
|
27
|
+
**Inside the stack the short name of an `env.http` service isn't guaranteed** (#806). Docker looks a name up over the
|
|
28
|
+
container's networks in the order of their names, and `elves-proxy` comes before `<stack>_<network>`: a short name that
|
|
29
|
+
got into the proxy's network overrides the stack's own. It happened with two stacks up — a name from stack A led to a
|
|
30
|
+
container of stack B; how the name got there isn't established, and repeating the steps gives no alias. Address such a
|
|
31
|
+
service by the container name `${COMPOSE_PROJECT_NAME}-<service>-1`, one on the machine. `task-env check` warns with a
|
|
32
|
+
`!` line (the exit code doesn't change, the project's `check` prints it too) when a URL or `host:port` in a service's
|
|
33
|
+
variables, `command`, `entrypoint`, a bind-mounted file or `configs` names an `env.http` service by its short name; a
|
|
34
|
+
mounted directory isn't read — it is code.
|
|
35
|
+
|
|
27
36
|
## Taking a task's stacks down
|
|
28
37
|
|
|
29
38
|
**down** — `down --volumes --remove-orphans` of `<project>-<N>` and `<project>-<N>-e2e` by the Compose project, from
|
|
@@ -33,27 +42,39 @@ stacks and the main checkout's aren't touched. `down` without a number — the b
|
|
|
33
42
|
|
|
34
43
|
```
|
|
35
44
|
+ stack shop-42: down, with its volumes
|
|
45
|
+
+ stack shop-43: down, with its volumes and images app/web:shop-43, shop-43-worker:latest
|
|
46
|
+
○ image app/api:shop-43 of stack shop-43: left — container shop-44-api-1 uses it
|
|
36
47
|
○ stacks shop-42, shop-42-e2e: none on the machine
|
|
37
48
|
! stack shop-42: not removed — <Docker's reason>
|
|
38
49
|
```
|
|
39
50
|
|
|
40
|
-
|
|
41
|
-
(`com.docker.compose.project`),
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
51
|
+
**The images the stack built go with it** (#807): Compose labels a built image with the stack's project
|
|
52
|
+
(`com.docker.compose.project`), a pulled one — a database, a broker, a base — has no such label and stays. A compose
|
|
53
|
+
file may tag a built image by the stack, `image: app/web:${COMPOSE_PROJECT_NAME}`, so that a parallel stack's build
|
|
54
|
+
doesn't move a machine-wide tag to another tree's code; such an image outlives its stack — a shared tag's previous
|
|
55
|
+
build lost its name and went by itself. `docker image rm` of each `repo:tag` (a dangling one — by its ID), without
|
|
56
|
+
`--force`: an image a container still runs on — another stack's, a test's own — stays, an `○` line names it and the
|
|
57
|
+
containers; another failure — a `!` line, code 2. `e2e` re-creates its stack on the same images: `up --build` rebuilds
|
|
58
|
+
them.
|
|
59
|
+
|
|
60
|
+
Only the stacks that are on the machine are taken down — found by the label of containers, volumes, networks and
|
|
61
|
+
built images (`com.docker.compose.project`), not by `docker compose ls`: a stack left with volumes only (`down`
|
|
62
|
+
without `-v`, containers removed by hand) or with its images only isn't in its list. No compose file in the checkout —
|
|
63
|
+
`○ no compose file … — the project has no task stacks`, Docker isn't called: `task close` of a project without Compose
|
|
64
|
+
doesn't depend on Docker running. No docker on the machine — an `○` line; Docker doesn't answer — a `!` line with the
|
|
65
|
+
reason.
|
|
45
66
|
|
|
46
67
|
## Stacks of closed tasks — prune
|
|
47
68
|
|
|
48
69
|
**prune** — the stacks of the project's closed tasks left on the machine (orphans: a task closed without `task
|
|
49
70
|
close`, a close that couldn't reach Docker, a task that removed the compose file): every stack `<project>-<N>` and
|
|
50
71
|
`<project>-<N>-e2e` on the machine, the task's state by GitHub (`gh api repos/<owner>/<repo>/issues/<N>`, the
|
|
51
|
-
repository — the checkout's `origin`). Closed — the stacks go with their volumes right away, without
|
|
52
|
-
closed task's stack is nobody's.
|
|
72
|
+
repository — the checkout's `origin`). Closed — the stacks go with their volumes and built images right away, without
|
|
73
|
+
a question: a closed task's stack is nobody's; a stack left with its images only — taken down before #807 — goes too.
|
|
53
74
|
|
|
54
75
|
```
|
|
55
76
|
○ stack shop-7: no task #7 in acme/shop — left
|
|
56
|
-
+ stack shop-41: down, with its volumes — task #41 is closed
|
|
77
|
+
+ stack shop-41: down, with its volumes and image app/web:shop-41 — task #41 is closed
|
|
57
78
|
○ stack shop-42: task #42 is open — left
|
|
58
79
|
○ stack shop-9: its containers are from /work/shop-9 — another project, left
|
|
59
80
|
```
|
|
@@ -74,12 +95,47 @@ stack shop-42: not up — container shop-42-api-1 exited (3)
|
|
|
74
95
|
| Error: connect ECONNREFUSED db:5432
|
|
75
96
|
```
|
|
76
97
|
|
|
98
|
+
## The Docker VM's memory
|
|
99
|
+
|
|
100
|
+
Containers' limits don't protect the VM: the sum of several stacks' limits is far above it. So `up` and `e2e`, before
|
|
101
|
+
anything starts and inside the machine queue, compare what the stack needs with the VM's `MemAvailable` plus
|
|
102
|
+
`SwapFree` (`/proc/meminfo` from a one-off container of the proxy's image):
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
{ "env": { "memoryMb": 6144 } }
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`env.memoryMb` in `.agents/elves.json` — MiB, a number from the project's measurement of a full stack under load; not
|
|
109
|
+
the sum of `mem_limit`: that upper bound is far above real use, and a full stack would never come up. No field — a
|
|
110
|
+
reserve of 1024 MiB. A stack with a running container is in the VM's numbers itself and isn't checked.
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
stack shop-42: not started — the Docker VM lacks memory: needs 6144 MiB, has 2560 MiB (available 2048 + free swap 512); stacks on it: shop-41, shop-43-e2e — take down one nobody needs: task-env down <N>
|
|
114
|
+
○ Docker VM memory not checked — <Docker's reason>
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
The first — code 2, nothing is started; the second — the bring-up goes on.
|
|
118
|
+
|
|
119
|
+
**A container killed: the VM's memory or its own limit.** From outside both look alike: `docker inspect` gives
|
|
120
|
+
`OOMKilled: true`, exit code 137, and it reads as a code failure or a low limit. The difference is inside:
|
|
121
|
+
|
|
122
|
+
| | the container's `memory.events` | VM kernel log (`dmesg`) | what to do |
|
|
123
|
+
|---|---|---|---|
|
|
124
|
+
| its own limit | `oom` > 0, `oom_kill` > 0 | `constraint=CONSTRAINT_MEMCG`, `oom_memcg=…` | raise the limit or fix the code |
|
|
125
|
+
| the VM's memory | `oom` 0, `oom_kill` 1 | `constraint=CONSTRAINT_NONE`, `global_oom` | take down stacks, enlarge the VM or raise `env.memoryMb` |
|
|
126
|
+
|
|
127
|
+
`memory.events` — `docker exec <container> cat /sys/fs/cgroup/memory.events` in a container still running (a dead
|
|
128
|
+
one's counters are gone: read the kernel log). The kernel log of Docker Desktop's VM — `docker run --rm --privileged
|
|
129
|
+
--entrypoint dmesg traefik:v3.7`. On a VM OOM the victim is the largest process with `oom_score_adj` 0, usually a JVM
|
|
130
|
+
or a database, and not necessarily of the stack that gave the load: the task that sees the failure may not be its
|
|
131
|
+
cause.
|
|
132
|
+
|
|
77
133
|
## Exit codes
|
|
78
134
|
|
|
79
135
|
`up` — 0 up, 1 not up, 2 not tried (no compose file, broken settings, Docker unavailable, `docker compose config`
|
|
80
|
-
fails); `e2e` — the command's, otherwise as `up`; `down` and `prune` — 0
|
|
81
|
-
unavailable or (`prune`) a task's state isn't checked; `proxy status` — 0 running, 1 not running (the start command),
|
|
82
|
-
2 no Docker; `check` — 0 the rules hold or no compose file, 1 violations, 2 not checked.
|
|
136
|
+
fails, the Docker VM can't fit the stack); `e2e` — the command's, otherwise as `up`; `down` and `prune` — 0 (an image a container uses, left, too), 2
|
|
137
|
+
if a stack or an image isn't removed, Docker is unavailable or (`prune`) a task's state isn't checked; `proxy status` — 0 running, 1 not running (the start command),
|
|
138
|
+
2 no Docker; `check` — 0 the rules hold or no compose file (`!` lines too), 1 violations, 2 not checked.
|
|
83
139
|
|
|
84
140
|
## The proxy — container, routes, API
|
|
85
141
|
|
|
@@ -9,9 +9,9 @@
|
|
|
9
9
|
* proxy's labels and network for the HTTP services of `env.http` in `.agents/elves.json`; their addresses go to Compose's
|
|
10
10
|
* interpolation in `TASK_ENV_<SERVICE>_URL` (the compose file gives the app its own address); it prints the addresses.
|
|
11
11
|
* `e2e` brings `<project>-<N>-e2e` up anew with clean volumes and runs the command on the host with the e2e addresses
|
|
12
|
-
* in `TASK_ENV_*` variables; `down` takes both stacks of a task down with their volumes
|
|
13
|
-
* takes down the stacks of the project's closed tasks left on the machine — orphans, the
|
|
14
|
-
* that didn't come up — each failed service with its state and the end of its log.
|
|
12
|
+
* in `TASK_ENV_*` variables; `down` takes both stacks of a task down with their volumes and the images they built —
|
|
13
|
+
* `task close` calls it; `prune` takes down the stacks of the project's closed tasks left on the machine — orphans, the
|
|
14
|
+
* task's state by GitHub. A stack that didn't come up — each failed service with its state and the end of its log.
|
|
15
15
|
*
|
|
16
16
|
* `check` holds the project's compose file to the isolation rules: Compose keeps two stacks of one project apart by the
|
|
17
17
|
* project name — containers, volumes and networks get its prefix — and four entries bypass the prefix and break
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
* unsandboxed call — an `excludedCommands` entry for it doesn't take it out (SKILL.md, «Docker and the sandbox»).
|
|
44
44
|
*/
|
|
45
45
|
import { spawnSync } from "node:child_process";
|
|
46
|
-
import { appendFileSync, existsSync, readFileSync } from "node:fs";
|
|
46
|
+
import { appendFileSync, existsSync, readFileSync, statSync } from "node:fs";
|
|
47
47
|
import path from "node:path";
|
|
48
48
|
import { fileURLToPath } from "node:url";
|
|
49
49
|
|
|
@@ -61,9 +61,11 @@ Brings the task's stack up — the Compose project <project>-<N> by the branch <
|
|
|
61
61
|
number (in the middle of a rebase — the branch being rebased; a linked worktree without a task branch — the task of
|
|
62
62
|
ELVES_TASK=<N>, without it refused: give N) — and prints its addresses: env.http services of .agents/elves.json through the proxy, published ports on
|
|
63
63
|
127.0.0.1; the HTTP addresses go to the compose file's interpolation in TASK_ENV_<SERVICE>_URL; --profile — Compose
|
|
64
|
-
profiles. The bring-up takes a place in the machine queue (slot) until the containers are healthy.
|
|
65
|
-
|
|
66
|
-
|
|
64
|
+
profiles. The bring-up takes a place in the machine queue (slot) until the containers are healthy. A stack not running
|
|
65
|
+
yet that the Docker VM can't fit — env.memoryMb of .agents/elves.json, without it a reserve, against its available
|
|
66
|
+
memory and free swap — isn't brought up: the numbers and the stacks on the VM. Code 0 — up, 1 — a service failed (its
|
|
67
|
+
state and log), 2 — not tried; not up — the reason is appended to the file of ELVES_TASK_ENV_FAILED, if given (pr
|
|
68
|
+
premerge of the github skill: «couldn't check», not a red check).
|
|
67
69
|
|
|
68
70
|
Examples:
|
|
69
71
|
task-env up
|
|
@@ -74,25 +76,26 @@ Examples:
|
|
|
74
76
|
The e2e stack <project>-<N>-e2e anew with clean volumes (its own addresses in the interpolation), then the command with
|
|
75
77
|
its addresses in TASK_ENV_PROJECT, TASK_ENV_<SERVICE>_URL, TASK_ENV_<SERVICE>_<PORT>; the exit code is the command's; the
|
|
76
78
|
stack stays until the next run. The bring-up takes a place in the machine queue (slot) until the containers are healthy,
|
|
77
|
-
the command runs outside it.
|
|
79
|
+
the command runs outside it; the Docker VM's memory is checked as in up.
|
|
78
80
|
|
|
79
81
|
Examples:
|
|
80
82
|
task-env e2e -- npx playwright test
|
|
81
83
|
task-env e2e --profile worker -- bun test e2e`,
|
|
82
84
|
down: `task-env down [<N>]
|
|
83
85
|
|
|
84
|
-
Takes the stacks of task N (default — the branch's) down with their volumes
|
|
85
|
-
○ none, ! not removed (code 2);
|
|
86
|
-
the
|
|
86
|
+
Takes the stacks of task N (default — the branch's) down with their volumes and the images they built (pulled ones
|
|
87
|
+
stay): dev and e2e; a line per stack: + down, ○ none, ! not removed (code 2); an image another container still uses —
|
|
88
|
+
left, named by a ○ line; no compose file in the checkout — nothing to take down, Docker isn't called; task close of the
|
|
89
|
+
github skill calls it.
|
|
87
90
|
|
|
88
91
|
Examples:
|
|
89
92
|
task-env down
|
|
90
93
|
task-env down 42`,
|
|
91
94
|
prune: `task-env prune
|
|
92
95
|
|
|
93
|
-
Takes down the stacks of the project's closed tasks left on the machine (orphans) with their volumes
|
|
94
|
-
by GitHub (gh); stacks of open tasks, of the main checkout,
|
|
95
|
-
the same name — left.
|
|
96
|
+
Takes down the stacks of the project's closed tasks left on the machine (orphans) with their volumes and built images —
|
|
97
|
+
a stack left with its images only too: the task's state — by GitHub (gh); stacks of open tasks, of the main checkout,
|
|
98
|
+
of numbers that aren't tasks and of another repository with the same name — left.
|
|
96
99
|
|
|
97
100
|
Examples:
|
|
98
101
|
task-env prune`,
|
|
@@ -100,8 +103,10 @@ Examples:
|
|
|
100
103
|
|
|
101
104
|
Holds the compose file in <dir> (default — the current directory) to the task isolation rules: no container_name, no
|
|
102
105
|
fixed host port, volumes and networks without name and external, code by paths relative to the compose file; one ❌ line
|
|
103
|
-
per violation.
|
|
104
|
-
|
|
106
|
+
per violation. A ! line — a service addresses an env.http service by its short name (a variable, command, entrypoint, a
|
|
107
|
+
mounted config): that name isn't guaranteed to stay in the stack, the container name \${COMPOSE_PROJECT_NAME}-<service>-1
|
|
108
|
+
is; the code doesn't change. Code 0 — the rules hold or there is no compose file, 1 — violations, 2 — not checked (no
|
|
109
|
+
docker compose, the config doesn't parse).
|
|
105
110
|
|
|
106
111
|
Examples:
|
|
107
112
|
task-env check
|
|
@@ -386,6 +391,8 @@ export const COMPOSE_FILES = ["compose.yaml", "compose.yml", "docker-compose.yam
|
|
|
386
391
|
const MACHINE = /^\/(?:var\/run|run|etc|dev|proc|sys)(?:\/|$)/;
|
|
387
392
|
/** `docker compose config` reads a few files — longer than this is a hang, not work. */
|
|
388
393
|
const CONFIG_TIMEOUT = 20_000;
|
|
394
|
+
/** A mounted file bigger than this is data, not a config: `check` doesn't read it for addresses. */
|
|
395
|
+
const MOUNTED_LIMIT = 1024 * 1024;
|
|
389
396
|
|
|
390
397
|
interface Port {
|
|
391
398
|
target: number;
|
|
@@ -403,6 +410,10 @@ interface Service {
|
|
|
403
410
|
volumes?: Mount[];
|
|
404
411
|
build?: { context?: string; dockerfile?: string };
|
|
405
412
|
networks?: Record<string, unknown>;
|
|
413
|
+
environment?: Record<string, string | null>;
|
|
414
|
+
command?: string[] | null;
|
|
415
|
+
entrypoint?: string[] | null;
|
|
416
|
+
configs?: { source: string }[];
|
|
406
417
|
}
|
|
407
418
|
interface Resource {
|
|
408
419
|
name?: string;
|
|
@@ -414,6 +425,7 @@ interface Config {
|
|
|
414
425
|
services?: Record<string, Service>;
|
|
415
426
|
volumes?: Record<string, Resource>;
|
|
416
427
|
networks?: Record<string, Resource>;
|
|
428
|
+
configs?: Record<string, { file?: string; content?: string }>;
|
|
417
429
|
}
|
|
418
430
|
|
|
419
431
|
const absolute = (p: string) => p.startsWith("/") || p === "~" || p.startsWith("~/");
|
|
@@ -459,6 +471,63 @@ function violations(config: Config, file: string): string[] {
|
|
|
459
471
|
return out;
|
|
460
472
|
}
|
|
461
473
|
|
|
474
|
+
/**
|
|
475
|
+
* An address that names `service` by its short name: the host of a URL or `host:port`. A longer name doesn't count —
|
|
476
|
+
* `<stack>-web-1`, `web.42.shop.localhost`, `webapp`, and neither does the last segment of a path or an image
|
|
477
|
+
* (`registry.test/web:3000`).
|
|
478
|
+
*/
|
|
479
|
+
function shortAddress(service: string): RegExp {
|
|
480
|
+
const name = service.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
481
|
+
return new RegExp(`[a-z][a-z0-9+.-]*://(?:[^/\\s@]*@)?${name}(?![\\w.-])|(?<![\\w./-])${name}:\\d{1,5}(?!\\d)`, "i");
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
/** The text of a mounted file relative to the compose file; a directory (code), a missing or an oversized file — nothing. */
|
|
485
|
+
function mountedText(dir: string, source: string): string {
|
|
486
|
+
try {
|
|
487
|
+
const file = path.resolve(dir, source);
|
|
488
|
+
const stat = statSync(file);
|
|
489
|
+
return stat.isFile() && stat.size <= MOUNTED_LIMIT ? readFileSync(file, "utf8") : "";
|
|
490
|
+
} catch {
|
|
491
|
+
return "";
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
/**
|
|
496
|
+
* `!` lines (#806): a service of the stack addresses an `env.http` service by its short name. Docker looks a name up over
|
|
497
|
+
* the container's networks in the order of their names, the proxy's network comes before `<stack>_<network>`, so a short
|
|
498
|
+
* name that got into the proxy's network — it happened, how is not established — leads to another task's stack; the
|
|
499
|
+
* container's name is one on the machine. A warning, not a violation: short names are the norm in compose files, and
|
|
500
|
+
* normally the name stays the stack's. Environment (with `env_file`, Compose merged it), `command`, `entrypoint`, bind
|
|
501
|
+
* mounted files and `configs`.
|
|
502
|
+
*/
|
|
503
|
+
function shortNames(config: Config, http: Record<string, number>, dir: string, file: string): string[] {
|
|
504
|
+
const targets = Object.keys(http).filter((s) => config.services?.[s]);
|
|
505
|
+
const out: string[] = [];
|
|
506
|
+
for (const [name, s] of Object.entries(config.services ?? {})) {
|
|
507
|
+
const places: [string, string][] = [
|
|
508
|
+
...Object.entries(s.environment ?? {}).map(([k, v]): [string, string] => [`environment ${k}`, v ?? ""]),
|
|
509
|
+
["command", (s.command ?? []).join(" ")],
|
|
510
|
+
["entrypoint", (s.entrypoint ?? []).join(" ")],
|
|
511
|
+
];
|
|
512
|
+
for (const v of s.volumes ?? []) {
|
|
513
|
+
if (v.type === "bind" && v.source && !absolute(v.source)) places.push([`mounted file ${v.source}`, mountedText(dir, v.source)]);
|
|
514
|
+
}
|
|
515
|
+
for (const c of s.configs ?? []) {
|
|
516
|
+
const { file: source, content } = config.configs?.[c.source] ?? {};
|
|
517
|
+
if (source) places.push([`mounted file ${source}`, mountedText(dir, source)]);
|
|
518
|
+
if (content) places.push([`config ${c.source}`, content]);
|
|
519
|
+
}
|
|
520
|
+
for (const [where, text] of places) {
|
|
521
|
+
for (const target of targets) {
|
|
522
|
+
if (shortAddress(target).test(text)) {
|
|
523
|
+
out.push(`! ${file}: service ${name} — ${where}: the short name ${target} of an env.http service may reach another task's stack; use the container name \${COMPOSE_PROJECT_NAME}-${target}-1`);
|
|
524
|
+
}
|
|
525
|
+
}
|
|
526
|
+
}
|
|
527
|
+
}
|
|
528
|
+
return out;
|
|
529
|
+
}
|
|
530
|
+
|
|
462
531
|
/** `check`: the exit code; all lines go to stdout — `check` of the installer reads them from there. */
|
|
463
532
|
function check(dir: string): number {
|
|
464
533
|
const file = COMPOSE_FILES.find((f) => existsSync(path.join(dir, f)));
|
|
@@ -476,9 +545,11 @@ function check(dir: string): number {
|
|
|
476
545
|
return notChecked("docker compose config printed no JSON");
|
|
477
546
|
}
|
|
478
547
|
const lines = violations(config, file);
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
548
|
+
// the settings are the repository's, the compose file may be in a subdirectory of it
|
|
549
|
+
const http = httpServices(git(dir, "rev-parse", "--show-toplevel") || dir);
|
|
550
|
+
const notes = typeof http === "string" ? [`○ ${http} — short names of env.http services not checked`] : shortNames(config, http, dir, file);
|
|
551
|
+
console.log([...lines, ...notes, ...(lines.length ? [] : [`${file}: the task isolation rules hold`])].join("\n"));
|
|
552
|
+
return lines.length ? 1 : 0;
|
|
482
553
|
}
|
|
483
554
|
|
|
484
555
|
// ----------------------------------------------------------------------------
|
|
@@ -643,6 +714,17 @@ export function httpServices(root: string): Record<string, number> | string {
|
|
|
643
714
|
return Object.values(ports).every((p) => Number.isInteger(p) && (p as number) > 0 && (p as number) < 65536) ? (ports as Record<string, number>) : bad;
|
|
644
715
|
}
|
|
645
716
|
|
|
717
|
+
/**
|
|
718
|
+
* What the project's stack needs of the Docker VM, MiB — `env.memoryMb` of the project's settings, a number from the
|
|
719
|
+
* project's measurement (#809, question 1); no field — undefined, a broken one — the reason.
|
|
720
|
+
*/
|
|
721
|
+
export function stackMemory(root: string): number | undefined | string {
|
|
722
|
+
const { file, fields } = manifestOf(root);
|
|
723
|
+
const memory = (fields.env as { memoryMb?: unknown } | null | undefined)?.memoryMb;
|
|
724
|
+
if (memory === undefined) return undefined;
|
|
725
|
+
return Number.isInteger(memory) && (memory as number) > 0 ? (memory as number) : `env.memoryMb of ${file}: what the stack needs of the Docker VM in MiB expected, a positive integer like 6144`;
|
|
726
|
+
}
|
|
727
|
+
|
|
646
728
|
/** Where the task's stack lives: the worktree's root, its compose files, the project's name, the task and HTTP services. */
|
|
647
729
|
interface Project {
|
|
648
730
|
root: string;
|
|
@@ -651,6 +733,8 @@ interface Project {
|
|
|
651
733
|
name: string;
|
|
652
734
|
task: number | undefined;
|
|
653
735
|
http: Record<string, number>;
|
|
736
|
+
/** `env.memoryMb`: what the stack needs of the Docker VM, MiB. */
|
|
737
|
+
memoryMb: number | undefined;
|
|
654
738
|
}
|
|
655
739
|
|
|
656
740
|
function projectOf(cwd: string, task?: number): Project | string {
|
|
@@ -660,8 +744,10 @@ function projectOf(cwd: string, task?: number): Project | string {
|
|
|
660
744
|
const extra = OVERRIDE_FILES.find((f) => existsSync(path.join(root, f)));
|
|
661
745
|
const http = httpServices(root);
|
|
662
746
|
if (typeof http === "string") return http;
|
|
747
|
+
const memoryMb = stackMemory(root);
|
|
748
|
+
if (typeof memoryMb === "string") return memoryMb;
|
|
663
749
|
const files = [file, ...(extra ? [extra] : [])].flatMap((f) => ["-f", f]);
|
|
664
|
-
return { root, files, name: projectName(root), task: task ?? taskBranch(currentBranch(root))?.issue, http };
|
|
750
|
+
return { root, files, name: projectName(root), task: task ?? taskBranch(currentBranch(root))?.issue, http, memoryMb };
|
|
665
751
|
}
|
|
666
752
|
|
|
667
753
|
/** `docker compose` in cwd; vars — over the script's environment: Compose takes them into interpolation. */
|
|
@@ -683,7 +769,8 @@ const urlVars = (project: Project, stack: Stack, env: NodeJS.ProcessEnv) =>
|
|
|
683
769
|
* services of the settings, nothing to the others (a database isn't published). The proxy's network isn't in it:
|
|
684
770
|
* Compose gives a service in each of its networks the alias of its short name, and in the proxy's network same-named
|
|
685
771
|
* services of two stacks would answer one name — a neighbour inside the stack (`http://storage:9000`) would reach
|
|
686
|
-
* another stack by chance (#700); `upStack` joins the network itself (`joinProxy`)
|
|
772
|
+
* another stack by chance (#700); `upStack` joins the network itself (`joinProxy`), which doesn't guarantee the short
|
|
773
|
+
* name either (#806, `shortNames`). The override goes to Compose's
|
|
687
774
|
* stdin (`-f -`), not into a file: a `compose.override.yaml` would be the project's. No HTTP service in the compose
|
|
688
775
|
* file — no override.
|
|
689
776
|
*/
|
|
@@ -792,11 +879,57 @@ function addressesOf(project: Project, stack: Stack, env: NodeJS.ProcessEnv): Ad
|
|
|
792
879
|
return out;
|
|
793
880
|
}
|
|
794
881
|
|
|
882
|
+
/** What a stack without `env.memoryMb` must find free on the Docker VM, MiB: below it nothing starts safely (#809). */
|
|
883
|
+
const VM_RESERVE_MB = 1024;
|
|
884
|
+
/** `docker run` of a present image takes under a second; the first run pulls it — longer than this, not checked. */
|
|
885
|
+
const VM_TIMEOUT = 30_000;
|
|
886
|
+
|
|
887
|
+
/**
|
|
888
|
+
* The Docker VM's memory in MiB: `/proc/meminfo` from a one-off container isn't namespaced, it is the VM's (the host's
|
|
889
|
+
* on Linux); `docker info` knows only the total. In the proxy's image — it is on the machine already, the version lives
|
|
890
|
+
* in its compose file. Not read — the reason.
|
|
891
|
+
*/
|
|
892
|
+
function vmMemory(env: NodeJS.ProcessEnv): { availableMb: number; swapFreeMb: number } | string {
|
|
893
|
+
const image = /^\s*image:\s*(\S+)/m.exec(readFileSync(PROXY_FILE, "utf8"))?.[1];
|
|
894
|
+
if (!image) return `no image in ${PROXY_FILE}`;
|
|
895
|
+
const r = spawnSync("docker", ["run", "--rm", "--network", "none", "--entrypoint", "cat", image, "/proc/meminfo"], { encoding: "utf8", env, timeout: VM_TIMEOUT });
|
|
896
|
+
if (r.error || r.status !== 0) return why(r);
|
|
897
|
+
const mib = (field: string) => Math.floor(Number(new RegExp(`^${field}:\\s+(\\d+) kB`, "m").exec(r.stdout)?.[1] ?? NaN) / 1024);
|
|
898
|
+
const [availableMb, swapFreeMb] = [mib("MemAvailable"), mib("SwapFree")] as [number, number];
|
|
899
|
+
return Number.isNaN(availableMb + swapFreeMb) ? "no MemAvailable or SwapFree in /proc/meminfo" : { availableMb, swapFreeMb };
|
|
900
|
+
}
|
|
901
|
+
|
|
902
|
+
/** The Compose stacks running on the VM, without the proxy: names sorted; not listed — the reason. */
|
|
903
|
+
function vmStacks(env: NodeJS.ProcessEnv): string {
|
|
904
|
+
const r = spawnSync("docker", ["ps", "--filter", `label=${PROJECT_LABEL}`, "--format", `{{.Label "${PROJECT_LABEL}"}}`], { encoding: "utf8", env, timeout: CONFIG_TIMEOUT });
|
|
905
|
+
if (r.error || r.status !== 0) return `not listed — ${why(r)}`;
|
|
906
|
+
return [...new Set(r.stdout.split("\n").filter((s) => s && s !== proxyName(env)))].sort().join(", ") || "none";
|
|
907
|
+
}
|
|
908
|
+
|
|
909
|
+
/**
|
|
910
|
+
* The gate before a stack comes up (#809): containers' limits don't protect the VM — the sum of several stacks' limits
|
|
911
|
+
* is far above it, and the kernel kills the largest process, not necessarily of the stack that gave the load. Available
|
|
912
|
+
* memory plus free swap against what the stack needs: `env.memoryMb`, without it — the reserve. A stack already running
|
|
913
|
+
* is in the VM's numbers itself, so it isn't checked. The refusal, the `○` line of a VM that didn't answer (the bring-up
|
|
914
|
+
* goes on: the gate protects neighbours, it isn't a precondition) or nothing.
|
|
915
|
+
*/
|
|
916
|
+
function vmGate(project: Project, stack: Stack, env: NodeJS.ProcessEnv): { refusal?: string; note?: string } {
|
|
917
|
+
if (containers(stack.name).some((c) => c.State === "running")) return {};
|
|
918
|
+
const vm = vmMemory(env);
|
|
919
|
+
if (typeof vm === "string") return { note: `○ Docker VM memory not checked — ${vm}${hint(vm, env)}` };
|
|
920
|
+
const need = project.memoryMb ?? VM_RESERVE_MB;
|
|
921
|
+
const has = vm.availableMb + vm.swapFreeMb;
|
|
922
|
+
if (has >= need) return {};
|
|
923
|
+
const source = project.memoryMb === undefined ? " (the reserve; env.memoryMb of .agents/elves.json sets what the stack needs)" : "";
|
|
924
|
+
return { refusal: `stack ${stack.name}: not started — the Docker VM lacks memory: needs ${need} MiB${source}, has ${has} MiB (available ${vm.availableMb} + free swap ${vm.swapFreeMb}); stacks on it: ${vmStacks(env)} — take down one nobody needs: task-env down <N>` };
|
|
925
|
+
}
|
|
926
|
+
|
|
795
927
|
/**
|
|
796
928
|
* Brings the stack up: the project's compose files plus the override, `up --wait` with a build — the stack runs the
|
|
797
|
-
* worktree's code, not an image from another task's run.
|
|
798
|
-
*
|
|
799
|
-
*
|
|
929
|
+
* worktree's code, not an image from another task's run. Before anything starts — the VM's memory (`vmGate`), inside
|
|
930
|
+
* the machine queue: two bring-ups don't count the same free memory. The proxy goes up first when the override joins its
|
|
931
|
+
* network and it isn't running (#393, question 8); a running one isn't touched. Both Compose calls get the stack's
|
|
932
|
+
* addresses for interpolation — `config` too: a required `${TASK_ENV_WEB_URL:?…}` would fail it.
|
|
800
933
|
*/
|
|
801
934
|
function upStack(project: Project, stack: Stack, profiles: string[], env: NodeJS.ProcessEnv): { code: number; lines: string[] } {
|
|
802
935
|
const vars = urlVars(project, stack, env);
|
|
@@ -806,6 +939,9 @@ function upStack(project: Project, stack: Stack, profiles: string[], env: NodeJS
|
|
|
806
939
|
const lines = Object.keys(project.http)
|
|
807
940
|
.filter((s) => !parsed.services?.[s])
|
|
808
941
|
.map((s) => `! env.http: service ${s} isn't in the compose file — no address for it`);
|
|
942
|
+
const gate = vmGate(project, stack, env);
|
|
943
|
+
if (gate.refusal) return { code: 2, lines: [...lines, gate.refusal] };
|
|
944
|
+
if (gate.note) lines.push(gate.note);
|
|
809
945
|
const override = overrideOf(parsed, project.http, stack, proxyName(env));
|
|
810
946
|
if (override) {
|
|
811
947
|
const running = proxyRunning(env);
|
|
@@ -834,39 +970,94 @@ function upStack(project: Project, stack: Stack, profiles: string[], env: NodeJS
|
|
|
834
970
|
* Takes a stack down with its volumes — by the Compose project from `/`, without the compose file: it may be gone
|
|
835
971
|
* already (`task close` after the worktree), and a compose file found by Compose would hide services of other profiles.
|
|
836
972
|
* Compose finds the stack's containers, networks and volumes by their labels — a stack left with volumes only too.
|
|
973
|
+
* withImages — the images the stack built go too (`removeImages`): `down` and `prune`; `e2e` brings its stack up anew on
|
|
974
|
+
* the same images, `up --build` rebuilds them.
|
|
837
975
|
*/
|
|
838
|
-
function downStack(stack: string, env: NodeJS.ProcessEnv): { ok: boolean;
|
|
976
|
+
function downStack(stack: string, env: NodeJS.ProcessEnv, withImages = false): { ok: boolean; lines: string[] } {
|
|
839
977
|
const r = dc(["-p", stack, "down", "--volumes", "--remove-orphans"], "/");
|
|
840
|
-
|
|
841
|
-
return { ok,
|
|
978
|
+
if (r.error || r.status !== 0) return { ok: false, lines: [`! stack ${stack}: not removed — ${why(r)}${hint(why(r), env)}`] };
|
|
979
|
+
if (!withImages) return { ok: true, lines: [`+ stack ${stack}: down, with its volumes`] };
|
|
980
|
+
const images = removeImages(stack, env);
|
|
981
|
+
const removed = images.removed.length ? ` and ${images.removed.length === 1 ? "image" : "images"} ${images.removed.join(", ")}` : "";
|
|
982
|
+
return { ok: images.ok, lines: [`+ stack ${stack}: down, with its volumes${removed}`, ...images.lines] };
|
|
842
983
|
}
|
|
843
984
|
|
|
844
|
-
/** The label Compose marks a stack's containers, volumes and networks with: the Compose project. */
|
|
985
|
+
/** The label Compose marks a stack's containers, volumes and networks with — and the images it built: the Compose project. */
|
|
845
986
|
const PROJECT_LABEL = "com.docker.compose.project";
|
|
987
|
+
|
|
988
|
+
/**
|
|
989
|
+
* Removes the images a stack built — Compose labels a built image with the stack's project (#807; Compose 5.6), a pulled
|
|
990
|
+
* one (a database, a broker, a base) has no such label and stays. A compose file may tag a built image by the stack
|
|
991
|
+
* (`image: app/web:${COMPOSE_PROJECT_NAME}` — a parallel stack's build doesn't move a machine-wide tag to another
|
|
992
|
+
* tree's code), and such an image outlives its stack: a shared tag's previous build lost its name and went by itself.
|
|
993
|
+
* By reference, `repo:tag` (a dangling one — by its ID), one by one, without `--force`: an image another container still
|
|
994
|
+
* runs on — another stack's, a test's own — stays, named by a `○` line with the containers; another failure — a `!`
|
|
995
|
+
* line. The references are sorted: the lines don't depend on Docker's order.
|
|
996
|
+
*/
|
|
997
|
+
function removeImages(stack: string, env: NodeJS.ProcessEnv): { removed: string[]; lines: string[]; ok: boolean } {
|
|
998
|
+
const label = `label=${PROJECT_LABEL}=${stack}`;
|
|
999
|
+
const list = spawnSync("docker", ["image", "ls", "--filter", label, "--format", "{{.ID}}\t{{.Repository}}:{{.Tag}}"], { encoding: "utf8", env, timeout: CONFIG_TIMEOUT });
|
|
1000
|
+
if (list.error || list.status !== 0) return { removed: [], lines: [`! images of stack ${stack}: not listed — ${why(list)}`], ok: false };
|
|
1001
|
+
const refs = new Set<string>();
|
|
1002
|
+
for (const row of list.stdout.split("\n").filter(Boolean)) {
|
|
1003
|
+
const [id, ref] = row.split("\t");
|
|
1004
|
+
refs.add(!ref || ref.includes("<none>") ? id! : ref);
|
|
1005
|
+
}
|
|
1006
|
+
const out = { removed: [] as string[], lines: [] as string[], ok: true };
|
|
1007
|
+
for (const ref of [...refs].sort()) {
|
|
1008
|
+
const r = spawnSync("docker", ["image", "rm", ref], { encoding: "utf8", env, timeout: CONFIG_TIMEOUT });
|
|
1009
|
+
if (!r.error && r.status === 0) {
|
|
1010
|
+
out.removed.push(ref);
|
|
1011
|
+
continue;
|
|
1012
|
+
}
|
|
1013
|
+
const users = spawnSync("docker", ["ps", "--all", "--filter", `ancestor=${ref}`, "--format", "{{.Names}}"], { encoding: "utf8", env, timeout: CONFIG_TIMEOUT });
|
|
1014
|
+
const names = users.status === 0 ? users.stdout.split("\n").filter(Boolean).sort() : [];
|
|
1015
|
+
if (names.length) out.lines.push(`○ image ${ref} of stack ${stack}: left — ${names.length === 1 ? "container" : "containers"} ${names.join(", ")} ${names.length === 1 ? "uses" : "use"} it`);
|
|
1016
|
+
else {
|
|
1017
|
+
out.lines.push(`! image ${ref} of stack ${stack}: not removed — ${why(r)}`);
|
|
1018
|
+
out.ok = false;
|
|
1019
|
+
}
|
|
1020
|
+
}
|
|
1021
|
+
return out;
|
|
1022
|
+
}
|
|
1023
|
+
|
|
846
1024
|
/** Compose projects on the machine → the directories of their containers; no docker — missing, Docker unavailable — the reason. */
|
|
847
1025
|
type Machine = Map<string, Set<string>> | { missing: true } | string;
|
|
848
1026
|
|
|
849
1027
|
/**
|
|
850
|
-
* Stacks on the machine — by the label of containers, volumes and
|
|
851
|
-
* containers are gone but volumes stay (`down` without `-v`, containers removed by hand) isn't in its list
|
|
852
|
-
* question 2)
|
|
853
|
-
* same name (`prune`).
|
|
1028
|
+
* Stacks on the machine — by the label of containers, volumes, networks and built images, not `docker compose ls`: a
|
|
1029
|
+
* stack whose containers are gone but volumes stay (`down` without `-v`, containers removed by hand) isn't in its list
|
|
1030
|
+
* (#395, question 2), nor one left with its built images only (taken down before #807). A container's directory
|
|
1031
|
+
* (`working_dir` — where Compose ran) tells a stack of another repository with the same name (`prune`).
|
|
854
1032
|
*/
|
|
855
1033
|
function machineStacks(env: NodeJS.ProcessEnv): Machine {
|
|
856
1034
|
const stacks = new Map<string, Set<string>>();
|
|
1035
|
+
const add = (name: string, dir = "") => {
|
|
1036
|
+
if (!name.trim()) return;
|
|
1037
|
+
const dirs = stacks.get(name.trim()) ?? new Set<string>();
|
|
1038
|
+
if (dir.trim()) dirs.add(dir.trim());
|
|
1039
|
+
stacks.set(name.trim(), dirs);
|
|
1040
|
+
};
|
|
857
1041
|
for (const list of [["ps", "--all"], ["volume", "ls"], ["network", "ls"]]) {
|
|
858
1042
|
const format = list[0] === "ps" ? `{{.Label "${PROJECT_LABEL}"}}\t{{.Label "${PROJECT_LABEL}.working_dir"}}` : `{{.Label "${PROJECT_LABEL}"}}`;
|
|
859
1043
|
const r = spawnSync("docker", [...list, "--filter", `label=${PROJECT_LABEL}`, "--format", format], { encoding: "utf8", env, timeout: CONFIG_TIMEOUT });
|
|
860
1044
|
if ((r.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") return { missing: true };
|
|
861
1045
|
if (r.error || r.status !== 0) return why(r);
|
|
862
1046
|
for (const line of r.stdout.split("\n")) {
|
|
863
|
-
const [name, dir] = line.split("\t");
|
|
864
|
-
|
|
865
|
-
const dirs = stacks.get(name.trim()) ?? new Set<string>();
|
|
866
|
-
if (dir?.trim()) dirs.add(dir.trim());
|
|
867
|
-
stacks.set(name.trim(), dirs);
|
|
1047
|
+
const [name = "", dir] = line.split("\t");
|
|
1048
|
+
add(name, dir);
|
|
868
1049
|
}
|
|
869
1050
|
}
|
|
1051
|
+
// `image ls --format` has no labels: the IDs, then `image inspect`
|
|
1052
|
+
const ids = spawnSync("docker", ["image", "ls", "--quiet", "--filter", `label=${PROJECT_LABEL}`], { encoding: "utf8", env, timeout: CONFIG_TIMEOUT });
|
|
1053
|
+
if (ids.error || ids.status !== 0) return why(ids);
|
|
1054
|
+
const unique = [...new Set(ids.stdout.split("\n").filter(Boolean))];
|
|
1055
|
+
if (unique.length) {
|
|
1056
|
+
const r = spawnSync("docker", ["image", "inspect", "--format", `{{index .Config.Labels "${PROJECT_LABEL}"}}`, ...unique], { encoding: "utf8", env, timeout: CONFIG_TIMEOUT });
|
|
1057
|
+
// an image removed between the two calls — not a failure: the others are printed
|
|
1058
|
+
if (r.error || (r.status !== 0 && !/no such image/i.test(r.stderr))) return why(r);
|
|
1059
|
+
for (const name of r.stdout.split("\n")) add(name);
|
|
1060
|
+
}
|
|
870
1061
|
return stacks;
|
|
871
1062
|
}
|
|
872
1063
|
|
|
@@ -895,7 +1086,7 @@ function stackUp(project: Project, profiles: string[], env: NodeJS.ProcessEnv):
|
|
|
895
1086
|
function stackE2e(project: Project, profiles: string[], command: string[], env: NodeJS.ProcessEnv): number {
|
|
896
1087
|
const stack = stackOf(project.name, project.task, true);
|
|
897
1088
|
const clean = downStack(stack.name, env);
|
|
898
|
-
if (!clean.ok) return console.log(clean.
|
|
1089
|
+
if (!clean.ok) return console.log(clean.lines.join("\n")), stackFailed(env, "e2e", 2, clean.lines);
|
|
899
1090
|
const r = inSlot(`e2e ${stack.name}`, () => upStack(project, stack, profiles, env));
|
|
900
1091
|
if (r.code) return console.log(r.lines.join("\n")), stackFailed(env, "e2e", r.code, r.lines);
|
|
901
1092
|
const addresses = addressesOf(project, stack, env);
|
|
@@ -908,9 +1099,10 @@ function stackE2e(project: Project, profiles: string[], command: string[], env:
|
|
|
908
1099
|
}
|
|
909
1100
|
|
|
910
1101
|
/**
|
|
911
|
-
* `down`: the task's stacks — dev and e2e — with their volumes
|
|
912
|
-
* aren't touched. A checkout without a compose file has no task stacks: Docker
|
|
913
|
-
* project calls `down`, and with Docker stopped a project without Compose would get
|
|
1102
|
+
* `down`: the task's stacks — dev and e2e — with their volumes and the images they built (`removeImages`), those that
|
|
1103
|
+
* are on the machine; stacks of other tasks aren't touched. A checkout without a compose file has no task stacks: Docker
|
|
1104
|
+
* isn't called — `task close` of every project calls `down`, and with Docker stopped a project without Compose would get
|
|
1105
|
+
* a `!` line (#395, question 4).
|
|
914
1106
|
*/
|
|
915
1107
|
function stackDown(root: string, task: number | undefined, env: NodeJS.ProcessEnv): number {
|
|
916
1108
|
if (!COMPOSE_FILES.some((f) => existsSync(path.join(root, f)))) return console.log(`○ no compose file in ${root} — the project has no task stacks`), 0;
|
|
@@ -921,8 +1113,8 @@ function stackDown(root: string, task: number | undefined, env: NodeJS.ProcessEn
|
|
|
921
1113
|
if (!(machine instanceof Map)) return console.log("○ no Docker on the machine — no task stacks"), 0;
|
|
922
1114
|
const present = stacks.filter((s) => machine.has(s));
|
|
923
1115
|
if (!present.length) return console.log(`○ stacks ${stacks.join(", ")}: none on the machine`), 0;
|
|
924
|
-
const done = present.map((s) => downStack(s, env));
|
|
925
|
-
console.log(done.
|
|
1116
|
+
const done = present.map((s) => downStack(s, env, true));
|
|
1117
|
+
console.log(done.flatMap((d) => d.lines).join("\n"));
|
|
926
1118
|
return done.every((d) => d.ok) ? 0 : 2;
|
|
927
1119
|
}
|
|
928
1120
|
|
|
@@ -955,10 +1147,11 @@ function taskState(repo: string, n: number, env: NodeJS.ProcessEnv): "open" | "c
|
|
|
955
1147
|
/**
|
|
956
1148
|
* `prune`: stacks of the project's closed tasks left on the machine — orphans: a task closed without `task close`, a
|
|
957
1149
|
* close that couldn't reach Docker, a task that removed the compose file. The stacks `<project>-<N>` and
|
|
958
|
-
* `<project>-<N>-e2e` of the machine (containers, volumes and
|
|
959
|
-
* closed — the stacks go with their volumes
|
|
960
|
-
*
|
|
961
|
-
*
|
|
1150
|
+
* `<project>-<N>-e2e` of the machine (containers, volumes, networks and built images, #395, question 2); the task's state
|
|
1151
|
+
* — by GitHub: closed — the stacks go with their volumes and built images (#807: a stack taken down before it left its
|
|
1152
|
+
* images); open, not an issue, not checked — left. A stack whose containers ran in an existing directory of another
|
|
1153
|
+
* project — another repository with the same name (`shop-2` at the project `shop`) — left (#395, question 3). Without
|
|
1154
|
+
* confirmation: a closed task's stack is nobody's (#395, question 1).
|
|
962
1155
|
*/
|
|
963
1156
|
function prune(root: string, env: NodeJS.ProcessEnv): number {
|
|
964
1157
|
const name = projectName(root);
|
|
@@ -985,8 +1178,9 @@ function prune(root: string, env: NodeJS.ProcessEnv): number {
|
|
|
985
1178
|
if (!states.has(task)) states.set(task, taskState(repo, task, env));
|
|
986
1179
|
const state = states.get(task)!;
|
|
987
1180
|
if (state === "closed") {
|
|
988
|
-
const d = downStack(stack, env);
|
|
989
|
-
|
|
1181
|
+
const d = downStack(stack, env, true);
|
|
1182
|
+
const [first = "", ...rest] = d.lines;
|
|
1183
|
+
console.log([first.startsWith("+") ? `${first} — task #${task} is closed` : first, ...rest].join("\n"));
|
|
990
1184
|
ok &&= d.ok;
|
|
991
1185
|
} else if (state === "open") console.log(`○ stack ${stack}: task #${task} is open — left`);
|
|
992
1186
|
else if (state === "missing") console.log(`○ stack ${stack}: no task #${task} in ${repo} — left`);
|