diff --git a/.changeset/test-suite-performance.md b/.changeset/test-suite-performance.md new file mode 100644 index 0000000..587d7b3 --- /dev/null +++ b/.changeset/test-suite-performance.md @@ -0,0 +1,5 @@ +--- +'@wpelevator/tug': patch +--- + +Start faster: the CLI loads only the command it runs. The CLI now takes its environment, working directory, streams and signals from one runtime object instead of the process, which lets the test suite run commands in-process and finish in less than half the time. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 94fdf80..e9578b5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,7 +31,10 @@ jobs: run: npm run typecheck - if: matrix.node == 24 run: npm run lint + # Tests start tug processes that compile the same TypeScript graph each time; a compile cache shares that work. - run: npm test + env: + NODE_COMPILE_CACHE: ${{ runner.temp }}/node-compile-cache - run: npm run test:smoke:dist integration: diff --git a/docs/architecture.md b/docs/architecture.md index 8c061a9..90d8b99 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -48,6 +48,14 @@ The [README](https://github.com/wpelevator/tug/blob/main/README.md#how-it-works) The rule is that `cli/`, `control/` and `agent/` may import domain modules and themselves but never one another, and domain modules never import a role. `cli.ts` imports no other role and `main.ts` imports no CLI code. Runtime imports (everything except `import type`) contain no cycles. `src/architecture.test.ts` enforces this, including dynamic `import()` calls, and also fails when a new top-level folder appears, so a catch-all folder cannot creep in. Unit tests sit next to the module they test; tests that span modules (`docs.examples`, `package`, `main`) stay at the top. +## The CLI runtime + +Nothing in `src/cli/` reads the process it runs in. A command receives a `CliRuntime` (`src/cli/runtime.ts`) and takes everything from it: `env`, `cwd`, `stdin`, `stdout`, `stderr`, `signals` (the process's signal and exit events), `version` and the exit code it asks for (`rt.exitCode`). Output goes through `out(rt, …)` and `err(rt, …)`, paths from the command line resolve with `resolvePath(rt, …)`, and the home directory comes from `homeDir(rt)`. Child processes (`ssh`, `scp`, `docker`, `git`) start with `rt.env` and `rt.cwd`, and their output is forwarded to the runtime's streams unless those are the real terminal. + +What a run remembers (`--verbose`, whether work has started, the resolved configuration, the controls whose version was already checked, the running progress display) is `rt.state`, created with the runtime. No module keeps state between runs, so one process can run any number of commands, one after another or at the same time, and a run never has to be reset. + +`src/cli.ts` builds the runtime of the real process (`processRuntime`) and calls `runCli(argv, rt)` from `src/cli/program.ts`, which builds the command tree for that run, loads only the module of the command the arguments name and returns the exit code. A test builds a runtime from plain objects (`tests/cli-runtime.ts`) and calls the same function, so it exercises the real parser and handlers without a child process and without patching a global. ESLint rejects `process`, `console` and `os.homedir` in `src/cli/` outside `runtime.ts`, so the boundary holds as the CLI grows. Shared domain modules (`images/`, `compose/`, `transport.ts`) take an explicit `env` or version where the CLI passes one and otherwise default to the process, because the control plane and the agent use them too. Time (`Date.now`) and the temporary directory are not part of the boundary. + ## Desired state and reconciliation `tug deploy` sends the Compose file to control, which validates `x-tug` placement (see [Compose extensions](compose.md)), optionally builds images for services with `build:`, and stores an immutable desired-state record for the deployment. Each agent receives the desired states that place services on its node, applies them, and reports the observed display version, immutable desired-state revision and health per project. When every assigned node reports the current revision as `serving` (or `skipped`), control also waits for every enabled managed-ingress node to report the current routing configuration as applied when the project adds, changes or removes ingress routes. The acknowledged configuration must contain each current project route with a serving upstream, or marked `maintenance`, which is routed with no upstream on purpose; a failed, stale or older ingress report cannot complete deployment. With no enabled ingress node, convergence reports service health only. This acknowledgement confirms the agent applied its Caddy configuration, not external DNS, certificate issuance or a successful public request. A failed node report still fails the deployment with its apply and rollout errors; an unavailable ingress can leave the deployment `rolling_out` until it recovers or the CLI times out. diff --git a/docs/design-records.md b/docs/design-records.md index 3755a4a..1e77243 100644 --- a/docs/design-records.md +++ b/docs/design-records.md @@ -16,4 +16,5 @@ These pages record why tug is built the way it is and what is planned. They are | [Standalone binary](standalone-binary.md) | Prototyped | A compiled client without Node.js | | [tug compared with Docker Swarm](swarm-comparison.md) | Record | A dated source assessment of overlap and gaps, with evidence | | [Terminal UI design](tui-design.md) | Phases 1 to 3 built | User flows, screen design, architecture and the remaining phases of `tug tui` | +| [Test suite performance](test-performance.md) | Record | Where the 2 minute 49 second `npm test` run went and what cut it to about 77 seconds | | [Terminology review](terminology-review.md) | Record | The 1 November 2026 naming review behind the vocabulary | diff --git a/docs/real-host-evaluation.md b/docs/real-host-evaluation.md index a10378d..3270e28 100644 --- a/docs/real-host-evaluation.md +++ b/docs/real-host-evaluation.md @@ -244,7 +244,7 @@ A partial run of the [Road to 1.0.0](roadmap.md#road-to-100) gate on two fresh U | `tug node add --name ` on an enrolled host | Refused with ``use `tug node replace app1` ``, nothing registered, no stack trace | | `tug node replace` | Still rotates the key (key hash changed), node back online | -**Finding, fixed.** `agent identity` built its CSR from the pending key file only, so re-running `tug node add` on an enrolled host sent a new key, which control rightly refused, although [Nodes](nodes.md#image) promised an in-place upgrade. `agent identity --current ` now reuses the installed key when the host is enrolled as that node and refuses another name; `node add` asks for it and `node replace` and `node repair` still rotate the key. Covered by `src/agent/credential.test.ts` (reuse, rotation, refusal, fresh host), `src/cli/commands/node.test.ts` (the arguments per mode) and `src/main.test.ts` (the plain error through the real entrypoint), and re-verified on the VMs with a rebuilt candidate. +**Finding, fixed.** `agent identity` built its CSR from the pending key file only, so re-running `tug node add` on an enrolled host sent a new key, which control rightly refused, although [Nodes](nodes.md#image) promised an in-place upgrade. `agent identity --current ` now reuses the installed key when the host is enrolled as that node and refuses another name; `node add` asks for it and `node replace` and `node repair` still rotate the key. Covered by `src/agent/credential.test.ts` (reuse, rotation, refusal, fresh host), `src/cli/commands/node.test.ts` (the arguments per mode) and `src/main.process.test.ts` (the plain error through the real entrypoint), and re-verified on the VMs with a rebuilt candidate. **Observations, fixed afterwards.** `tug node replace` and `tug node repair` now accept `-y` like `tug node add` (they never ask, and `--all` still needs the nodes declared in `tug.yml`). `--build-local-image` now runs the build on the host under `-` (for example `tug:local-a17ed756592c`) as well as `tug:local`, so rebuilding `tug:local` no longer leaves the running control or agent container showing an image ID. diff --git a/docs/standalone-binary.md b/docs/standalone-binary.md index be96db3..64200f2 100644 --- a/docs/standalone-binary.md +++ b/docs/standalone-binary.md @@ -110,7 +110,7 @@ Review the remaining runtime behavior under Bun: asynchronous child processes fo - Add `tools/scripts/build-binary.js` (Node, per project convention) that runs `bun build --compile tools/binary/entry.ts` for each target, writes `dist-bin/tug--`, and packs each into a `.tar.gz` with a `.sha256` file. - Add an `npm run build:binary` script that calls it. Bun is a build-time dependency only, installed in CI with `oven-sh/setup-bun` and not added to `package.json`. -- Extend the smoke test (`test:smoke:dist` already runs `src/cli/templates.test.ts` against `CLI_ENTRY`) so `CLI_ENTRY` can point at the native binary and assert `tug --version`, that every template renders, and that an mTLS request through a local test control succeeds with the pinned CA and connect-target override (the checks of `verify-mtls-runtime.js`). +- Extend the smoke test (`test:smoke:dist` already runs `src/cli/templates.process.test.ts` against `CLI_ENTRY`) so `CLI_ENTRY` can point at the native binary and assert `tug --version`, that every template renders, and that an mTLS request through a local test control succeeds with the pinned CA and connect-target override (the checks of `verify-mtls-runtime.js`). - CI runs the smoke test on the host-native binary for linux x64 and macOS arm64. The other targets are cross-compiled only. ## Release and Homebrew diff --git a/docs/test-performance.md b/docs/test-performance.md new file mode 100644 index 0000000..3b6792f --- /dev/null +++ b/docs/test-performance.md @@ -0,0 +1,109 @@ +# Test suite performance + +Status: Record. The first proposal is built; measured on 17 November 2026 on a 4-core Linux container with Node.js 22.23.4. + +`npm test` took 2 minutes 49 seconds there and about 8.5 minutes of CPU before the change described under [Result](#result), and takes about 77 seconds after it (70 seconds with `--test-concurrency` set to the core count). This page records where the time went and what changed. The numbers are from runs on that machine, so treat them as ratios, not as promises for other hardware. I did not measure earlier releases, so this page cannot say which change made the suite slow. + +## What the run is made of + +| Measure | Value | How it was taken | +| --- | --- | --- | +| Wall time, `npm test` | 2 min 49 s | `time node --test 'src/**/*.test.ts' tools/scripts/check-reachability.test.mjs` | +| CPU time (user) | 8 min 35 s | Same run | +| Test files | 152 | `find src tools/scripts -name '*.test.*'` | +| Test cases | 1,175 | JUnit reporter | +| Sum of case durations | 454 s | JUnit reporter | +| CLI processes started | 467 | A `--import` preload that logs every process whose entry is `cli.ts` or `cli.js` | +| Cost of one `node src/cli.ts --version` | about 0.45 to 0.5 s wall, 0.8 s CPU | `time`, repeated | +| Cost of bare `node -e 0` | 0.03 s | `time` | + +The suite is not slow because of many tests or slow logic. It is slow because tests start the CLI as a child process 467 times, and each start costs about 15 times a bare Node.js start. + +At 0.8 s of CPU each, those starts account for up to about 370 s of the 515 s of CPU, which is most of it. The slowest cases are matrix tests that run the CLI once per argument set: + +| Case | Seconds | File | +| --- | --- | --- | +| CLI selections mutate only chosen resources | 36.9 | `src/cli/cli.selection.process.test.ts` | +| Token commands reject malformed invocations | 28.9 | `src/cli/credentials.test.ts` | +| Credential create, list and revoke | 25.5 | `src/cli/credentials.test.ts` | +| Deploy refuses a `--var` that is a secret | 23.9 | `src/cli/commands/var.test.ts` | +| Every config key applies to every command that has its option | 22.2 | `src/cli/config.test.ts` | +| Every command that produces a result accepts `--json` | 20.1 | `src/cli/json-option.test.ts` | + +Those durations were taken with the 4 cores busy, so they are inflated. `src/cli/credentials.test.ts` alone, with nothing else running, takes 18 s for 4 test cases. + +The eleven slowest files are all CLI tests: `credentials`, `cli.selection`, `templates`, `ssh-hostkey`, `config`, `var`, `json-option`, `wait-progress`, `cli`, `upgrade` and `stdin`. `src/control/live-flow.test.ts` is the only non-CLI file near the top, and it also drives the CLI. + +## Why one CLI start is slow + +`src/cli.ts` imports every command module at the top (`registerBackup`, `registerDeploy`, `registerNode` and about twenty more), so `tug --help` loads the control client, mTLS, YAML, tar and the rest. + +A CPU profile of `node src/cli.ts --version` shows the time in module loading and in Node.js stripping TypeScript types on every start, not in tug code: the amaro transform, WebAssembly compilation and the ESM loader. + +| Entry point | Start time | +| --- | --- | +| `node src/cli.ts --version` | 0.45 to 0.5 s | +| `node dist/cli.js --version` (built) | 0.33 to 0.4 s | +| `node dist/cli.js` with `NODE_COMPILE_CACHE` warm | 0.25 to 0.27 s | +| `node src/cli.ts` with `NODE_COMPILE_CACHE` warm | 0.39 to 0.41 s | + +The build takes 5.7 s. Building and caching alone roughly halves the start cost but still leaves about 0.25 s per spawn, so it is not enough by itself. + +`src/cli.ts` calls `program.parseAsync()` at the top level, so there is no function a test can call without starting a process. + +## Result + +Built, in this order: + +1. The CLI reaches its process only through a `CliRuntime` (env, cwd, streams, signals, exit code and per-run state; see [the CLI runtime](architecture.md#the-cli-runtime)), and `runCli(argv, rt)` in `src/cli/program.ts` builds the command tree for one run and returns the exit code. `src/cli.ts` is a three-line entry. ESLint rejects `process`, `console` and `os.homedir` in `src/cli/` outside `runtime.ts`. +2. The program loads only the module of the command named on the command line (`REGISTRARS`), and everything for `--help`, `--version` and unknown names; the root options that decide where the command name is come from the program itself. `tug credential list` starts in about 0.34 s instead of 0.45 s. `src/cli/program.test.ts` checks that the table matches `tug --help`. +3. `tests/cli-inprocess.ts` provides `execCli`, which builds a `testRuntime` (`tests/cli-runtime.ts`) for each call, so nothing global is patched and calls overlap safely, and 17 test files moved from `exec(process.execPath, [entry, …])` to it. The matrix tests (`credentials`, `json-option`, `config`, `var`, the argument cases of `cli.selection`) now take about a second each, down from 18 to 46 seconds. +4. CI sets `NODE_COMPILE_CACHE` on the test step, so the processes that remain compile the module graph once. Locally, export it to get the same (for example `NODE_COMPILE_CACHE="$TMPDIR/tug-compile-cache" npm test`). +5. Test files that start real tug processes are named `*.process.test.ts`, import their entry points from `tests/cli-process.ts`, and are guarded by `src/test-layout.test.ts` (see [fast and process test files](testing.md#fast-and-process-test-files)). + +| Measure | Before | After | +| --- | --- | --- | +| Wall time, `npm test` | 2 min 49 s | about 77 s (70 s with `--test-concurrency=4`) | +| CPU time (user) | 8 min 35 s | 3 min 22 s | +| CLI processes started | 467 | 106 | +| Test cases | 1,175 | 1,192 (new ones for `runCli`, the runtime, `execCli`, the ESLint boundary and the layout guard) | + +The 106 that remain need a real process: the interactive selection and prompt tests (a fake terminal and keystrokes), whole-document stdin and `secret set` (exit while stdin stays open), the 100 MB streaming tests, and the `dist` and templates smoke tests. `wait-progress` is not among them: it runs in-process and takes about 14 s because it waits on real timers. + +A `pretest` build step and an `npm test` / `npm run test:cli` split were not built. After the move, the processes that remain are mostly terminal and stream tests that run against `src`, so a built entry would save about 0.15 s on about a hundred starts, and the suite is already under the 90 second target. Revisit when it grows past that. + +## Fast and process files + +`node:test` has no tags. It can run files in parallel (`--test-concurrency`), split a run across machines (`--test-shard`) and filter by test name (`--test-name-pattern`, `--test-skip-pattern`), and it runs the tests inside one file one after another. Parallelism is therefore per file, and the wall time is bounded by the larger of the longest file and the total CPU time divided by the cores. + +Measured serially and uncontended on the 4-core container, the 153 test files that existed then add up to 224 s, so 4 cores cannot go below about 56 s. The longest file alone is 21.5 s (`src/control/live-flow.test.ts`), then `cli.selection` (18.3 s), `templates` (14.7 s) and `wait-progress` (13.6 s, in-process but waiting on real timers). + +| Kind | Files | Serial time | How it is selected | +| --- | --- | --- | --- | +| Fast: unit and in-process service tests | 144 (145 now) | 167 s | `*.test.ts` | +| Process: starts real tug processes | 9 | 57 s | `*.process.test.ts`, `npm run test:process` | + +`npm test` runs both. With plain `node --test` the process files alone take 28 s wall, and node cannot exclude a glob, so there is no fast-only script: the kind is a file name that tools and a reader can use (`ls src/**/*.process.test.ts`). + +Concurrency, whole suite, compile cache warm: + +| `--test-concurrency` | Wall time | +| --- | --- | +| 2 | 109 s | +| 3 (node's default here: cores minus one) | 87 s | +| 4 (the core count) | 70 s | +| 8 | 68 s | + +Matching the concurrency to the core count is worth about 20 % on this machine, and more than that gains nothing. Node's default leaves a core idle, and the setting is machine-specific, so it is not hard-coded in `npm test`: pass `--test-concurrency=$(nproc)` locally when it matters. Running the longest files first and sharding across CI jobs were considered and left out: the first needs a cache of timings that goes stale, and the second adds jobs to save about 20 s. + +## Keeping it fast + +The cause of the slow suite was a habit, not a defect: the cheapest way to write a CLI test was to copy a neighbour and spawn the process. Three things keep it from coming back: + +- The cheap way is the default. `execCli` (`tests/cli-inprocess.ts`) is what a test reaches for, and `startMtlsControl` gives it a real control in the same process. The runtime boundary is what makes that safe: the CLI cannot read a global, so a test never has to patch one. +- The expensive way is named and fenced. A test that needs a terminal, piped stdin, signals or the built entry goes in a `*.process.test.ts` file and imports `cliEntry` or `mainEntry` from `tests/cli-process.ts`. `src/test-layout.test.ts` fails when a fast file imports that helper or names the entry path, and when a process file starts no process. +- The numbers are in the log. A reader can compare against the table above: the suite at 1,192 test cases takes about 77 s on 4 cores, with 106 CLI starts in the whole run. + +## Next candidates + +Each of the slowest files is dominated by a few real-process, large-transfer or real-timer cases. Cutting further means shrinking the 100 MB transfers, injecting a clock into the long-wait tests, or sharing one control between cases. diff --git a/docs/testing.md b/docs/testing.md index 45d1773..498c006 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -20,7 +20,7 @@ Managed-ingress convergence tests exercise current and outdated configuration ha |---|---|---| | The runtime image shipped without the Compose plugin, so every real deploy failed (the former runtime ran Compose on nodes; agents now use the Docker Engine API and the plugin is no longer part of the image) | Real hosts | Tier 2: `npm run test:smoke:image` runs the shipped image's binaries, database code and mTLS dependencies without any host plugins, on Alpine | | `deploy --build-local` was rejected on containerd image stores, where `docker save` lists a build attestation as an extra top-level entry | Local integration run on Docker Desktop | Tier 1: `src/images/artifacts.test.ts` builds synthetic archives, including the rejected variants | -| `secret set` printed success but stayed running with stdin open; auditing prompts also found stale readline listeners that echoed later hidden answers | CLI bug report and subprocess reproduction | Tier 1: `src/cli/commands/secret.test.ts` and `src/cli/prompt.test.ts` check exit with open input, listener cleanup, hidden answers and EOF errors | +| `secret set` printed success but stayed running with stdin open; auditing prompts also found stale readline listeners that echoed later hidden answers | CLI bug report and subprocess reproduction | Tier 1: `src/cli/commands/secret.process.test.ts` and `src/cli/prompt.process.test.ts` check exit with open input, listener cleanup, hidden answers and EOF errors | | `tug run` lost the start of a command's output: the one-off container's logs were attached after it started with the default 100-line tail, and with flow control a fixed 1.5 s drain cap would also have cut the end | Local integration run on Docker Desktop | Tier 2: `tests/integration/live-exec-flow.test.ts` (8 MB through `tug run` to a slow reader) | | The first rolling deploy started two revisions of the same image | Real hosts | Not guarded yet, see backlog item 1 | | Backup recipes in `docs/backups.md` used a single `$` in `restore:`, which `tug deploy` 3.0 rejects as an unset value | Real hosts, 15 November 2026 | The recipes use `$$`. Tier 1: `src/docs.snippets.test.ts` runs the `findMissingValues` check of `tug deploy` over every Compose snippet in `README.md` and `docs/` and every Compose file in `examples/`, and found the same mistake in `docs/compose.md` | @@ -31,13 +31,18 @@ Managed-ingress convergence tests exercise current and outdated configuration ha ### Conventions that exist -- **Control** runs in-process on a random port with a temporary data directory and real SQLite, so tests exercise the HTTP API without Docker. Agent endpoints are driven directly, with the test acting as the agent (`src/control/rollback.test.ts`, `src/control/network.test.ts`). These in-process tests skip TLS: a test identity shim (`tests/helpers.ts`) supplies the principal a certificate would, and it still resolves against the database. Real certificates, handshakes, key authorization, enrollment, renewal and node IDs are covered by `src/pki.test.ts` and `src/control/mtls.test.ts`, and by the subprocess CLI tests that start a real mTLS control (`startMtlsControl`). +- **Control** runs in-process on a random port with a temporary data directory and real SQLite, so tests exercise the HTTP API without Docker. Agent endpoints are driven directly, with the test acting as the agent (`src/control/rollback.test.ts`, `src/control/network.test.ts`). These in-process tests skip TLS: a test identity shim (`tests/helpers.ts`) supplies the principal a certificate would, and it still resolves against the database. Real certificates, handshakes, key authorization, enrollment, renewal and node IDs are covered by `src/pki.test.ts` and `src/control/mtls.test.ts`, and by the CLI tests that start a real mTLS control (`startMtlsControl`). - **The agent** takes its Docker Engine API client (`DockerApi`; the in-memory Engine in `tests/fake-docker.ts`) and HTTP client as injectable dependencies, so tests assert the exact Engine calls issued for a reconcile (`src/agent/agent.test.ts`, `src/agent/images.test.ts`, `src/agent/network.test.ts`). - **Shell scripts** are tested by running the generated text against fake executables placed first on `PATH`, instead of asserting on strings (`src/cli/install.test.ts`). - **Image archives** are built in the test, so malformed and hostile layouts can be checked without Docker (`src/images/artifacts.test.ts`). -- **The CLI** is run against a stub `ssh` that records its arguments (`src/cli/templates.test.ts`). Tests that run the install commands also put a stub `docker` first on the PATH (`writeStubDocker` in `tests/helpers.ts`) that answers `manifest inspect` as published and passes everything else to the real Docker: the commit that cuts a release runs CI before its image exists, and a test must not depend on the registry. Subprocess exit tests leave stdin open after secret entry, repeated visible/hidden prompts, prompted command failure, HTTP responses, and interactive exec success, nonzero exit, remote error, disconnect and SIGINT cancellation (`src/cli/commands/secret.test.ts`, `src/cli/prompt.test.ts`, `src/cli/stdin.test.ts`, `src/cli/live-transport.test.ts`). Each subprocess has a 60 second deadline so a leaked handle fails the test. The deadline catches a hang and is not a speed check: a 5 or 10 second one failed `secret set`, `var set` and `ps` runs on CI runners that start a dozen Node processes at once, and 60 seconds still fails a hang within the job's budget. A timer-based test that needs a state to last or to end (a rolling `drain`) states both sides with a margin of hundreds of milliseconds, not tens, since a runner can pause for longer than a short drain between two calls. Whole-document readers (`init -`, `node register --csr -`, backup destination credentials and runtime `agent install-cert`) receive EOF and must then exit; they intentionally wait for the complete document before producing a result. +- **The CLI runs in-process.** The CLI reaches its process only through a `CliRuntime` ([architecture](architecture.md#the-cli-runtime)), so `execCli` in `tests/cli-inprocess.ts` builds one from plain objects (`testRuntime` in `tests/cli-runtime.ts`: the environment, working directory, stdin, streams and signals of that one call), runs the real `runCli` and resolves or rejects like a promisified `execFile` (`code`, `stdout`, `stderr`). Nothing global is patched, so calls may overlap and a test cannot leak its environment into the next. Every call has a 60 second deadline, as a child process had, so a hang fails the test. A node process costs about half a second to start, so parsing, help, `--json`, config and API tests use `execCli`; a test of one helper (`runStep`, `createProgress`, `importCredential`) builds a `testRuntime` and passes `rt` to it. Start a real process only for what in-process cannot show: a terminal (`--import` with a fake TTY), signals, a command that must exit while stdin stays open, and the built `dist` entry. CI sets `NODE_COMPILE_CACHE` for `npm test` so the processes that remain compile the module graph once; export it locally for the same effect. +- **The CLI** is run against a stub `ssh` that records its arguments (`src/cli/templates.process.test.ts`). Tests that run the install commands also put a stub `docker` first on the PATH (`writeStubDocker` in `tests/helpers.ts`) that answers `manifest inspect` as published and passes everything else to the real Docker: the commit that cuts a release runs CI before its image exists, and a test must not depend on the registry. Subprocess exit tests leave stdin open after secret entry, repeated visible/hidden prompts, prompted command failure, HTTP responses, and interactive exec success, nonzero exit, remote error, disconnect and SIGINT cancellation (`src/cli/commands/secret.process.test.ts`, `src/cli/prompt.process.test.ts`, `src/cli/stdin.process.test.ts`, `src/cli/live-transport.process.test.ts`). Each subprocess has a 60 second deadline so a leaked handle fails the test. The deadline catches a hang and is not a speed check: a 5 or 10 second one failed `secret set`, `var set` and `ps` runs on CI runners that start a dozen Node processes at once, and 60 seconds still fails a hang within the job's budget. A timer-based test that needs a state to last or to end (a rolling `drain`) states both sides with a margin of hundreds of milliseconds, not tens, since a runner can pause for longer than a short drain between two calls. Whole-document readers (`init -`, `node register --csr -`, backup destination credentials and runtime `agent install-cert`) receive EOF and must then exit; they intentionally wait for the complete document before producing a result. - **Waiting** for something asynchronous uses `until(condition, what)` from `tests/wait.ts`, never a fixed sleep followed by an assertion. A sleep is a guess about machine speed, and CI runners that run test files in parallel are slower than a laptop at unpredictable moments, so a guess that passes locally fails there now and then (the flakes in the job runner, the stuck control backup and the TUI poller were all this). `until` polls with a generous deadline that a passing test never pays for and fails naming what it waited for. Do not assert how many times a timer fired in a fixed window; wait for the count you need, or compare two rates over the same elapsed time. A fixed sleep is still right to show that something does *not* happen, after waiting for the last positive signal. +### Fast and process test files + +A file named `*.process.test.ts` starts real tug processes and is a process file (`npm run test:process`); every other `*.test.ts` file is fast. Process files import `cliEntry` and `mainEntry` from `tests/cli-process.ts`, and `src/test-layout.test.ts` fails on a fast file that does, on one that hard-codes the entry path, and on a process file that starts no process. `node:test` has no tags and parallelizes per file, so a file name is the one marker that survives. `--test-concurrency=$(nproc)` is about 20 % faster than node's default of one fewer than the cores. + ### SQLite contract and blocking measurements `src/db/db.test.ts` runs the reusable factory-driven suite in `tests/db-contract.ts` against the Node adapter. It checks bindings and injection resistance, NULL and missing rows, ordinary object results, numeric change counts, integer boundaries, classified errors, transactions, busy waits, read-only/no-create behavior and connection cleanup. Shared-policy tests cover schemas, persisted agent state, foreign keys, WAL and the 1,000 ms timeout. A future Bun adapter must pass the same suite before it can replace the Node adapter. diff --git a/docs/tui-design.md b/docs/tui-design.md index 5336a20..0868273 100644 --- a/docs/tui-design.md +++ b/docs/tui-design.md @@ -260,7 +260,7 @@ Per [Testing](testing.md), with assertion messages that state the expected behav - `actions.test.ts`, `poller.test.ts`, `format.test.ts`, `once.test.ts`: the request each action sends, a failed poll keeping data, 403 turning an admin feed off, timers cleaned on stop, `sanitize`, ages and the exit rule. - `app.test.ts`: the whole runtime on fake terminal streams, a fake API and a fake live transport: alternate screen entered and restored, quit and `ctrl-c`, no redraw when idle, logs reassembled and sanitized and the session closed with the screen, inspect, `R` then `y` and `n`, read-only, a dropped control, and the shell hand-over and return. - `screen.test.ts`: the same runtime with its output fed into a real terminal emulator (`@xterm/headless`, a dev dependency), so the checks are on what a terminal shows after applying the escape sequences: the alternate screen is used, many incremental updates leave exactly what a clear-and-redraw shows, a closed log screen leaves nothing behind, a resize redraws at the new size, the shell gets the normal screen and the overview returns, and quitting leaves the normal screen clean. `tests/tui-harness.ts` holds the fake terminal, API and live transport that `app.test.ts` and `screen.test.ts` share. -- `cli.tui.test.ts`: the real command against an mTLS control: `--once`, `--json` with the role and version from `whoami`, no terminal, an unknown view and an unreachable control. `credentials.test.ts` covers `whoami` and the role matrix. +- `cli.tui.process.test.ts`: the real command against an mTLS control: `--once`, `--json` with the role and version from `whoami`, no terminal, an unknown view and an unreachable control. `credentials.test.ts` covers `whoami` and the role matrix. Not covered by automated tests: a full run against a live agent with a real container (the log, inspect and shell paths are tested against the live transport interface, and `runCliLive` has its own suite), and rendering in specific terminal emulators beyond xterm.js (a pseudo-terminal run of the real command was done by hand, not in the suite). diff --git a/eslint.config.js b/eslint.config.js index b649766..feb15b6 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -28,6 +28,73 @@ export default [ 'no-else-return': 'warn', }, }, + { + // The CLI reaches its process only through the CliRuntime it is given (src/cli/runtime.ts), so any command runs + // in-process under a test runtime without patching a global. Take env, cwd, streams, signals and the exit code + // from `rt`; docs/architecture.md#the-cli-runtime says how. + files: ['src/cli/**/*.ts'], + ignores: ['src/cli/**/*.test.ts', 'src/cli/runtime.ts'], + rules: { + 'no-restricted-globals': [ + 'error', + { + name: 'process', + message: + 'Use the CliRuntime (rt.env, rt.cwd, rt.stdin, rt.stdout, rt.stderr, rt.signals, rt.exitCode) instead of the process.', + }, + { + name: 'console', + message: + 'Write through the CliRuntime: out(rt, ...) for stdout, err(rt, ...) for stderr.', + }, + ], + 'no-restricted-properties': [ + 'error', + { + object: 'os', + property: 'homedir', + message: 'Use homeDir(rt), which honours the runtime environment.', + }, + { + object: 'globalThis', + property: 'process', + message: 'Use the CliRuntime instead of reaching the process through globalThis.', + }, + { + object: 'globalThis', + property: 'console', + message: + 'Write through the CliRuntime: out(rt, ...) for stdout, err(rt, ...) for stderr.', + }, + ], + 'no-restricted-imports': [ + 'error', + { + paths: [ + { + name: 'node:process', + message: 'Use the CliRuntime instead of importing the process.', + }, + { name: 'process', message: 'Use the CliRuntime instead of importing the process.' }, + { + name: 'node:console', + message: 'Write through the CliRuntime: out(rt, ...) and err(rt, ...).', + }, + { + name: 'node:os', + importNames: ['homedir'], + message: 'Use homeDir(rt), which honours the runtime environment.', + }, + { + name: 'os', + importNames: ['homedir'], + message: 'Use homeDir(rt), which honours the runtime environment.', + }, + ], + }, + ], + }, + }, { files: ['tests/**/*.ts', 'src/**/*.test.ts'], languageOptions: { diff --git a/package.json b/package.json index ad95196..154cd12 100644 --- a/package.json +++ b/package.json @@ -29,6 +29,7 @@ "schema": "node tools/scripts/write-x-tug-schema.js", "prepack": "npm run build", "test": "node --test 'src/**/*.test.ts' tools/scripts/check-reachability.test.mjs", + "test:process": "node --test 'src/**/*.process.test.ts'", "lint": "eslint . && prettier --check .", "format": "prettier --write . && eslint . --fix", "test:integration": "bash tools/scripts/integration-test.sh", @@ -36,7 +37,7 @@ "test:integration:agent": "node --test 'tests/integration/**/*.test.ts'", "test:integration:ingress": "node --test tests/integration/ingress-resilience.test.ts", "test:integration:backups": "node --test tests/integration/backup-job.test.ts tests/integration/run-job.test.ts", - "test:smoke:dist": "npm run build && CLI_ENTRY=dist/cli.js node --test src/cli/templates.test.ts", + "test:smoke:dist": "npm run build && CLI_ENTRY=dist/cli.js node --test src/cli/templates.process.test.ts", "changeset": "changeset", "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts", "release": "changeset publish", diff --git a/src/cli.ts b/src/cli.ts index ed91ea1..33961ba 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -1,193 +1,4 @@ #!/usr/bin/env node -import { Command } from 'commander'; -import { - applyConfigDefaults, - commandPath, - integerOption, - nodeSettings, - resolveCliConfig, -} from './cli/config.ts'; -import { CliLiveError } from './cli/live.ts'; -import { setVerbose } from './cli/process.ts'; -import { isUsageError } from './cli/usage.ts'; -import { addJsonOption } from './cli/json-option.ts'; -import { CREDENTIAL_NAME_PATTERN, PROJECT_NAME_PATTERN } from './roles.ts'; -import { packageVersion } from './images/image.ts'; -import { errMessage } from './errors.ts'; -import { CONFIG_HELP, setResolvedConfig } from './cli/commands/context.ts'; -import { registerBackup } from './cli/commands/backup.ts'; -import { registerControl } from './cli/commands/control.ts'; -import { registerUpgrade } from './cli/commands/upgrade.ts'; -import { registerCredential } from './cli/commands/credential.ts'; -import { registerDeploy } from './cli/commands/deploy.ts'; -import { registerInit } from './cli/commands/init.ts'; -import { registerNode } from './cli/commands/node.ts'; -import { registerObserve } from './cli/commands/observe.ts'; -import { registerRestore } from './cli/commands/restore.ts'; -import { registerHold } from './cli/commands/hold.ts'; -import { registerImage } from './cli/commands/image.ts'; -import { registerLint } from './cli/commands/lint.ts'; -import { registerDomain } from './cli/commands/domain.ts'; -import { registerIngress } from './cli/commands/ingress.ts'; -import { registerSecret } from './cli/commands/secret.ts'; -import { registerVar } from './cli/commands/var.ts'; -import { registerService } from './cli/commands/service.ts'; -import { registerTui } from './cli/commands/tui.ts'; -import { registerVolume } from './cli/commands/volume.ts'; +import { runCli } from './cli/program.ts'; -const VERBOSE_HELP = - 'show the output of quiet steps, such as Docker pulls and installers on a remote host (also TUG_VERBOSE=1)'; -const program = new Command(); -program - .name('tug') - .description('Deploy Docker Compose applications to your own servers') - .version(packageVersion()) - .enablePositionalOptions() - .option('--config ', CONFIG_HELP) - .option( - '--control-url ', - 'connect target for the control API (the credential still verifies its own public URL)', - ) - .option( - '--credential ', - 'credential file (overrides TUG_CREDENTIAL, TUG_CREDENTIAL_FILE and config)', - ) - .option('--project ', 'project (overrides TUG_PROJECT and config; default: site)') - .option('--verbose', VERBOSE_HELP); - -registerInit(program); -registerControl(program); -registerUpgrade(program); -registerNode(program); -registerDeploy(program); -registerObserve(program); -registerTui(program); -registerService(program); -registerHold(program); -registerImage(program); -registerLint(program); -registerSecret(program); -registerVar(program); -registerDomain(program); -registerIngress(program); -registerBackup(program); -registerRestore(program); -registerCredential(program); -registerVolume(program); - -/** Commands that may create the config file, so a selected file need not exist yet. */ -const CREATES_CONFIG = ['init', 'control setup']; -const NODE_NAME_FROM_ARGUMENT = ['node register', 'node replace', 'node repair', 'node upgrade']; -const NODE_NAME_FROM_OPTION = ['node add', 'node enroll']; - -program.hook('preAction', async (_root, command) => { - const path = commandPath(command); - const options = command.opts(); - for (const [key, min, max] of [ - ['port', 1, 65535], - ['timeout', 1, 86400], - ['ttl', 1, 31536000], - ['uses', 1, 1000000], - ['expiresInDays', 1, 3650], - ['limit', 1, 500], - ['tail', 0, 1000000], - ] as const) { - if (options[key] !== undefined) - integerOption( - String(options[key]), - '--' + key.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase()), - min, - max, - ); - } - if (path === 'control restore' && options.snapshot && !options.fromDestination) - throw new Error('--snapshot goes with --from-destination'); - if (path === 'control restore' && options.passwordStdin && !options.fromDestination) - throw new Error('--password-stdin goes with --from-destination'); - const positional = path === 'exec' ? command.args.slice(0, 1) : command.args; - for (const value of [...positional, ...Object.values(options), ...Object.values(program.opts())]) - if (typeof value === 'string' && /[\r\n\0]/.test(value)) - throw new Error('arguments and option values must not contain line breaks or NUL'); - if (path === 'exec' && command.args.slice(1).some((value) => value.includes('\0'))) - throw new Error('exec command arguments must not contain NUL'); - if (options.name && !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(options.name)) - throw new Error('--name must contain only letters, numbers, dots, underscores or hyphens'); - const connection = command.optsWithGlobals(); - if (connection.verbose) setVerbose(true); - if (path === 'credential create') { - // --project is repeatable here and scopes the new credential, so it must not also select the connection project. - if (!CREDENTIAL_NAME_PATTERN.test(command.args[0])) - throw new Error( - 'credential name must be 1-64 letters, numbers, dots, underscores or hyphens, starting with a letter or number', - ); - for (const project of options.project as string[]) - if (!PROJECT_NAME_PATTERN.test(project)) - throw new Error( - '--project must contain only letters, numbers, dots, underscores or hyphens', - ); - if (options.role === 'admin' && options.project.length) - throw new Error( - 'admin credentials cannot be limited to projects; use --role read or --role deploy with --project', - ); - connection.project = undefined; - } - const resolved = await resolveCliConfig( - connection, - process.env, - process.cwd(), - CREATES_CONFIG.includes(path), - ); - setResolvedConfig(resolved); - // Config values are defaults for options not given on the command line; nodes are only read by the - // commands that create or register one, never by commands that talk to an existing node. - const nodeName = NODE_NAME_FROM_ARGUMENT.includes(path) - ? command.args[0] - : NODE_NAME_FROM_OPTION.includes(path) - ? (options.name as string | undefined) - : undefined; - applyConfigDefaults(command, options, { - ...resolved.commandDefaults, - ...(path.startsWith('node ') || path === 'control setup' || path === 'control upgrade' - ? nodeSettings(resolved, nodeName) - : {}), - }); -}); - -/** Every command that does work accepts the connection options, so they can follow the command. */ -function addConnectionOptions(command: Command): void { - if (command.commands.length) { - for (const child of command.commands) addConnectionOptions(child); - // `deploy` is both a command and the parent of `deploy cancel`. - if (!command.options.length) return; - } - command - .option('--config ', CONFIG_HELP) - .option( - '--control-url ', - 'connect target for the control API (the credential still verifies its own public URL)', - ) - .option( - '--credential ', - 'credential file (overrides TUG_CREDENTIAL, TUG_CREDENTIAL_FILE and config)', - ); - // exec and run forward everything after the service to a remote command, which may take its own --verbose. - if (!['exec', 'run'].includes(command.name())) command.option('--verbose', VERBOSE_HELP); - if (!command.options.some((option) => option.long === '--project')) - command.option('--project ', 'project (overrides TUG_PROJECT and config; default: site)'); -} -function forbidExtraArguments(command: Command): void { - command.allowExcessArguments(false); - for (const child of command.commands) forbidExtraArguments(child); -} -for (const command of program.commands) addJsonOption(command); -for (const command of program.commands) addConnectionOptions(command); -forbidExtraArguments(program); -program.showHelpAfterError(); -program.parseAsync().catch((e: unknown) => { - console.error( - isUsageError(errMessage(e)) - ? `${errMessage(e)}\nRun tug --help for usage.` - : errMessage(e), - ); - process.exitCode = e instanceof CliLiveError ? e.exitCode : 1; -}); +process.exitCode = await runCli(process.argv.slice(2)); diff --git a/src/cli/build.ts b/src/cli/build.ts index d06e6e7..bd526c8 100644 --- a/src/cli/build.ts +++ b/src/cli/build.ts @@ -6,15 +6,31 @@ import { buildImage, run, unpackContext } from '../images/build.ts'; import { saveImageArchive } from '../images/artifacts.ts'; import type { ComposeFile, LocalImageUpload } from '../protocol.ts'; import { CONFIG_NAMES } from './config.ts'; +import type { CliRuntime } from './runtime.ts'; export interface LocalBuildDependencies { build: typeof buildImage; save: typeof saveImageArchive; nonce: () => string; remove: (imageRef: string) => Promise; - cleanupWarning?: (message: string) => void; + /** Reports a temporary image that could not be removed; the build itself succeeded. */ + cleanupWarning: (message: string) => void; } +/** The real Docker build, export and removal, reporting cleanup problems through `cleanupWarning`. */ +export const localBuildDependencies = ( + rt: CliRuntime, + cleanupWarning: (message: string) => void, +): LocalBuildDependencies => ({ + build: (options) => buildImage({ ...options, env: rt.env }), + save: (imageRef, file) => saveImageArchive(imageRef, file, rt.env), + nonce: randomUUID, + remove: async (imageRef) => { + await run('docker', ['image', 'rm', imageRef], { env: rt.env, cwd: rt.cwd }); + }, + cleanupWarning, +}); + /** At any depth: the git directory and every file that can hold a token (the untracked config overlays). */ const ALWAYS_EXCLUDED = [ '.git', @@ -164,14 +180,7 @@ export async function prepareLocalImages( compose: ComposeFile, contextDir: string, directory: string, - dependencies: LocalBuildDependencies = { - build: buildImage, - save: saveImageArchive, - nonce: randomUUID, - remove: async (imageRef) => { - await run('docker', ['image', 'rm', imageRef]); - }, - }, + dependencies: LocalBuildDependencies, onProgress?: (message: string) => void, ): Promise { const images: LocalImageUpload[] = []; @@ -196,7 +205,7 @@ export async function prepareLocalImages( try { await dependencies.remove(imageRef); } catch (error) { - (dependencies.cleanupWarning || console.warn)( + dependencies.cleanupWarning( `Could not remove temporary application image ${imageRef}: ${(error as Error).message}`, ); } diff --git a/src/cli/cli.selection.test.ts b/src/cli/cli.selection.process.test.ts similarity index 96% rename from src/cli/cli.selection.test.ts rename to src/cli/cli.selection.process.test.ts index 470e1ef..a61a110 100644 --- a/src/cli/cli.selection.test.ts +++ b/src/cli/cli.selection.process.test.ts @@ -9,6 +9,8 @@ import { createTransport } from '../transport.ts'; import { openDb } from '../db/db.ts'; import { startMtlsControl } from '../../tests/helpers.ts'; import { keysFor, menuCount } from './test-keys.ts'; +import { execCli } from '../../tests/cli-inprocess.ts'; +import { cliEntry } from '../../tests/cli-process.ts'; const exec = promisify(execFile); const terminal = `data:text/javascript,${encodeURIComponent('process.stdin.isTTY = true; process.stdout.isTTY = true;')}`; @@ -23,7 +25,6 @@ test('CLI selections mutate only chosen resources, preserve output and abort wit assert.ok(row, `the expected database row must exist for: ${sql}`); return row; }; - const entry = path.resolve('src/cli.ts'); const api = async (method: string, route: string, body?: unknown) => { const response = await transport.http(transport.base + route, { method, @@ -36,7 +37,7 @@ test('CLI selections mutate only chosen resources, preserve output and abort wit const run = (args: string[], answers: string[] = [], interactive = true) => { const running = exec( process.execPath, - [...(interactive ? ['--import', terminal] : []), entry, ...args], + [...(interactive ? ['--import', terminal] : []), cliEntry, ...args], { cwd: dir, env: { @@ -76,7 +77,11 @@ test('CLI selections mutate only chosen resources, preserve output and abort wit ], ] as [string[], RegExp][]) await assert.rejects( - run(args), + // Rejected before any prompt, so it needs no terminal and runs in-process. + execCli(args, { + cwd: dir, + env: { ...process.env, ...control.env, TUG_CREDENTIAL: '', TUG_PROJECT: 'site', CI: '' }, + }), pattern, 'conflicting selection flags must fail before prompting or mutation', ); diff --git a/src/cli/cli.status.test.ts b/src/cli/cli.status.test.ts index 2caec74..fe0f828 100644 --- a/src/cli/cli.status.test.ts +++ b/src/cli/cli.status.test.ts @@ -3,12 +3,8 @@ import assert from 'node:assert/strict'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { execFile } from 'node:child_process'; -import { promisify } from 'node:util'; import { startMtlsControl } from '../../tests/helpers.ts'; - -const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); +import { execCli } from '../../tests/cli-inprocess.ts'; test('status is human-readable by default and prints JSON with --json', async () => { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-status-')); @@ -18,12 +14,12 @@ test('status is human-readable by default and prints JSON with --json', async () assert.equal(node.status, 200, 'the status test node must register'); const env: NodeJS.ProcessEnv = { ...process.env, ...control.env }; delete env.TUG_CONFIG; - const json = await exec(process.execPath, [entry, 'status', '--json'], { cwd: dir, env }); + const json = await execCli(['status', '--json'], { cwd: dir, env }); assert.ok( Array.isArray(JSON.parse(json.stdout).nodes), 'status --json must print the raw JSON for scripts', ); - const human = await exec(process.execPath, [entry, 'status'], { cwd: dir, env }); + const human = await execCli(['status'], { cwd: dir, env }); assert.match( human.stdout, /No projects/, diff --git a/src/cli/cli.test.ts b/src/cli/cli.test.ts index 041574b..930365b 100644 --- a/src/cli/cli.test.ts +++ b/src/cli/cli.test.ts @@ -10,6 +10,7 @@ import * as tar from 'tar'; import { writeCredentialFile } from '../../tests/helpers.ts'; import { resolveCliConfig, integerOption } from './config.ts'; import { createLocalBuildSnapshot, createSourceArchive, prepareLocalImages } from './build.ts'; +import { execCli } from '../../tests/cli-inprocess.ts'; import { controlPortCheck, dockerPlatform, @@ -20,7 +21,6 @@ import { } from './install.ts'; const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); test('connection resolution consistently uses explicit options, then environment, then selected config', async () => { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-config-')); @@ -154,7 +154,7 @@ test('CLI exposes flat commands and rejects malformed invocations before side ef TUG_CONTROL_URL: 'https://unreachable.invalid', }; try { - const { stdout } = await exec(process.execPath, [entry, '--help'], { env, cwd: dir }); + const { stdout } = await execCli(['--help'], { env, cwd: dir }); for (const name of ['setup', 'control', 'node', 'secret', 'backup', 'restore', 'credential']) assert.match(stdout, new RegExp(`^ ${name}\\b`, 'm'), `help should list ${name}`); assert.doesNotMatch( @@ -188,7 +188,7 @@ test('CLI exposes flat commands and rejects malformed invocations before side ef ['control', 'restore', '--snapshot', 'abcd1234'], ]) { await assert.rejects( - exec(process.execPath, [entry, ...args], { env, cwd: dir }), + execCli([...args], { env, cwd: dir }), (error) => { const stderr = (error as Error & { stderr: string }).stderr; assert.doesNotMatch( @@ -201,7 +201,7 @@ test('CLI exposes flat commands and rejects malformed invocations before side ef `${args.join(' ')} should be rejected`, ); } - const help = await exec(process.execPath, [entry, 'deploy', '--help'], { env, cwd: dir }); + const help = await execCli(['deploy', '--help'], { env, cwd: dir }); assert.match( help.stdout, /--config/, @@ -223,10 +223,8 @@ test('init applies global options after the command without relying on Docker or const file = path.join(dir, 'new.json'); const source = path.join(dir, 'source-cred.json'); await writeCredentialFile(source); - await exec( - process.execPath, + await execCli( [ - entry, 'init', '--config', file, @@ -328,6 +326,7 @@ test('local application builds skip published images and produce unique file-bac '/source', '/temp', { + cleanupWarning: () => {}, nonce: () => 'unique-build', build: async (options) => { assert.equal( @@ -985,11 +984,7 @@ test('network failures name their cause instead of only "fetch failed"', async ( test('node replace and node repair accept -y like node add, so scripts can share the flags', async () => { for (const verb of ['replace', 'repair']) { - const { stdout } = await promisify(execFile)( - process.execPath, - [path.resolve('src/cli.ts'), 'node', verb, '--help'], - { timeout: 60_000 }, - ); + const { stdout } = await execCli(['node', verb, '--help']); assert.match(stdout, /-y, --yes/, `node ${verb} must list -y, --yes`); } }); diff --git a/src/cli/cli.tui.test.ts b/src/cli/cli.tui.process.test.ts similarity index 97% rename from src/cli/cli.tui.test.ts rename to src/cli/cli.tui.process.test.ts index f9a55b9..5d1a5f7 100644 --- a/src/cli/cli.tui.test.ts +++ b/src/cli/cli.tui.process.test.ts @@ -6,9 +6,9 @@ import path from 'node:path'; import { execFile } from 'node:child_process'; import { promisify } from 'node:util'; import { startMtlsControl } from '../../tests/helpers.ts'; +import { cliEntry } from '../../tests/cli-process.ts'; const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); async function withControl( run: ( @@ -29,7 +29,7 @@ async function withControl( } } const tug = (args: string[], env: NodeJS.ProcessEnv, cwd: string) => - exec(process.execPath, [entry, ...args], { cwd, env }).then( + exec(process.execPath, [cliEntry, ...args], { cwd, env }).then( (r) => ({ code: 0, stdout: r.stdout, stderr: r.stderr }), (e: { code: number; stdout: string; stderr: string }) => ({ code: e.code, diff --git a/src/cli/commands/backup.ts b/src/cli/commands/backup.ts index 1bfe532..4fe28d9 100644 --- a/src/cli/commands/backup.ts +++ b/src/cli/commands/backup.ts @@ -3,6 +3,8 @@ import { withProgress } from '../progress.ts'; import type { Command } from 'commander'; import { backupCheckProblems } from '../../backup/check.ts'; import { collectList, loadCfg, print, readEnvValues, request } from './context.ts'; +import { out, err } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; interface BackupRunRecord { id: string; @@ -57,7 +59,7 @@ const runState = (run: BackupRunRecord): string => : run.state; const BACKUP_TERMINAL = ['succeeded', 'failed', 'missed', 'cancelled']; -export function registerBackup(program: Command): void { +export function registerBackup(rt: CliRuntime, program: Command): void { const backup = program .command('backup') .description('run and inspect workload backups and set where they go'); @@ -76,19 +78,19 @@ export function registerBackup(program: Command): void { ) => { if (o.select && targets.length) throw new Error('--select cannot be combined with explicit targets'); - if (o.select) targets = await selectBackups(); - return withProgress('Queueing backups', async (progress) => { - const project = (await loadCfg()).project || 'site'; + if (o.select) targets = await selectBackups(rt); + return withProgress(rt, 'Queueing backups', async (progress) => { + const project = loadCfg(rt).project || 'site'; const queued = await request<{ runs: { runId: string; target: string }[]; errors: string[]; - }>('POST', '/api/v1/backups/run', { + }>(rt, 'POST', '/api/v1/backups/run', { project, targets: targets.length ? targets : undefined, }); - for (const message of queued.errors) console.error(message); + for (const message of queued.errors) err(rt, message); if (!o.json) - for (const run of queued.runs) console.log(`queued ${run.target} as ${run.runId}`); + for (const run of queued.runs) out(rt, `queued ${run.target} as ${run.runId}`); let failed = queued.errors.length > 0; // With --json the outcome of each run is printed once, at the end. const finished: BackupListing['runs'] = []; @@ -103,6 +105,7 @@ export function registerBackup(program: Command): void { while (pending.size && Date.now() < deadline) { await new Promise((resolve) => setTimeout(resolve, 2000)); const listing = await request( + rt, 'GET', `/api/v1/backups?project=${encodeURIComponent(project)}&limit=200`, ); @@ -114,7 +117,8 @@ export function registerBackup(program: Command): void { const ok = run.state === 'succeeded'; failed ||= !ok; if (!o.json) - console.log( + out( + rt, ok ? `${run.target}: snapshot ${run.snapshot_id?.slice(0, 8)}, ${formatBytes(run.added_bytes)} added` : `${run.target}: ${run.state}${run.error ? ` (${run.error})` : ''}`, @@ -127,20 +131,21 @@ export function registerBackup(program: Command): void { ); } if (pending.size) { - console.error( + err( + rt, `timed out waiting for ${pending.size} backup(s); they keep running on the node`, ); failed = true; } } if (o.json) - print({ + print(rt, { ok: !failed, queued: queued.runs, errors: queued.errors, ...(o.wait ? { finished } : {}), }); - if (failed) process.exitCode = 1; + if (failed) rt.exitCode = 1; }); }, ); @@ -157,28 +162,32 @@ export function registerBackup(program: Command): void { 'with --check, accept a project that has no enabled backup target (a destination is still required)', ) .action(async (o: { limit: string; check?: boolean; allowEmpty?: boolean; json?: boolean }) => { - const project = (await loadCfg()).project || 'site'; + const project = loadCfg(rt).project || 'site'; const listing = await request( + rt, 'GET', `/api/v1/backups?project=${encodeURIComponent(project)}&limit=${encodeURIComponent(o.limit)}`, ); if (!listing.destinationConfigured) - console.error('no backup destination is configured; run tug backup destination set'); - if (o.json) print(listing); + err(rt, 'no backup destination is configured; run tug backup destination set'); + if (o.json) print(rt, listing); else if (!listing.targets.length) - console.log('no backup targets; add x-tug.backup to a database service or volume'); + out(rt, 'no backup targets; add x-tug.backup to a database service or volume'); if (!o.json && listing.control) - console.log( + out( + rt, `control\t-\tnightly\tlast success ${listing.control.lastSuccessAt ?? 'never'}${listing.control.scope === 'local' ? '\tlocal path only: not off-host' : ''}${listing.control.problem ? `\t${listing.control.problem}` : ''}`, ); if (!o.json) for (const t of listing.targets) - console.log( + out( + rt, `${t.target}\t${t.node ?? '-'}\t${t.schedule}\tlast success ${t.lastSuccessAt ?? 'never'}\tnext ${t.enabled ? t.nextRunAt : 'disabled'}`, ); if (!o.json) for (const r of listing.runs) - console.log( + out( + rt, `${r.finished_at ?? r.queued_at}\t${r.target}\t${r.trigger}\t${runState(r)}\t${r.snapshot_id?.slice(0, 8) ?? '-'}\t${formatBytes(r.size_bytes)}\t${r.id}${r.error ? `\t${r.error}` : ''}`, ); if (o.check) { @@ -186,8 +195,8 @@ export function registerBackup(program: Command): void { requireProtection: true, allowEmpty: o.allowEmpty, }); - for (const problem of problems) console.error(`PROBLEM ${problem}`); - if (problems.length) process.exitCode = 1; + for (const problem of problems) err(rt, `PROBLEM ${problem}`); + if (problems.length) rt.exitCode = 1; } }); backup @@ -196,9 +205,10 @@ export function registerBackup(program: Command): void { 'stop a queued or running backup (the run id is the last column of `tug backup list`); it is reported as cancelled and not retried', ) .action(async (run: string) => { - const project = (await loadCfg()).project || 'site'; + const project = loadCfg(rt).project || 'site'; print( - await request('POST', `/api/v1/backups/${encodeURIComponent(run)}/cancel`, { project }), + rt, + await request(rt, 'POST', `/api/v1/backups/${encodeURIComponent(run)}/cancel`, { project }), ); }); backup @@ -212,10 +222,12 @@ export function registerBackup(program: Command): void { ) .action(async (o: { control?: boolean }) => { if (o.control) - return print(await request('GET', '/api/v1/backup/repository-password?control=1')); - const project = (await loadCfg()).project || 'site'; + return print(rt, await request(rt, 'GET', '/api/v1/backup/repository-password?control=1')); + const project = loadCfg(rt).project || 'site'; print( + rt, await request( + rt, 'GET', `/api/v1/backup/repository-password?project=${encodeURIComponent(project)}`, ), @@ -237,11 +249,13 @@ export function registerBackup(program: Command): void { [], ) .action(async (url: string, o: { env: string[] }) => { - const env = await readEnvValues(o.env); - console.log( - JSON.stringify(await request('POST', '/api/v1/backup/destination', { url, env })), + const env = await readEnvValues(rt, o.env); + out( + rt, + JSON.stringify(await request(rt, 'POST', '/api/v1/backup/destination', { url, env })), ); - console.error( + err( + rt, 'Control now backs itself up here every night. Keep its password with these credentials: tug backup password --control', ); }); @@ -250,13 +264,13 @@ export function registerBackup(program: Command): void { .description( 'show the backup destination and the names of its credential variables, never values', ) - .action(async () => print(await request('GET', '/api/v1/backup/destination'))); + .action(async () => print(rt, await request(rt, 'GET', '/api/v1/backup/destination'))); destination .command('remove') .description( 'remove the backup destination and its stored credentials; existing backups stay in the repository', ) .action(async () => - console.log(JSON.stringify(await request('DELETE', '/api/v1/backup/destination'))), + out(rt, JSON.stringify(await request(rt, 'DELETE', '/api/v1/backup/destination'))), ); } diff --git a/src/cli/commands/context.preca.test.ts b/src/cli/commands/context.preca.test.ts index d33103e..cc288fb 100644 --- a/src/cli/commands/context.preca.test.ts +++ b/src/cli/commands/context.preca.test.ts @@ -7,7 +7,8 @@ import path from 'node:path'; import { test } from 'node:test'; import { Pki, identityUri, serverNames } from '../../pki.ts'; import { serverTlsOptions } from '../../control/tls-server.ts'; -import { resetVersionChecks, request, setResolvedConfig } from './context.ts'; +import { request } from './context.ts'; +import { testRuntime } from '../../../tests/cli-runtime.ts'; import type { ResolvedCliConfig } from '../config.ts'; /** @@ -38,7 +39,8 @@ test('a credential from a different CA fails the preflight with the both-fingerp const url = `https://127.0.0.1:${(https.address() as { port: number }).port}`; const realpathed = path.join(dir, 'credential.json'); await fs.writeFile(realpathed, JSON.stringify(credential), { mode: 0o600 }); - setResolvedConfig({ + const { rt } = testRuntime(); + rt.state.config = { file: path.join(dir, 'cfg.yml'), localFile: path.join(dir, 'cfg.local.yml'), fileExists: false, @@ -49,22 +51,20 @@ test('a credential from a different CA fails the preflight with the both-fingerp nodeDefaults: {}, nodes: {}, project: 'site', - } as unknown as ResolvedCliConfig); - resetVersionChecks(); + } as unknown as ResolvedCliConfig; try { await assert.rejects( - request('GET', '/api/v1/services?project=site'), + request(rt, 'GET', '/api/v1/services?project=site'), /did not present a certificate signed by this credential's CA/, 'the CA mismatch must surface as the actionable message from the first TLS connection (the preflight)', ); await assert.rejects( - request('GET', '/api/v1/services?project=site'), + request(rt, 'GET', '/api/v1/services?project=site'), /this credential trusts [A-F0-9]/, 'the message also names the trusted CA fingerprint', ); } finally { https.closeAllConnections(); await new Promise((resolve) => https.close(() => resolve())); - resetVersionChecks(); } }); diff --git a/src/cli/commands/context.skew.test.ts b/src/cli/commands/context.skew.test.ts index c81c1dc..9d29bb7 100644 --- a/src/cli/commands/context.skew.test.ts +++ b/src/cli/commands/context.skew.test.ts @@ -5,12 +5,12 @@ import { createServer } from 'node:https'; import type { IncomingMessage, ServerResponse } from 'node:http'; import os from 'node:os'; import path from 'node:path'; -import { after, test } from 'node:test'; +import { test } from 'node:test'; import { Pki, serverNames, identityUri } from '../../pki.ts'; import type { Credential } from '../../pki.ts'; import { serverTlsOptions } from '../../control/tls-server.ts'; -import { pinPackageVersion } from '../../images/image.ts'; -import { resetVersionChecks, request, setResolvedConfig } from './context.ts'; +import { request } from './context.ts'; +import { testRuntime } from '../../../tests/cli-runtime.ts'; import type { ResolvedCliConfig } from '../config.ts'; /** @@ -90,8 +90,10 @@ async function startFixture(scenario: Scenario): Promise { }; } -async function configure(f: Fixture): Promise { - setResolvedConfig({ +/** A runtime that reports `CLI_VERSION` and talks to the fixture; it remembers nothing of any other run. */ +function configure(f: Fixture) { + const run = testRuntime({ version: CLI_VERSION }); + run.rt.state.config = { file: '/dev/null', localFile: '/dev/null', fileExists: false, @@ -102,35 +104,21 @@ async function configure(f: Fixture): Promise { nodeDefaults: {}, nodes: {}, project: 'site', - } as unknown as ResolvedCliConfig); - resetVersionChecks(); + } as unknown as ResolvedCliConfig; + return run; } -const warnings: string[] = []; -const unmutatedWarning = console.error; -const speak = (): void => { - console.error = unmutatedWarning; -}; // Fixed versions, independent of the package's real one: the verdicts depend only on how these relate under the // skew rule (a different major is breaking from 1.0; an older minor or patch of the same major is compatible). const CLI_VERSION = '1.4.2'; const OLDER_MAJOR = '0.9.0'; const NEWER_PATCH = '1.4.3'; -pinPackageVersion(CLI_VERSION); -after(() => pinPackageVersion(undefined)); - -const quiet = (): void => { - console.error = (message?: unknown) => { - warnings.push(String(message)); - }; -}; test('a read-first command gets its skew judged off the response stamp, with no extra probe', async () => { const f = await startFixture({ stamp: CLI_VERSION }); - await configure(f); - quiet(); + const h = configure(f); try { - await request('GET', '/api/v1/status'); + await request(h.rt, 'GET', '/api/v1/status'); assert.deepEqual( f.hits.map((h) => h.route), ['/api/v1/status'], @@ -141,18 +129,16 @@ test('a read-first command gets its skew judged off the response stamp, with no [CLI_VERSION], 'every request declares the calling CLI version for the control-side guard', ); - assert.deepEqual(warnings, [], 'matching versions stay silent'); + assert.equal(h.stderr(), '', 'matching versions stay silent'); // The agreement is remembered for the process; a later mutation pays no probe either. - await request('POST', '/api/v1/deployments', { project: 'site' }); + await request(h.rt, 'POST', '/api/v1/deployments', { project: 'site' }); assert.deepEqual( f.hits.map((h) => h.route), ['/api/v1/status', '/api/v1/deployments'], 'a mutation that follows a judged read skips the probe', ); } finally { - speak(); await f.close(); - resetVersionChecks(); } }); @@ -160,10 +146,10 @@ test('a stale stamp or stampless control refuses the read-first command with the for (const stamp of [undefined, OLDER_MAJOR]) { const label = stamp === undefined ? 'a stampless control' : `a stale stamp (${stamp})`; const f = await startFixture({ stamp }); - await configure(f); + const h = configure(f); try { await assert.rejects( - request('GET', '/api/v1/status'), + request(h.rt, 'GET', '/api/v1/status'), /tug control upgrade --yes/, `${label} is refused, from the response the read already paid for`, ); @@ -174,23 +160,19 @@ test('a stale stamp or stampless control refuses the read-first command with the ); } finally { await f.close(); - resetVersionChecks(); } } }); test('a control on a newer patch is compatible and stays silent', async () => { const f = await startFixture({ stamp: NEWER_PATCH }); - await configure(f); - quiet(); + const h = configure(f); try { - await request('GET', '/api/v1/status'); - await request('GET', '/api/v1/status'); - assert.deepEqual(warnings, [], 'a patch never changes the wire, so no pin warning is printed'); + await request(h.rt, 'GET', '/api/v1/status'); + await request(h.rt, 'GET', '/api/v1/status'); + assert.equal(h.stderr(), '', 'a patch never changes the wire, so no pin warning is printed'); } finally { - speak(); await f.close(); - resetVersionChecks(); } }); @@ -202,16 +184,16 @@ test('a mutating first request is probed against the version route before it is { stamp: undefined, noDeploymentRoute: true, expected: ['/api/v1/version'] }, ]) { const f = await startFixture(scenario); - await configure(f); + const h = configure(f); try { if (scenario.expected.length === 2) await assert.doesNotReject( - request('POST', '/api/v1/deployments', { project: 'site' }), + request(h.rt, 'POST', '/api/v1/deployments', { project: 'site' }), 'a compatible control receives the mutation', ); else await assert.rejects( - request('POST', '/api/v1/deployments', { project: 'site' }), + request(h.rt, 'POST', '/api/v1/deployments', { project: 'site' }), /tug control upgrade --yes/, 'an older control is refused before it received the mutation', ); @@ -222,7 +204,6 @@ test('a mutating first request is probed against the version route before it is ); } finally { await f.close(); - resetVersionChecks(); } } }); @@ -233,28 +214,26 @@ test("the control's own skew refusal is surfaced verbatim, on read and mutation const controlError = 'this client (test) is newer than the control running own: fix it now'; const refusal = await (async () => { const f = await startFixture({ stamp: CLI_VERSION, refuseAll: controlError }); - await configure(f); + const h = configure(f); try { - return await request('GET', '/api/v1/status').then( + return await request(h.rt, 'GET', '/api/v1/status').then( () => null, (e) => String((e as Error).message), ); } finally { await f.close(); - resetVersionChecks(); } })(); const mutationRefusal = await (async () => { const f = await startFixture({ stamp: CLI_VERSION, refuseAll: controlError }); - await configure(f); + const h = configure(f); try { - return await request('POST', '/api/v1/deployments', { project: 'site' }).then( + return await request(h.rt, 'POST', '/api/v1/deployments', { project: 'site' }).then( () => null, (e) => String((e as Error).message), ); } finally { await f.close(); - resetVersionChecks(); } })(); assert.equal( @@ -271,16 +250,15 @@ test("the control's own skew refusal is surfaced verbatim, on read and mutation test('a refused control is judged again on the next request, never waved through', async () => { const f = await startFixture({ stamp: OLDER_MAJOR }); - await configure(f); + const h = configure(f); try { for (const attempt of [1, 2]) await assert.rejects( - request('GET', '/api/v1/status'), + request(h.rt, 'GET', '/api/v1/status'), /tug control upgrade --yes/, `attempt ${attempt} against a stale control is refused: a refusal must not be remembered as agreement`, ); } finally { await f.close(); - resetVersionChecks(); } }); diff --git a/src/cli/commands/context.ts b/src/cli/commands/context.ts index 6a2e6ec..bce42f3 100644 --- a/src/cli/commands/context.ts +++ b/src/cli/commands/context.ts @@ -1,6 +1,7 @@ import { canPrompt } from '../prompt.ts'; -import { markWorkStarted } from '../usage.ts'; -import { selectOne } from '../selection.ts'; +import { err, markWorkStarted, out, resolvePath } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; +import { selectOne, terminalSelection } from '../selection.ts'; import type { ServiceChoice } from './selection.ts'; import { withProgress } from '../progress.ts'; export { runCapture, runLocal } from '../process.ts'; @@ -22,7 +23,6 @@ import type { ResolvedCliConfig } from '../config.ts'; import { createTransport } from '../../transport.ts'; import { createCliLiveTransport } from '../live-transport.ts'; import { caTrustCode, describeCaMismatch } from '../../pki.ts'; -import { packageVersion } from '../../images/image.ts'; import { parseLiveRequest, runCliLive } from '../live.ts'; import type { CliLiveIO, LiveInput, LiveRequest } from '../live.ts'; import { TERMINAL_DEPLOYMENT_STATES } from '../../protocol.ts'; @@ -72,9 +72,14 @@ export function formatDeployment( } /** Prints the full API result with `--json`, otherwise the human summary. */ -export function printResult(json: boolean | undefined, value: T, summary: (value: T) => string) { - if (json) print(value); - else console.log(summary(value)); +export function printResult( + rt: CliRuntime, + json: boolean | undefined, + value: T, + summary: (value: T) => string, +) { + if (json) print(rt, value); + else out(rt, summary(value)); } export interface CommonOpts { project?: string; @@ -93,13 +98,10 @@ export const CONFIG_HELP = 'CLI config file, YAML or JSON (default: TUG_CONFIG, else tug.yml, tug.yaml, tug.json or .tug.json)'; type Config = ResolvedCliConfig; -let resolvedConfig: Config | undefined; -/** Set by the root `preAction` hook before any command runs. */ -export function setResolvedConfig(config: Config): void { - resolvedConfig = config; -} -export async function loadCfg(): Promise { - return resolvedConfig!; +/** The configuration the root `preAction` hook resolved for this run, before any command runs. */ +export function loadCfg(rt: CliRuntime): Config { + if (!rt.state.config) throw new Error('the configuration is resolved before a command runs'); + return rt.state.config; } /** * Collects a flag that takes several values: it can be repeated or given a comma-separated list, and the two mix, so @@ -113,17 +115,11 @@ export const collectList = (value: string, previous: string[]): string[] => [ .map((item) => item.trim()) .filter(Boolean), ]; -export async function readStdin(): Promise { +export async function readStdin(rt: CliRuntime): Promise { const chunks: Buffer[] = []; - for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk)); + for await (const chunk of rt.stdin) chunks.push(Buffer.from(chunk)); return Buffer.concat(chunks).toString('utf8'); } -/** Version agreements are remembered per control (base + trusted CA mark) per process. */ -const versionChecked = new Set(); -/** Test isolation helper: forget the remembered version agreements. */ -export function resetVersionChecks(): void { - versionChecked.clear(); -} /** Cache key for one control: address override, base and the credential's CA mark (mismatches change the mark). The * process-local set never compares CAs across processes, so the raw values distinguish all it needs to, without * cryptographic work and without depending on fingerprintPem with corrupt input. */ @@ -171,18 +167,18 @@ export function versionVerdict( } /** Apply a decided skew verdict: the one-time warning and the refusal, shared by both judging paths. */ -function applyVerdict(verdict: { error?: string; warning?: string }): void { - if (verdict.warning) console.error(verdict.warning); // once per process: versionChecked gates the callers +function applyVerdict(rt: CliRuntime, verdict: { error?: string; warning?: string }): void { + if (verdict.warning) err(rt, verdict.warning); // once per run: versionChecked gates the callers if (verdict.error) throw new Error(verdict.error); } /** Explicit skew probe for the flows the header cannot cover: a first request that mutates (the refusal must not * arrive after the harm is done) and flows with no HTTP request at all before acting (live commands, `node add`). * Deprecated-equivalent of the header check: read-first flows see the `x-tug-version` stamp within their own request. * One extra request per control per process; remember it per control (base + trusted CA mark) via versionChecked. */ -async function preflightVersion(c: Config): Promise { +async function preflightVersion(rt: CliRuntime, c: Config): Promise { const key = versionKey(c); - if (!key || versionChecked.has(key)) return; - const transport = createTransport(c.credential!, c.controlUrl); + if (!key || rt.state.versionChecked.has(key)) return; + const transport = createTransport(c.credential!, c.controlUrl, rt.version); try { let res; try { @@ -208,20 +204,21 @@ async function preflightVersion(c: Config): Promise { const refusal = skewRefusalMessage(await res.text().catch(() => '')); if (refusal) throw new Error(refusal); if (res.status === 404 || res.status === 405) - throw new Error(versionVerdict(undefined, packageVersion(), transport.base).error); + throw new Error(versionVerdict(undefined, rt.version, transport.base).error); return; } // The probe judges the same stamp the read path does; a stampless 200 without the `{ v }` route's own stamp is // refused the same as on the read path, keeping one rule for both directions of the check. applyVerdict( + rt, versionVerdict( res.headers.get(VERSION_STAMP_HEADER) ?? undefined, - packageVersion(), + rt.version, transport.base, ), ); // Remembered only after a passing verdict (a warning passes), so a refused control is probed again. - versionChecked.add(key); + rt.state.versionChecked.add(key); } finally { void transport.close(); } @@ -231,11 +228,7 @@ async function preflightVersion(c: Config): Promise { * A newer minor inside one major only adds, so a CLI ahead of its control may call a route the control lacks. The * control's stamp then explains the 404, instead of the bare express body. */ -export function missingRouteHint( - res: Response, - base: string, - cliVersion = packageVersion(), -): string { +export function missingRouteHint(res: Response, base: string, cliVersion: string): string { if (res.status !== 404) return ''; const stamp = res.headers.get(VERSION_STAMP_HEADER); const control = stamp ? majorMinor(stamp) : null; @@ -264,30 +257,34 @@ async function noCredentialMessage(c: Config): Promise { } /** The pinned mTLS transport for the resolved credential; an address override only changes the connect target. */ -export async function transportFor(c: Config, guard: SkewGuard) { - markWorkStarted(); +export async function transportFor(rt: CliRuntime, c: Config, guard: SkewGuard) { + markWorkStarted(rt); if (!c.credential) throw new Error(await noCredentialMessage(c)); - if (guard === 'probe') await preflightVersion(c); - return createTransport(c.credential, c.controlUrl); + if (guard === 'probe') await preflightVersion(rt, c); + return createTransport(c.credential, c.controlUrl, rt.version); } +/** A control read bound to one run; the shape `loadDeployValues` and `loadExistingNames` take, so tests can fake it. */ +// eslint-disable-next-line @typescript-eslint/no-explicit-any +export type ControlGet = (method: string, route: string) => Promise; // eslint-disable-next-line @typescript-eslint/no-explicit-any export async function request( + rt: CliRuntime, method: string, route: string, body?: unknown, multipart = false, ): Promise { - markWorkStarted(); - const c = await loadCfg(); + markWorkStarted(rt); + const c = loadCfg(rt); if (!c.credential) throw new Error(await noCredentialMessage(c)); const key = versionKey(c); - const unseen = !!key && !versionChecked.has(key); + const unseen = !!key && !rt.state.versionChecked.has(key); // The skew check rides on ordinary traffic: a read's response carries the control's `x-tug-version` stamp and is // judged after the fact (reads are safe to have run against an old control). A mutating first request is judged // BEFORE it is sent, against the version route, because the harm of new-CLI-old-control semantics is already done // once the old control received the mutation. const firstRead = unseen && method === 'GET'; - const transport = await transportFor(c, unseen && method !== 'GET' ? 'probe' : 'stamp'); + const transport = await transportFor(rt, c, unseen && method !== 'GET' ? 'probe' : 'stamp'); const headers: Record = {}; if (!multipart) headers['content-type'] = 'application/json'; try { @@ -315,20 +312,21 @@ export async function request( // does anything else with the control. Missing or garbage stamps get the same verdict as an old control. // The control is remembered only once the verdict passed, so a refused control is judged again, never waved through. applyVerdict( + rt, versionVerdict( res.headers.get(VERSION_STAMP_HEADER) ?? undefined, - packageVersion(), + rt.version, transport.base, ), ); - versionChecked.add(key!); + rt.state.versionChecked.add(key!); } if (!res.ok) { // A control may refuse the request itself when this CLI is newer than it; its own wording is authoritative. const text = await res.text().catch(() => ''); throw new Error( skewRefusalMessage(text) ?? - `${method} ${route}: ${res.status} ${text}${missingRouteHint(res, transport.base)}`, + `${method} ${route}: ${res.status} ${text}${missingRouteHint(res, transport.base, rt.version)}`, ); } return (await res.json()) as T; @@ -337,16 +335,16 @@ export async function request( } } /** The project a project-scoped command works on: `--project`, then the resolved config, then `site`. */ -export async function projectOf(o: CommonOpts): Promise { - return o.project || (await loadCfg()).project || 'site'; +export function projectOf(rt: CliRuntime, o: CommonOpts): string { + return o.project || loadCfg(rt).project || 'site'; } /** * Saves a control response body to `file` (mode 0600, never overwriting) without buffering it. The archive holds * the master key and the CA key, so it is never created readable by others. */ -export async function download(route: string, file: string): Promise { - markWorkStarted(); - const transport = await transportFor(await loadCfg(), 'stamp'); +export async function download(rt: CliRuntime, route: string, file: string): Promise { + markWorkStarted(rt); + const transport = await transportFor(rt, loadCfg(rt), 'stamp'); let created = false; try { const res = await transport.http(`${transport.base}${route}`, { method: 'GET' }); @@ -354,7 +352,7 @@ export async function download(route: string, file: string): Promise { if (!res.body) throw new Error(`GET ${route}: the response has no body`); // Exclusive creation first: if the file exists this throws before `created` is set, so cleanup below can only ever // remove a file this command made. - const handle = await fsp.open(file, 'wx', 0o600); + const handle = await fsp.open(resolvePath(rt, file), 'wx', 0o600); created = true; await pipeline( Readable.fromWeb(res.body as import('node:stream/web').ReadableStream), @@ -362,7 +360,7 @@ export async function download(route: string, file: string): Promise { ); } catch (error) { // A failure after creation leaves a partial archive that must not be mistaken for a backup. - if (created) await fsp.rm(file, { force: true }); + if (created) await fsp.rm(resolvePath(rt, file), { force: true }); throw error; } finally { void transport.close(); @@ -372,16 +370,16 @@ export async function download(route: string, file: string): Promise { * Posts a local file as the request body (`application/gzip`), streamed from disk without buffering it, and returns * the JSON answer. Used to hand a control archive to the control host for a restore. */ -export async function upload(route: string, file: string): Promise { - markWorkStarted(); - const c = await loadCfg(); +export async function upload(rt: CliRuntime, route: string, file: string): Promise { + markWorkStarted(rt); + const c = loadCfg(rt); // A mutation: judged against the control's version before any byte is sent. - const transport = await transportFor(c, 'probe'); + const transport = await transportFor(rt, c, 'probe'); try { const res = await transport.http(`${transport.base}${route}`, { method: 'POST', headers: { 'content-type': 'application/gzip' }, - body: Readable.toWeb(createReadStream(file)) as never, + body: Readable.toWeb(createReadStream(resolvePath(rt, file))) as never, duplex: 'half', } as RequestInit); if (!res.ok) @@ -395,20 +393,25 @@ export async function upload(route: string, file: string): Promise { * Values for the named variables: from the environment, else from stdin lines, one per name that the environment * does not provide, in the order the names are given (a repeated name counts once). */ -export async function readEnvValues(names: string[]): Promise> { +export async function readEnvValues( + rt: CliRuntime, + names: string[], +): Promise> { const unique = [...new Set(names)]; - const missing = unique.filter((name) => process.env[name] === undefined); + const missing = unique.filter((name) => rt.env[name] === undefined); const lines = missing.length - ? (await readStdin()).split(/\r?\n/).filter((line) => line.length > 0) + ? (await readStdin(rt)).split(/\r?\n/).filter((line) => line.length > 0) : []; if (lines.length < missing.length) throw new Error(`expected a value on stdin for ${missing.slice(lines.length).join(', ')}`); return Object.fromEntries( - unique.map((name) => [name, process.env[name] ?? lines[missing.indexOf(name)]]), + unique.map((name) => [name, rt.env[name] ?? lines[missing.indexOf(name)]]), ); } -export const print = (value: unknown): void => console.log(JSON.stringify(value, null, 2)); +export const print = (rt: CliRuntime, value: unknown): void => + out(rt, JSON.stringify(value, null, 2)); export async function waitForDeployment( + rt: CliRuntime, deploymentId: string, timeoutSeconds = 300, onProgress?: (deployment: DeploymentRecord) => void, @@ -418,6 +421,7 @@ export async function waitForDeployment( let deployment: DeploymentRecord; try { deployment = await request( + rt, 'GET', `/api/v1/deployments/${encodeURIComponent(deploymentId)}`, ); @@ -442,13 +446,14 @@ export async function waitForDeployment( ); } export async function waitForCommand( + rt: CliRuntime, commandId: string, timeoutSeconds = 60, ): Promise { - return withProgress(`Waiting for command ${commandId}`, async (progress) => { + return withProgress(rt, `Waiting for command ${commandId}`, async (progress) => { const deadline = Date.now() + timeoutSeconds * 1000; while (Date.now() < deadline) { - const cmd = await request('GET', `/api/v1/commands/${commandId}`); + const cmd = await request(rt, 'GET', `/api/v1/commands/${commandId}`); if (cmd) progress.stage(`Command ${commandId}: ${cmd.state}`); if (cmd?.state === 'succeeded' || cmd?.state === 'failed') return cmd; await new Promise((r) => setTimeout(r, 1000)); @@ -457,13 +462,15 @@ export async function waitForCommand( }); } export async function runLive( + rt: CliRuntime, operation: LiveRequest['operation'], input: Omit, - io: CliLiveIO = {}, + io: Partial = {}, ): Promise { - const cfg = await loadCfg(); - if (!input.node && canPrompt()) { + const cfg = loadCfg(rt); + if (!input.node && canPrompt(rt)) { const { services: listing } = await request<{ services: ServiceChoice[] }>( + rt, 'GET', `/api/v1/services?project=${encodeURIComponent(cfg.project || 'site')}`, ); @@ -474,19 +481,29 @@ export async function runLive( .map((node) => [node.name, node]), ); if (candidates.size > 1) - input.node = await selectOne(undefined, 'Select a node for this operation', async () => - [...candidates.values()].map((node) => ({ - value: node.name, - label: `${node.name} (${node.status})`, - })), + input.node = await selectOne( + undefined, + 'Select a node for this operation', + async () => + [...candidates.values()].map((node) => ({ + value: node.name, + label: `${node.name} (${node.status})`, + })), + terminalSelection(rt), ); } // Commands that skip the HTTP service listing (an explicit service name) would otherwise reach an old control on the // live channel alone; the same per-control preflight as ordinary API requests applies here. - await transportFor(cfg, 'probe').then((t) => t.close()); - process.exitCode = await runCliLive( + await transportFor(rt, cfg, 'probe').then((t) => t.close()); + rt.exitCode = await runCliLive( parseLiveRequest(operation, { ...input, project: cfg.project || 'site' }), - createCliLiveTransport(cfg.credential, cfg.controlUrl), - io, + createCliLiveTransport(cfg.credential, cfg.controlUrl, rt.version), + { + stdin: rt.stdin, + stdout: rt.stdout, + stderr: rt.stderr, + signals: rt.signals, + ...io, + }, ); } diff --git a/src/cli/commands/control.restart.test.ts b/src/cli/commands/control.restart.test.ts index e818c92..38310a4 100644 --- a/src/cli/commands/control.restart.test.ts +++ b/src/cli/commands/control.restart.test.ts @@ -1,13 +1,9 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { execFile } from 'node:child_process'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { promisify } from 'node:util'; - -const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); +import { execCli } from '../../../tests/cli-inprocess.ts'; /** A fake `docker` that logs every call; `inspect` succeeds only when the control container exists in $FAKE_DIR. */ const FAKE_DOCKER = `#!/bin/sh @@ -44,7 +40,7 @@ async function withHost( await run({ control: async (...args) => { try { - const { stdout, stderr } = await exec(process.execPath, [entry, 'control', ...args], { + const { stdout, stderr } = await execCli(['control', ...args], { cwd: dir, env: { ...process.env, diff --git a/src/cli/commands/control.ts b/src/cli/commands/control.ts index 625968a..b783aaf 100644 --- a/src/cli/commands/control.ts +++ b/src/cli/commands/control.ts @@ -1,5 +1,4 @@ import fsp from 'node:fs/promises'; -import path from 'node:path'; import { withProgress } from '../progress.ts'; import { formatBytes } from './backup.ts'; import { runProcess, runStep, SshHostKeyError, sshHostKeyHint, STAGE_MARKER } from '../process.ts'; @@ -23,7 +22,7 @@ import { stopControlScript, } from '../upgrade.ts'; import type { ControlInstall } from '../upgrade.ts'; -import { assertImagePublished, defaultImage, resolveImage } from '../../images/image.ts'; +import { defaultImage, resolveImage } from '../../images/image.ts'; import { decodeCredential, fingerprintPem, writeFileDurable } from '../../pki.ts'; import { loadTemplate } from '../load-template.ts'; import { errMessage } from '../../errors.ts'; @@ -40,7 +39,13 @@ import { upload, } from './context.ts'; import type { InstallOpts } from './context.ts'; -import { bootstrapDocker, hostHasDocker, preflightRemote, transferTugImage } from './host.ts'; +import { + assertPublished, + bootstrapDocker, + hostHasDocker, + preflightRemote, + transferTugImage, +} from './host.ts'; import { importCredential } from './init.ts'; import { CONTROL_LEFTOVERS, @@ -49,6 +54,8 @@ import { controlGuardScript, controlMigrateScript, } from '../migrate.ts'; +import { out, err, resolvePath } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; const PREVIEW_NOTE = 'This only checked the backup and changed nothing; add --confirm to restore it.'; @@ -84,6 +91,7 @@ interface SetupOpts extends InstallOpts { /** Replaces the control container with one running `image` on the same volume; the data is never touched. */ async function installControlContainer( + rt: CliRuntime, sshTarget: string, plan: Omit, progress: StepProgress, @@ -101,18 +109,19 @@ async function installControlContainer( MARKER: STAGE_MARKER, CONTAINER_SH: sh(CONTROL_CONTAINER), }); - await runStep('ssh', ['--', sshTarget, remote], { progress }); + await runStep(rt, 'ssh', ['--', sshTarget, remote], { progress }); } /** Running `control setup` over an existing control rebuilds it from this run's flags alone; say what that changes. */ async function warnWhenSetupChangesInstall( + rt: CliRuntime, sshTarget: string, plan: { controlUrl: string; port: number; extraSans: string[] }, ): Promise { let existing: ControlInstall; try { existing = parseControlInspect( - await runCapture('ssh', ['--', sshTarget, inspectControlScript]), + await runCapture(rt, 'ssh', ['--', sshTarget, inspectControlScript]), ); } catch { return; // nothing installed yet (or not by setup): there is nothing to compare @@ -129,7 +138,8 @@ async function warnWhenSetupChangesInstall( : []), ]; if (changes.length) - console.error( + err( + rt, `note: control is already installed on ${sshTarget} and this run changes its settings (${changes.join('; ')}); to move to a new release and keep them, use \`tug control upgrade\``, ); } @@ -144,11 +154,11 @@ interface UpgradeOpts { } /** The control's own version, retried while the container finishes starting; undefined without a credential or an answer. */ -async function waitForControlVersion(): Promise { - if (!(await loadCfg()).credential) return undefined; +async function waitForControlVersion(rt: CliRuntime): Promise { + if (!loadCfg(rt).credential) return undefined; for (let i = 0; i < 15; i++) { try { - return (await request<{ v: string }>('GET', '/api/v1/version')).v; + return (await request<{ v: string }>(rt, 'GET', '/api/v1/version')).v; } catch { await new Promise((r) => setTimeout(r, 1000)); } @@ -163,10 +173,11 @@ async function waitForControlVersion(): Promise { * the CA is compared before and after. */ export async function runControlUpgrade( + rt: CliRuntime, sshTargetArg: string | undefined, o: UpgradeOpts, ): Promise { - const cfg = await loadCfg(); + const cfg = loadCfg(rt); const sshTarget = sshTargetArg ?? cfg.controlSsh; if (!sshTarget) throw new Error( @@ -180,11 +191,15 @@ export async function runControlUpgrade( ); const image = o.rollback ? ROLLBACK_TAG - : resolveImage(o.image ?? (o.to ? defaultImage(o.to) : undefined), o.buildLocalImage); - if (!o.rollback) assertImagePublished(image); - return withProgress(`Upgrading control on ${sshTarget}`, async (progress) => { + : resolveImage( + o.image ?? (o.to ? defaultImage(o.to) : undefined), + o.buildLocalImage, + rt.version, + ); + if (!o.rollback) assertPublished(rt, image); + return withProgress(rt, `Upgrading control on ${sshTarget}`, async (progress) => { progress.stage(`Reading the control installation on ${sshTarget}`); - const inspection = await runCapture('ssh', ['--', sshTarget, inspectControlScript]).catch( + const inspection = await runCapture(rt, 'ssh', ['--', sshTarget, inspectControlScript]).catch( (e: unknown) => { if (e instanceof SshHostKeyError) throw e; throw new Error( @@ -194,16 +209,20 @@ export async function runControlUpgrade( }, ); const current = parseControlInspect(inspection); - if (o.rollback) await runCapture('ssh', ['--', sshTarget, rollbackImageScript]); - const targetId = parseImageId(await runCapture('ssh', ['--', sshTarget, imageIdScript(image)])); + if (o.rollback) await runCapture(rt, 'ssh', ['--', sshTarget, rollbackImageScript]); + const targetId = parseImageId( + await runCapture(rt, 'ssh', ['--', sshTarget, imageIdScript(image)]), + ); if (alreadyRunning(current.imageId, targetId, o.force) && !o.buildLocalImage) { - console.error( + err( + rt, `control on ${sshTarget} already runs ${image}; nothing to do (--force recreates it)`, ); - print({ ok: true, sshTarget, image, upgraded: false }); + print(rt, { ok: true, sshTarget, image, upgraded: false }); return true; } - console.error( + err( + rt, [ o.rollback ? 'Control rollback plan' : 'Control upgrade plan', ` host: ${sshTarget}`, @@ -222,51 +241,55 @@ export async function runControlUpgrade( ].join('\n'), ); if ( - canPrompt() && + canPrompt(rt) && !o.yes && - !(await confirm(`${o.rollback ? 'Roll back' : 'Upgrade'} control?`)) + !(await confirm(rt, `${o.rollback ? 'Roll back' : 'Upgrade'} control?`)) ) throw new Error('cancelled; nothing was changed'); progress.stage(`Checking control host ${sshTarget}`); - await preflightRemote(sshTarget, { + await preflightRemote(rt, sshTarget, { ports: [...new Set(current.bindings.map(({ port }) => port))], minDiskMb: 2048, progress, }); - const runImage = o.buildLocalImage ? await transferTugImage(sshTarget, image, progress) : image; + const runImage = o.buildLocalImage + ? await transferTugImage(rt, sshTarget, image, progress) + : image; progress.stage(`Checking control data on ${sshTarget}`); // The guard runs first: on a legacy host it refuses with the migrate hint before anything creates the volume. - await runStep('ssh', ['--', sshTarget, controlGuardScript(runImage)], { progress }); + await runStep(rt, 'ssh', ['--', sshTarget, controlGuardScript(runImage)], { progress }); // Read by image ID: the running container's tag may since name another image, and the ID is always on the host. const before = fingerprintPem( - await runCapture('ssh', ['--', sshTarget, readControlCaScript(current.imageId)]), + await runCapture(rt, 'ssh', ['--', sshTarget, readControlCaScript(current.imageId)]), ); const runImageId = parseImageId( - await runCapture('ssh', ['--', sshTarget, imageIdScript(runImage)]), + await runCapture(rt, 'ssh', ['--', sshTarget, imageIdScript(runImage)]), ); if (!o.rollback && rollbackTagNeeded(current.imageId, runImageId)) { progress.stage(`Keeping ${current.image} as ${ROLLBACK_TAG}`); - await runStep('ssh', ['--', sshTarget, rollbackTagScript(current.imageId)], { progress }); + await runStep(rt, 'ssh', ['--', sshTarget, rollbackTagScript(current.imageId)], { progress }); } progress.stage(`Replacing control on ${sshTarget}`); - await installControlContainer(sshTarget, { ...current, image: runImage }, progress); + await installControlContainer(rt, sshTarget, { ...current, image: runImage }, progress); const after = fingerprintPem( - await runCapture('ssh', ['--', sshTarget, readControlCaScript(runImage)]), + await runCapture(rt, 'ssh', ['--', sshTarget, readControlCaScript(runImage)]), ); if (after !== before) throw new Error( `control's CA changed from ${before} to ${after} during the upgrade; inspect /data/pki on ${sshTarget} before using it`, ); progress.stage('Waiting for control to answer'); - const version = await waitForControlVersion(); + const version = await waitForControlVersion(rt); if (!version) - console.error( + err( + rt, `control restarted but did not answer yet (or no credential is configured); check \`tug doctor\` and \`docker logs ${CONTROL_CONTAINER}\` on ${sshTarget}`, ); - console.error( + err( + rt, `control now runs ${runImage}${version ? ` (version ${version})` : ''}; match the agents next with \`tug node upgrade --all\``, ); - print({ + print(rt, { ok: true, sshTarget, image: runImage, @@ -278,7 +301,7 @@ export async function runControlUpgrade( } /** `control setup`, also registered as the top-level shortcut `setup`. */ -function addSetup(parent: Command, description: string): void { +function addSetup(rt: CliRuntime, parent: Command, description: string): void { parent .command('setup ') .description(description) @@ -315,26 +338,29 @@ function addSetup(parent: Command, description: string): void { ) .option('-y, --yes', 'do not ask for confirmation in a terminal') .action(async (sshTarget: string, o: SetupOpts, command: Command) => { - const cfg = await loadCfg(); + const cfg = loadCfg(rt); if (!o.import && !o.credentialOut) throw new Error('--no-import needs --credential-out, or the root credential would be lost'); // The control URL clients use: --control-url, TUG_CONTROL_URL or the config's controlUrl, else the SSH target's host // and the published port. Clients verify a name generated from the CA, so this is only an address. const controlUrl = cfg.requestedControlUrl ?? defaultControlUrl(sshTarget, o.port); - console.error( + err( + rt, `control URL: ${controlUrl} (${cfg.requestedControlUrl ? 'from --control-url, TUG_CONTROL_URL or the config file' : 'from the SSH target and --port'}); clients connect there by default`, ); - const interactive = canPrompt(); + const interactive = canPrompt(rt); let missingDocker = false; - if (!o.installDocker && interactive && !hostHasDocker(sshTarget)) { + if (!o.installDocker && interactive && !hostHasDocker(rt, sshTarget)) { missingDocker = true; o.installDocker = await confirm( + rt, `Docker is not installed on ${sshTarget}. Install it now (needs root)?`, ); } - const image = resolveImage(o.image, o.buildLocalImage); - assertImagePublished(image); - console.error( + const image = resolveImage(o.image, o.buildLocalImage, rt.version); + assertPublished(rt, image); + err( + rt, [ 'Control plan', ` host: ${sshTarget}`, @@ -345,33 +371,34 @@ function addSetup(parent: Command, description: string): void { ` credential: ${[o.import ? 'imported into the local config' : '', o.credentialOut ? `written to ${o.credentialOut}` : ''].filter(Boolean).join(' and ')}`, ].join('\n'), ); - if (interactive && !o.yes && !(await confirm('Install the control plane?'))) + if (interactive && !o.yes && !(await confirm(rt, 'Install the control plane?'))) throw new Error('cancelled; nothing was changed'); - return withProgress(`Preparing control on ${sshTarget}`, async (progress) => { + return withProgress(rt, `Preparing control on ${sshTarget}`, async (progress) => { if (o.installDocker) { progress.stage(`Installing Docker on ${sshTarget}`); - await bootstrapDocker(sshTarget, progress); + await bootstrapDocker(rt, sshTarget, progress); } progress.stage(`Checking control host ${sshTarget}`); - await preflightRemote(sshTarget, { + await preflightRemote(rt, sshTarget, { ports: [Number(o.port)], minDiskMb: 2048, progress, }); - await warnWhenSetupChangesInstall(sshTarget, { + await warnWhenSetupChangesInstall(rt, sshTarget, { controlUrl, port: Number(o.port), extraSans: o.extraSan, }); const runImage = o.buildLocalImage - ? await transferTugImage(sshTarget, image, progress) + ? await transferTugImage(rt, sshTarget, image, progress) : image; // Before anything is written: a control host that still keeps its data in the old directory must migrate first, // or a fresh control would create a second CA on an empty volume (--recover-root included). progress.stage(`Checking control data on ${sshTarget}`); - await runStep('ssh', ['--', sshTarget, controlGuardScript(runImage)], { progress }); + await runStep(rt, 'ssh', ['--', sshTarget, controlGuardScript(runImage)], { progress }); progress.stage(`Installing control on ${sshTarget}`); await installControlContainer( + rt, sshTarget, { image: runImage, @@ -384,10 +411,11 @@ function addSetup(parent: Command, description: string): void { // Upgrades never reissue root: fresh installs create it, `--recover-root` replaces its key. Output goes straight to files. const issue = `docker exec ${sh(CONTROL_CONTAINER)} node dist/main.js control issue-credential --name root --role admin${o.recoverRoot ? ' --replace' : ''}`; progress.stage(`Issuing root credential on ${sshTarget}`); - const out = await runProcess('ssh', ['--', sshTarget, issue], { capture: true }); + const out = await runProcess(rt, 'ssh', ['--', sshTarget, issue], { capture: true }); if (out.status !== 0) { if (!o.recoverRoot && /already used/.test(String(out.stderr))) - console.error( + err( + rt, 'control already has a root credential; upgrade complete (pass --recover-root to replace it)', ); else @@ -405,6 +433,7 @@ function addSetup(parent: Command, description: string): void { // Fail closed before any local write: a credential for a CA the control did not persist is the // control-rewrote-credentials incident exactly, and importing it silently breaks every later CLI call. const persisted = await runProcess( + rt, 'ssh', ['--', sshTarget, `docker exec ${sh(CONTROL_CONTAINER)} cat /data/pki/ca.crt`], { capture: true }, @@ -429,7 +458,8 @@ function addSetup(parent: Command, description: string): void { onDiskError = errMessage(e); } if (!onDiskFp) - console.error( + err( + rt, `note: skipped the CA-consistency check — could not read the control's persisted CA (${onDiskError})`, ); else if (issuedFp !== onDiskFp) @@ -437,18 +467,18 @@ function addSetup(parent: Command, description: string): void { `the issued root credential is signed by CA ${issuedFp}, but the control persisted CA ${onDiskFp}; refusing to write local state — inspect /data/pki on ${sshTarget}`, ); if (o.credentialOut) { - await writeFileDurable(o.credentialOut, text, 0o600); - console.error(`root credential written to ${o.credentialOut}`); + await writeFileDurable(resolvePath(rt, o.credentialOut), text, 0o600); + err(rt, `root credential written to ${o.credentialOut}`); } if (o.import) { const { controlUrl: connectUrl, project } = command.optsWithGlobals<{ controlUrl?: string; project?: string; }>(); - await importCredential(cfg, text, { controlUrl: connectUrl, project }); + await importCredential(rt, cfg, text, { controlUrl: connectUrl, project }); } } - print({ ok: true, sshTarget, url: controlUrl }); + print(rt, { ok: true, sshTarget, url: controlUrl }); }); }); } @@ -463,17 +493,19 @@ interface ContainerOpts { * back the state on disk (after `control restore`, the restored one). */ export async function runControlContainer( + rt: CliRuntime, action: 'stop' | 'restart', sshTargetArg: string | undefined, o: ContainerOpts, ): Promise { - const cfg = await loadCfg(); + const cfg = loadCfg(rt); const sshTarget = sshTargetArg ?? cfg.controlSsh; if (!sshTarget) throw new Error( `control ${action} needs the control host: pass or set controlSsh in ${cfg.file}`, ); - console.error( + err( + rt, [ action === 'stop' ? 'Control stop plan' : 'Control restart plan', ` host: ${sshTarget}`, @@ -487,30 +519,33 @@ export async function runControlContainer( ].join('\n'), ); if ( - canPrompt() && + canPrompt(rt) && !o.yes && - !(await confirm(`${action === 'stop' ? 'Stop' : 'Restart'} control?`)) + !(await confirm(rt, `${action === 'stop' ? 'Stop' : 'Restart'} control?`)) ) throw new Error('cancelled; nothing was changed'); await withProgress( + rt, `${action === 'stop' ? 'Stopping' : 'Restarting'} control on ${sshTarget}`, async (progress) => { await runStep( + rt, 'ssh', ['--', sshTarget, action === 'stop' ? stopControlScript : restartControlScript], { progress }, ); if (action === 'stop') { - print({ ok: true, sshTarget, container: CONTROL_CONTAINER, stopped: true }); + print(rt, { ok: true, sshTarget, container: CONTROL_CONTAINER, stopped: true }); return; } progress.stage('Waiting for control to answer'); - const version = await waitForControlVersion(); + const version = await waitForControlVersion(rt); if (!version) - console.error( + err( + rt, `control restarted but did not answer yet (or no credential is configured); check \`tug doctor\` and \`docker logs ${CONTROL_CONTAINER}\` on ${sshTarget}`, ); - print({ + print(rt, { ok: true, sshTarget, container: CONTROL_CONTAINER, @@ -525,18 +560,17 @@ const RESTART_NOTE = 'control must restart to use the restored state: run `tug control restart []` (the SSH target defaults to controlSsh) with your original operator credential'; /** A restore that wants a restart names the command that does it. */ -function noteRestart(result: unknown): void { - if ((result as { restartRequired?: boolean } | null)?.restartRequired) - console.error(RESTART_NOTE); +function noteRestart(rt: CliRuntime, result: unknown): void { + if ((result as { restartRequired?: boolean } | null)?.restartRequired) err(rt, RESTART_NOTE); } -export function registerControl(program: Command): void { +export function registerControl(rt: CliRuntime, program: Command): void { const description = 'install the control plane on a Docker-capable host over SSH and import the root credential into the local config; it listens for mTLS only, so front it with TCP passthrough rather than a terminating proxy'; const control = program .command('control') .description('install, back up and restore the control plane'); - addSetup(control, description); + addSetup(rt, control, description); control .command('upgrade [sshTarget]') .description( @@ -555,7 +589,7 @@ export function registerControl(program: Command): void { .option('--force', 'recreate the container even when it already runs the target image') .option('-y, --yes', 'do not ask for confirmation in a terminal') .action(async (sshTarget: string | undefined, o: UpgradeOpts) => { - if (!(await runControlUpgrade(sshTarget, o))) process.exitCode = 1; + if (!(await runControlUpgrade(rt, sshTarget, o))) rt.exitCode = 1; }); control .command('stop [sshTarget]') @@ -564,7 +598,7 @@ export function registerControl(program: Command): void { ) .option('-y, --yes', 'do not ask for confirmation in a terminal') .action(async (sshTarget: string | undefined, o: ContainerOpts) => - runControlContainer('stop', sshTarget, o), + runControlContainer(rt, 'stop', sshTarget, o), ); control .command('restart [sshTarget]') @@ -573,7 +607,7 @@ export function registerControl(program: Command): void { ) .option('-y, --yes', 'do not ask for confirmation in a terminal') .action(async (sshTarget: string | undefined, o: ContainerOpts) => - runControlContainer('restart', sshTarget, o), + runControlContainer(rt, 'restart', sshTarget, o), ); control .command('migrate ') @@ -581,15 +615,18 @@ export function registerControl(program: Command): void { `move the control data of a control plane installed before it lived in a Docker volume from ${LEGACY_CONTROL_DIR} into the ${CONTROL_VOLUME} volume and restart control on it, keeping its image, URL and port. Run it before the next control setup on such a host, which refuses until then`, ) .action(async (sshTarget: string) => - withProgress(`Migrating control data on ${sshTarget}`, async (progress) => { - await runStep('ssh', ['--', sshTarget, controlMigrateScript(STAGE_MARKER)], { progress }); - console.error( + withProgress(rt, `Migrating control data on ${sshTarget}`, async (progress) => { + await runStep(rt, 'ssh', ['--', sshTarget, controlMigrateScript(STAGE_MARKER)], { + progress, + }); + err( + rt, `${LEGACY_CONTROL_DIR} is no longer used; remove it on ${sshTarget} once control is confirmed healthy (it holds a copy of the master key and the CA)`, ); - print({ ok: true, sshTarget, volume: CONTROL_VOLUME, leftover: CONTROL_LEFTOVERS }); + print(rt, { ok: true, sshTarget, volume: CONTROL_VOLUME, leftover: CONTROL_LEFTOVERS }); }), ); - addSetup(program, 'shortcut for `tug control setup`'); + addSetup(rt, program, 'shortcut for `tug control setup`'); const backup = control .command('backup') .description( @@ -617,31 +654,39 @@ export function registerControl(program: Command): void { if (!archive) { // Only an archive has build images, so --no-images must not quietly turn this into one. if (!o.images) throw new Error('--no-images applies to an archive; add --local or -o'); - return withProgress('Storing control-plane backup in the backup destination', async () => - print(await request('POST', '/api/v1/control/backups/run', { toDestination: true })), + return withProgress( + rt, + 'Storing control-plane backup in the backup destination', + async () => + print( + rt, + await request(rt, 'POST', '/api/v1/control/backups/run', { toDestination: true }), + ), ); } - return withProgress('Creating control-plane backup', async (progress) => { + return withProgress(rt, 'Creating control-plane backup', async (progress) => { // Refuse before the backup exists on control when the chosen file is already there. - if (o.output && (await fsp.stat(o.output).catch(() => null))) + if (o.output && (await fsp.stat(resolvePath(rt, o.output)).catch(() => null))) throw new Error(`${o.output} already exists; choose another file with -o`); const result = await request<{ backupId: string; artifactRef: string; state: string; images: boolean; - }>('POST', '/api/v1/control/backups/run', { images: o.images }); - if (!o.download && !o.output) return print(result); - const file = path.resolve(o.output ?? `tug-control-backup-${result.backupId}.tar.gz`); + }>(rt, 'POST', '/api/v1/control/backups/run', { images: o.images }); + if (!o.download && !o.output) return print(rt, result); + const file = resolvePath(rt, o.output ?? `tug-control-backup-${result.backupId}.tar.gz`); progress.stage(`Downloading the archive to ${file}`); await download( + rt, `/api/v1/control/backups/${encodeURIComponent(result.backupId)}/download`, file, ); - console.error( + err( + rt, `Saved ${file}: ${result.images ? 'with' : 'without'} build images, no workload volumes. It contains the master key and the CA private key, so store it encrypted. A copy also stays on control at ${result.artifactRef}; delete it there when you no longer need it.`, ); - print({ ...result, downloadedTo: file, serverCopy: result.artifactRef }); + print(rt, { ...result, downloadedTo: file, serverCopy: result.artifactRef }); }); }, ); @@ -652,29 +697,30 @@ export function registerControl(program: Command): void { ) .option('--json', 'print the full result as JSON') .action(async (o: { json?: boolean }) => { - const listing = await request('GET', '/api/v1/control/backups'); - if (o.json) return print(listing); - console.log( - `repository: ${listing.repository ?? 'none (no backup destination is configured)'}`, - ); - console.log(listing.local.length ? 'on the control host:' : 'on the control host: none'); + const listing = await request(rt, 'GET', '/api/v1/control/backups'); + if (o.json) return print(rt, listing); + out(rt, `repository: ${listing.repository ?? 'none (no backup destination is configured)'}`); + out(rt, listing.local.length ? 'on the control host:' : 'on the control host: none'); for (const copy of listing.local) - console.log( + out( + rt, ` ${copy.id}\t${copy.createdAt}\t${copy.onDisk ? formatBytes(copy.sizeBytes) : 'gone from disk'}\t${copy.images === false ? 'no images' : copy.images ? 'with images' : '-'}\t${copy.path ?? '-'}`, ); if (!listing.remote) return; if (listing.remote.state === 'error') { - console.log(`in the destination: unreadable: ${listing.remote.error}`); - process.exitCode = 1; + out(rt, `in the destination: unreadable: ${listing.remote.error}`); + rt.exitCode = 1; return; } - console.log( + out( + rt, listing.remote.snapshots.length ? 'in the destination (newest first; each holds the database, CA and master key, never workload volumes):' : 'in the destination: none yet', ); for (const snapshot of listing.remote.snapshots) - console.log( + out( + rt, ` ${snapshot.shortId}\t${snapshot.time}\t${formatBytes(snapshot.sizeBytes ?? null)}\t${snapshot.tags.includes('images:none') ? 'no images' : 'images not recorded'}\t${snapshot.tags.filter((tag) => tag !== 'control' && tag !== 'images:none').join(' ')}`, ); }); @@ -725,18 +771,20 @@ export function registerControl(program: Command): void { throw new Error( '--from-file takes no archive path, --from-destination, --snapshot or --env', ); - if (!(await fsp.stat(o.fromFile).catch(() => null))) + if (!(await fsp.stat(resolvePath(rt, o.fromFile)).catch(() => null))) throw new Error(`${o.fromFile} does not exist`); return withProgress( + rt, verify ? 'Verifying control-plane backup' : 'Restoring control-plane backup', async () => { const result = await upload( + rt, `/api/v1/control/restore?${verify ? 'verify=1' : 'confirm=1'}`, o.fromFile!, ); - if (verify) console.error(PREVIEW_NOTE); - noteRestart(result); - print(result); + if (verify) err(rt, PREVIEW_NOTE); + noteRestart(rt, result); + print(rt, result); }, ); } @@ -751,19 +799,19 @@ export function registerControl(program: Command): void { // missing value is still read from stdin after the credential values, as `backup destination set` reads them. let values: Record | undefined; if (o.fromDestination && o.passwordStdin) { - const missing = o.env.filter((name) => process.env[name] === undefined); + const missing = o.env.filter((name) => rt.env[name] === undefined); if (missing.length) throw new Error( `with --password-stdin, set ${missing.join(', ')} in the environment: stdin carries only the password`, ); - const password = (await readStdin()).split(/\r?\n/).find((line) => line.length > 0); + const password = (await readStdin(rt)).split(/\r?\n/).find((line) => line.length > 0); if (!password) throw new Error('expected the control password on stdin'); values = { - ...Object.fromEntries(o.env.map((name) => [name, process.env[name]!])), + ...Object.fromEntries(o.env.map((name) => [name, rt.env[name]!])), [CONTROL_PASSWORD_VARIABLE]: password, }; } else if (o.fromDestination) { - values = await readEnvValues([...o.env, CONTROL_PASSWORD_VARIABLE]); + values = await readEnvValues(rt, [...o.env, CONTROL_PASSWORD_VARIABLE]); } const fromDestination = o.fromDestination && values @@ -775,17 +823,18 @@ export function registerControl(program: Command): void { } : undefined; return withProgress( + rt, verify ? 'Verifying control-plane backup' : 'Restoring control-plane backup', async () => { - const result = await request('POST', '/api/v1/control/restore', { + const result = await request(rt, 'POST', '/api/v1/control/restore', { artifactRef, fromDestination, confirm: Boolean(o.confirm), verify, }); - if (verify) console.error(PREVIEW_NOTE); - noteRestart(result); - print(result); + if (verify) err(rt, PREVIEW_NOTE); + noteRestart(rt, result); + print(rt, result); }, ); }, diff --git a/src/cli/commands/credential.ts b/src/cli/commands/credential.ts index 6d0acd0..0ae0f0a 100644 --- a/src/cli/commands/credential.ts +++ b/src/cli/commands/credential.ts @@ -1,11 +1,13 @@ -import { selectMany } from '../selection.ts'; +import { selectMany, terminalSelection } from '../selection.ts'; import { selectResource } from './selection.ts'; import type { Command } from 'commander'; import { Option } from 'commander'; import { ROLES } from '../../roles.ts'; import { collectList, print, request } from './context.ts'; +import { err } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; -export function registerCredential(program: Command): void { +export function registerCredential(rt: CliRuntime, program: Command): void { const credential = program .command('credential') .description('create, list and revoke operator credentials'); @@ -47,6 +49,7 @@ export function registerCredential(program: Command): void { 'Select projects (choose all projects alone for unrestricted access)', async () => { const { projects } = await request<{ projects: { name: string }[] }>( + rt, 'GET', '/api/v1/projects', ); @@ -55,22 +58,24 @@ export function registerCredential(program: Command): void { ...projects.map((project) => ({ value: project.name, label: project.name })), ]; }, + terminalSelection(rt), ); if (o.project.includes('*')) { if (o.project.length !== 1) throw new Error('all projects must be selected alone'); o.project = []; } } - const created = await request('POST', '/api/v1/credentials', { + const created = await request(rt, 'POST', '/api/v1/credentials', { name, role: o.role, projects: o.project.length ? o.project : undefined, expiresInSeconds: o.expiresInDays ? Number(o.expiresInDays) * 86400 : undefined, }); - console.error( + err( + rt, 'Store this credential now (for example as the TUG_CREDENTIAL secret in CI); it is not shown again. Replace one by creating a new name, verifying it, then revoking the old name.', ); - print(created); + print(rt, created); }, ); credential @@ -78,7 +83,7 @@ export function registerCredential(program: Command): void { .description( 'list operator credentials with role, projects, expiry and last use; secrets are never shown', ) - .action(async () => print(await request('GET', '/api/v1/credentials'))); + .action(async () => print(rt, await request(rt, 'GET', '/api/v1/credentials'))); credential .command('revoke [name]') .description( @@ -86,9 +91,11 @@ export function registerCredential(program: Command): void { ) .action(async (name: string) => print( + rt, await request( + rt, 'DELETE', - `/api/v1/credentials/${encodeURIComponent(await selectResource(name, 'credentials'))}`, + `/api/v1/credentials/${encodeURIComponent(await selectResource(rt, name, 'credentials'))}`, ), ), ); diff --git a/src/cli/commands/deploy.ts b/src/cli/commands/deploy.ts index 94cd305..6ea26dd 100644 --- a/src/cli/commands/deploy.ts +++ b/src/cli/commands/deploy.ts @@ -4,7 +4,12 @@ import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; import type { Command } from 'commander'; -import { createLocalBuildSnapshot, createSourceArchive, prepareLocalImages } from '../build.ts'; +import { + createLocalBuildSnapshot, + createSourceArchive, + localBuildDependencies, + prepareLocalImages, +} from '../build.ts'; import { deploymentsSharingLabel } from '../status.ts'; import { createProgress, withProgress } from '../progress.ts'; import { canPrompt } from '../prompt.ts'; @@ -30,14 +35,16 @@ import { waitForCommand, waitForDeployment, } from './context.ts'; -import type { CommonOpts, DeployResponse, WaitOpts } from './context.ts'; +import type { CommonOpts, ControlGet, DeployResponse, WaitOpts } from './context.ts'; +import { out, err, resolvePath } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; /** * The project's secrets and variable values, read one request after the other. Two requests in flight from one CLI * process made control reset the second TLS connection (`ECONNRESET`), so these are sequential on purpose. */ export async function loadDeployValues( - get: typeof request, + get: ControlGet, project: string, ): Promise<{ secrets: { name: string }[]; @@ -54,11 +61,11 @@ export async function loadDeployValues( return { secrets, vars }; } -async function makeContext(): Promise { - const cfg = await loadCfg(); +async function makeContext(rt: CliRuntime): Promise { + const cfg = loadCfg(rt); const tmp = path.join(os.tmpdir(), `tug-${Date.now()}.tgz`); try { - await createSourceArchive(process.cwd(), tmp, [ + await createSourceArchive(rt.cwd, tmp, [ cfg.file, cfg.localFile, ...(cfg.credentialFile ? [cfg.credentialFile] : []), @@ -71,7 +78,7 @@ async function makeContext(): Promise { } /** The first conventional Compose file name in the working directory; `docker-compose.yml` when none exists. */ -export function defaultComposeFile(cwd = process.cwd()): string { +export function defaultComposeFile(rt: CliRuntime, cwd = rt.cwd): string { const names = ['compose.yaml', 'compose.yml', 'docker-compose.yaml', 'docker-compose.yml']; return names.find((name) => existsSync(path.join(cwd, name))) ?? 'docker-compose.yml'; } @@ -86,12 +93,12 @@ export async function composeName(file: string): Promise { * Ids of earlier deployments of the project that carry the same version label as this one, found from control's recent * deployments. A failed lookup is no hint: the summary still shows the deployment id. */ -async function sharedLabel(response: DeployResponse): Promise { +async function sharedLabel(rt: CliRuntime, response: DeployResponse): Promise { try { const state = response.desiredState as { project?: string; version?: string } | undefined; const { deployments } = await request<{ deployments: { id: string; version: string; project_id?: string }[]; - }>('GET', '/api/v1/status'); + }>(rt, 'GET', '/api/v1/status'); return deploymentsSharingLabel( deployments, response.deployment.id, @@ -103,11 +110,11 @@ async function sharedLabel(response: DeployResponse): Promise { } } -export function registerDeploy(program: Command): void { +export function registerDeploy(rt: CliRuntime, program: Command): void { const deploy = program .command('deploy') .description('deploy the Compose project, or cancel a deployment with `deploy cancel `') - .option('-f, --file ', 'compose file', defaultComposeFile()) + .option('-f, --file ', 'compose file', defaultComposeFile(rt)) .option('--version ', 'display version (default: git-)') .option('--build-local', 'build application images locally and upload them without source') .option( @@ -154,15 +161,18 @@ export function registerDeploy(program: Command): void { dryRun?: boolean; }, ) => { - const progress = createProgress(); + const progress = createProgress(rt); try { progress.stage('Preparing deployment'); - const cfg = await loadCfg(); + const cfg = loadCfg(rt); const project = o.project || cfg.project || 'site'; // Every ${NAME} comes from control (secrets as sentinels the agent fills in, variables as their values), from // --var, or from the default written in the file. The shell and .env of this machine are never read. const flags = parseVarFlags(o.var ?? []); - const { secrets, vars } = await loadDeployValues(request, project); + const { secrets, vars } = await loadDeployValues( + (method, route) => request(rt, method, route), + project, + ); const secretNames = secrets.map((secret) => secret.name); const variables = new Map( vars.map((row) => [row.name, { version: row.version, value: row.value }]), @@ -174,32 +184,32 @@ export function registerDeploy(program: Command): void { ); } for (const note of await ignoredSourceNotes( + rt.cwd, o.file, new Set([...secretNames, ...variables.keys()]), + rt.env, )) - console.error(note); + err(rt, note); const known = () => new Set([...secretNames, ...variables.keys(), ...Object.keys(flags)]); - const missing = await findMissingValues(o.file, known()); + const missing = await findMissingValues(rt.cwd, o.file, known()); if (missing.length) { - if (o.dryRun || !canPrompt()) + if (o.dryRun || !canPrompt(rt)) throw new Error( missingValuesMessage( o.file, - await fs.readFile(o.file, 'utf8').catch(() => ''), + await fs.readFile(resolvePath(rt, o.file), 'utf8').catch(() => ''), missing, Boolean(o.dryRun), ), ); - console.error( - `Values not set on control for project ${project}: ${missing.join(', ')}`, - ); + err(rt, `Values not set on control for project ${project}: ${missing.join(', ')}`); // Only names that do not exist yet are stored, so an existing value is never overwritten. - for (const [name, entry] of Object.entries(await promptForValues(missing))) { + for (const [name, entry] of Object.entries(await promptForValues(rt, missing))) { if (entry.kind === 'secret') { - await request('POST', '/api/v1/secrets', { project, name, value: entry.value }); + await request(rt, 'POST', '/api/v1/secrets', { project, name, value: entry.value }); secretNames.push(name); } else { - const stored = await request<{ version: number }>('POST', '/api/v1/vars', { + const stored = await request<{ version: number }>(rt, 'POST', '/api/v1/vars', { project, name, value: entry.value, @@ -208,7 +218,7 @@ export function registerDeploy(program: Command): void { } } } - const values = await describeValues(o.file, { + const values = await describeValues(rt.cwd, o.file, { secrets: new Set(secretNames), vars: variables, flags, @@ -216,29 +226,31 @@ export function registerDeploy(program: Command): void { const referenced = new Set(values.map((value) => value.name)); for (const name of Object.keys(flags)) if (!referenced.has(name)) - console.error(`warning: --var ${name} is not referenced in ${o.file}; it is ignored`); - console.error(`Values: ${summarizeValues(values)}`); + err(rt, `warning: --var ${name} is not referenced in ${o.file}; it is ignored`); + err(rt, `Values: ${summarizeValues(values)}`); const movePayload = o.move.length ? { moves: o.move } : {}; - const declared = await composeName(o.file); + const declared = await composeName(resolvePath(rt, o.file)); if (declared && declared !== project) - console.error( + err( + rt, `warning: ${o.file} is named ${declared} but the Tug project is ${project}; secrets, backups and restores are scoped to the Tug project (set project: ${declared} in tug.yml, or pass --project)`, ); - const compose = await normalizeCompose(o.file, secretNames, { + const compose = await normalizeCompose(resolvePath(rt, o.file), secretNames, { project, composeCli: o.composeCli, + hostEnv: rt.env, vars: { ...Object.fromEntries([...variables].map(([n, v]) => [n, v.value])), ...flags }, profiles: o.profile, }); if (o.dryRun) { // Reading the file is part of the dry run: an env_file or an unsupported construct fails here too. - console.log(formatValuesTable(values)); + out(rt, formatValuesTable(values)); // The checks a deploy makes against other projects (a host port another project already publishes on a node). - await request('POST', '/api/v1/deployments/check', { project, compose }); - console.error('No host-port clash with another project on any node.'); + await request(rt, 'POST', '/api/v1/deployments/check', { project, compose }); + err(rt, 'No host-port clash with another project on any node.'); return; } - for (const warning of bindMountWarnings(compose)) console.error(warning); + for (const warning of bindMountWarnings(compose)) err(rt, warning); const version = o.version || `git-${composeHash(compose)}`; let response: DeployResponse; if (o.buildLocal) { @@ -247,17 +259,17 @@ export function registerDeploy(program: Command): void { const form = new FormData(); progress.stage('Preparing local build snapshot'); const source = Object.values(compose.services).some((service) => service.build) - ? await createLocalBuildSnapshot(process.cwd(), directory, [ + ? await createLocalBuildSnapshot(rt.cwd, directory, [ cfg.file, cfg.localFile, ...(cfg.credentialFile ? [cfg.credentialFile] : []), ]) - : process.cwd(); + : rt.cwd; const localImages = await prepareLocalImages( compose, source, directory, - undefined, + localBuildDependencies(rt, (message) => err(rt, message)), progress.stage, ); for (const { field } of localImages) @@ -271,13 +283,19 @@ export function registerDeploy(program: Command): void { JSON.stringify({ project, version, compose, values, localImages, ...movePayload }), ); progress.stage('Uploading images and preparing deployment on control'); - response = await request('POST', '/api/v1/deployments', form, true); + response = await request( + rt, + 'POST', + '/api/v1/deployments', + form, + true, + ); } finally { await fs.rm(directory, { recursive: true, force: true }); } } else if (Object.values(compose.services).some((service) => service.build)) { progress.stage('Archiving source for remote build'); - const tarball = await makeContext(); + const tarball = await makeContext(rt); try { const form = new FormData(); form.append( @@ -286,13 +304,19 @@ export function registerDeploy(program: Command): void { ); form.append('context', await openAsBlob(tarball), 'context.tgz'); progress.stage('Uploading source and building images on control'); - response = await request('POST', '/api/v1/deployments', form, true); + response = await request( + rt, + 'POST', + '/api/v1/deployments', + form, + true, + ); } finally { await fs.rm(tarball, { force: true }); } } else { progress.stage('Resolving images and preparing deployment on control'); - response = await request('POST', '/api/v1/deployments', { + response = await request(rt, 'POST', '/api/v1/deployments', { project, version, compose, @@ -303,13 +327,14 @@ export function registerDeploy(program: Command): void { if (o.wait) { progress.stage(`Deployment ${response.deployment.id}: ${response.deployment.state}`); response.deployment = await waitForDeployment( + rt, response.deployment.id, Number(o.timeout), (deployment) => progress.stage(`Deployment ${deployment.id}: ${deployment.state}`), ); } - const sharedWith = o.json ? [] : await sharedLabel(response); - printResult(o.json, response, (value) => formatDeployment(value, sharedWith)); + const sharedWith = o.json ? [] : await sharedLabel(rt, response); + printResult(rt, o.json, response, (value) => formatDeployment(value, sharedWith)); } finally { progress.stop(); } @@ -320,9 +345,11 @@ export function registerDeploy(program: Command): void { .description('cancel a deployment that has not finished') .action(async (id: string) => print( + rt, await request( + rt, 'POST', - `/api/v1/deployments/${encodeURIComponent(await selectDeployment(id))}/cancel`, + `/api/v1/deployments/${encodeURIComponent(await selectDeployment(rt, id))}/cancel`, {}, ), ), @@ -336,21 +363,22 @@ export function registerDeploy(program: Command): void { .option('--timeout ', 'wait timeout', '300') .option('--json', 'print the full result, including the desired state, as JSON') .action(async (o: CommonOpts & WaitOpts & { force?: boolean; json?: boolean }) => { - return withProgress('Preparing rollback on control', async (progress) => { - const response = await request('POST', '/api/v1/rollback', { - project: await projectOf(o), + return withProgress(rt, 'Preparing rollback on control', async (progress) => { + const response = await request(rt, 'POST', '/api/v1/rollback', { + project: projectOf(rt, o), force: Boolean(o.force), }); if (o.wait) { progress.stage(`Deployment ${response.deployment.id}: ${response.deployment.state}`); response.deployment = await waitForDeployment( + rt, response.deployment.id, Number(o.timeout), (deployment) => progress.stage(`Deployment ${deployment.id}: ${deployment.state}`), ); } - const sharedWith = o.json ? [] : await sharedLabel(response); - printResult(o.json, response, (value) => formatDeployment(value, sharedWith)); + const sharedWith = o.json ? [] : await sharedLabel(rt, response); + printResult(rt, o.json, response, (value) => formatDeployment(value, sharedWith)); }); }); @@ -368,15 +396,17 @@ export function registerDeploy(program: Command): void { if (o.replicas && replicas) throw new Error('pass replicas positionally or with --replicas, not both'); replicas = replicas || o.replicas || ''; - const project = await projectOf(o); + const project = projectOf(rt, o); if (!/^[1-9]\d*$/.test(replicas)) throw new Error('replicas must be a positive integer'); - service = await selectService(service); + service = await selectService(rt, service); const result = await request<{ service: string; replicas: number; nodes: string[] }>( + rt, 'POST', '/api/v1/scale', { project, service, replicas: Number(replicas) }, ); printResult( + rt, o.json, result, (r) => @@ -390,12 +420,12 @@ export function registerDeploy(program: Command): void { .description('restart a service on every node that runs it') .option('--timeout ', 'wait timeout', '60') .action(async (svc: string, o: CommonOpts & { timeout: string }) => { - const project = await projectOf(o); - svc = await selectService(svc); - const created = await request('POST', '/api/v1/restart', { project, service: svc }); - const cmd = await waitForCommand(created.commandId, Number(o.timeout)); + const project = projectOf(rt, o); + svc = await selectService(rt, svc); + const created = await request(rt, 'POST', '/api/v1/restart', { project, service: svc }); + const cmd = await waitForCommand(rt, created.commandId, Number(o.timeout)); if (cmd.state === 'failed') throw new Error(JSON.parse(cmd.result_json || '{}').error || 'restart failed'); - print(cmd); + print(rt, cmd); }); } diff --git a/src/cli/commands/deploy.values.test.ts b/src/cli/commands/deploy.values.test.ts index 6ff813a..be31eb5 100644 --- a/src/cli/commands/deploy.values.test.ts +++ b/src/cli/commands/deploy.values.test.ts @@ -1,7 +1,7 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { loadDeployValues } from './deploy.ts'; -import type { request } from './context.ts'; +import type { ControlGet } from './context.ts'; test('deploy reads secrets and variables one request after the other, never both in flight', async () => { const events: string[] = []; @@ -16,7 +16,7 @@ test('deploy reads secrets and variables one request after the other, never both inFlight--; if (route.startsWith('/api/v1/secrets')) return { secrets: [{ name: 'API_KEY' }] }; return { vars: [{ name: 'GREETING', version: 1, value: 'hi' }] }; - }) as unknown as typeof request; + }) as unknown as ControlGet; const values = await loadDeployValues(get, 'site'); diff --git a/src/cli/commands/domain.test.ts b/src/cli/commands/domain.test.ts index 87a69fb..7505431 100644 --- a/src/cli/commands/domain.test.ts +++ b/src/cli/commands/domain.test.ts @@ -1,23 +1,18 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { execFile } from 'node:child_process'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { promisify } from 'node:util'; import { startMtlsControl } from '../../../tests/helpers.ts'; - -const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); +import { execCli } from '../../../tests/cli-inprocess.ts'; test('domain commands reach the control over mTLS and report its answers', async () => { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-domain-cli-')); const control = await startMtlsControl(dir); const run = (...args: string[]) => - exec(process.execPath, [entry, 'domain', ...args], { + execCli(['domain', ...args], { cwd: dir, env: { ...process.env, ...control.env, TUG_CREDENTIAL: '', TUG_PROJECT: 'site' }, - timeout: 60_000, }); try { assert.deepEqual( diff --git a/src/cli/commands/domain.ts b/src/cli/commands/domain.ts index 7d0b7b8..9a19fb9 100644 --- a/src/cli/commands/domain.ts +++ b/src/cli/commands/domain.ts @@ -1,8 +1,9 @@ import type { Command } from 'commander'; import { print, projectOf, request } from './context.ts'; import type { CommonOpts } from './context.ts'; +import type { CliRuntime } from '../runtime.ts'; -export function registerDomain(program: Command): void { +export function registerDomain(rt: CliRuntime, program: Command): void { const domain = program .command('domain') .description( @@ -16,8 +17,9 @@ export function registerDomain(program: Command): void { .requiredOption('--service ', 'the service whose ingress route serves the hostname') .action(async (host: string, o: CommonOpts & { service: string }) => print( - await request('POST', '/api/v1/domains', { - project: await projectOf(o), + rt, + await request(rt, 'POST', '/api/v1/domains', { + project: projectOf(rt, o), service: o.service, host, }), @@ -29,7 +31,8 @@ export function registerDomain(program: Command): void { .description('list the mapped domains of the project') .action(async (o: CommonOpts) => print( - await request('GET', `/api/v1/domains?project=${encodeURIComponent(await projectOf(o))}`), + rt, + await request(rt, 'GET', `/api/v1/domains?project=${encodeURIComponent(projectOf(rt, o))}`), ), ); domain @@ -37,9 +40,11 @@ export function registerDomain(program: Command): void { .description('stop serving a mapped domain') .action(async (host: string, o: CommonOpts) => print( + rt, await request( + rt, 'DELETE', - `/api/v1/domains/${encodeURIComponent(host)}?project=${encodeURIComponent(await projectOf(o))}`, + `/api/v1/domains/${encodeURIComponent(host)}?project=${encodeURIComponent(projectOf(rt, o))}`, ), ), ); diff --git a/src/cli/commands/hold.ts b/src/cli/commands/hold.ts index f7a6a5f..d7b08c5 100644 --- a/src/cli/commands/hold.ts +++ b/src/cli/commands/hold.ts @@ -2,8 +2,9 @@ import { selectHolds } from './selection.ts'; import type { Command } from 'commander'; import { print, projectOf, request } from './context.ts'; import type { CommonOpts } from './context.ts'; +import type { CliRuntime } from '../runtime.ts'; -export function registerHold(program: Command): void { +export function registerHold(rt: CliRuntime, program: Command): void { const hold = program .command('hold') .description('services a deploy stopped because their data moved to another node'); @@ -16,10 +17,11 @@ export function registerHold(program: Command): void { .action(async (services: string[], o: CommonOpts & { select?: boolean }) => { if (o.select && services.length) throw new Error('--select cannot be combined with explicit services'); - if (o.select) services = await selectHolds(); + if (o.select) services = await selectHolds(rt); return print( - await request('POST', '/api/v1/holds/release', { - project: await projectOf(o), + rt, + await request(rt, 'POST', '/api/v1/holds/release', { + project: projectOf(rt, o), services, }), ); diff --git a/src/cli/commands/host.test.ts b/src/cli/commands/host.test.ts index bd5b732..806483f 100644 --- a/src/cli/commands/host.test.ts +++ b/src/cli/commands/host.test.ts @@ -7,10 +7,11 @@ import { createHash } from 'node:crypto'; import * as tar from 'tar'; import { bootstrapCommand, dockerBootstrap, immutableLocalTag, transferTugImage } from './host.ts'; import { STAGE_MARKER } from '../process.ts'; +import { testRuntime } from '../../../tests/cli-runtime.ts'; test('runtime image transfer reports build, export, copy and load in order and cleans temporary archives', async () => { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-transfer-progress-')); - const previousPath = process.env.PATH; + const previousPath = process.env.PATH ?? ''; const stages: string[] = []; const commandsFile = path.join(dir, 'commands.jsonl'); try { @@ -39,8 +40,13 @@ if (cmd === 'docker' && args[0] === 'save') process.stdout.write(fs.readFileSync `; for (const cmd of ['ssh', 'docker', 'scp']) await fs.writeFile(path.join(dir, cmd), stub, { mode: 0o755 }); - process.env.PATH = dir + path.delimiter + previousPath; - const runTag = await transferTugImage('root@host', 'tug:local', (label) => stages.push(label)); + // The stubs are found through this run's PATH; this process's own is never touched. + const { rt } = testRuntime({ + env: { ...process.env, PATH: dir + path.delimiter + previousPath }, + }); + const runTag = await transferTugImage(rt, 'root@host', 'tug:local', (label) => + stages.push(label), + ); assert.equal( runTag, 'tug:local-0123456789ab', @@ -82,7 +88,7 @@ if (cmd === 'docker' && args[0] === 'save') process.stdout.write(fs.readFileSync }); stages.length = 0; await assert.rejects( - transferTugImage('root@host', 'tug:local', (label) => stages.push(label)), + transferTugImage(rt, 'root@host', 'tug:local', (label) => stages.push(label)), /exit 9/, 'failed builds must preserve the child exit error', ); @@ -92,8 +98,6 @@ if (cmd === 'docker' && args[0] === 'save') process.stdout.write(fs.readFileSync 'failed builds must not claim to export or transfer an image', ); } finally { - if (previousPath === undefined) delete process.env.PATH; - else process.env.PATH = previousPath; await fs.rm(dir, { recursive: true, force: true }); } }); diff --git a/src/cli/commands/host.ts b/src/cli/commands/host.ts index 1146966..fec1a7b 100644 --- a/src/cli/commands/host.ts +++ b/src/cli/commands/host.ts @@ -3,6 +3,7 @@ import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; import { saveImageArchive } from '../../images/artifacts.ts'; +import { assertImagePublished } from '../../images/image.ts'; import { AGENT_VOLUME } from '../migrate.ts'; import { controlPortCheck, localImageBuildArgs, shellQuote as sh } from '../install.ts'; import { LIST_ADDRESSES_COMMAND, parseAddressCandidates, sortCandidates } from '../onboarding.ts'; @@ -10,8 +11,10 @@ import type { AddressCandidate } from '../onboarding.ts'; import { runStep, sshHostKeyHint, STAGE_MARKER } from '../process.ts'; import type { StepProgress } from '../process.ts'; import { runCapture, templatesDir } from './context.ts'; +import type { CliRuntime } from '../runtime.ts'; export async function preflightRemote( + rt: CliRuntime, target: string, { controlUrl, @@ -54,7 +57,7 @@ export async function preflightRemote( const script = `set -e ${checks.map(([name, cmd, fix]) => `echo "preflight: ${name}"; (${cmd}) || { echo "FAILED ${name}: ${fix}" >&2; exit 20; }`).join('\n')} `; - await runStep('ssh', ['--', target, script], { progress }); + await runStep(rt, 'ssh', ['--', target, script], { progress }); } /** @@ -67,6 +70,7 @@ export function immutableLocalTag(imageTag: string, imageId: string): string { /** Builds the runtime image from the checkout, copies it to the host and returns the immutable tag to run. */ export async function transferTugImage( + rt: CliRuntime, target: string, imageTag: string, progressOrStage: StepProgress | ((label: string) => void), @@ -79,19 +83,22 @@ export async function transferTugImage( const archive = path.join(directory, 'image.tar.gz'); const remote = `/tmp/${path.basename(directory)}.tar.gz`; try { - const uname = await runCapture('ssh', ['--', target, 'uname -m']); + const uname = await runCapture(rt, 'ssh', ['--', target, 'uname -m']); stage(`Building Tug image ${imageTag}`); - await runStep('docker', localImageBuildArgs(imageTag, uname), { progress }); + await runStep(rt, 'docker', localImageBuildArgs(imageTag, uname), { progress }); const runTag = immutableLocalTag( imageTag, - (await runCapture('docker', ['image', 'inspect', '--format', '{{.Id}}', imageTag])).trim(), + ( + await runCapture(rt, 'docker', ['image', 'inspect', '--format', '{{.Id}}', imageTag]) + ).trim(), ); stage(`Exporting Tug image ${imageTag}`); - await saveImageArchive(imageTag, archive); + await saveImageArchive(imageTag, archive, rt.env); stage(`Transferring Tug image to ${target}`); - await runStep('scp', ['-q', '--', archive, `${target}:${remote}`], { progress }); + await runStep(rt, 'scp', ['-q', '--', archive, `${target}:${remote}`], { progress }); stage(`Loading Tug image on ${target}`); await runStep( + rt, 'ssh', [ '--', @@ -116,35 +123,60 @@ export function bootstrapCommand(script: string): string { } /** Installs Docker Engine over SSH. */ -export async function bootstrapDocker(target: string, progress?: StepProgress): Promise { - await runStep('ssh', ['--', target, bootstrapCommand(await dockerBootstrap())], { +export async function bootstrapDocker( + rt: CliRuntime, + target: string, + progress?: StepProgress, +): Promise { + await runStep(rt, 'ssh', ['--', target, bootstrapCommand(await dockerBootstrap())], { progress, }); } /** A probe that cannot get past ssh's host key check says so at once, instead of reading as "no Docker" or "no answer". */ -function probe(target: string, command: string) { +function probe(rt: CliRuntime, target: string, command: string) { const args = ['--', target, command]; - const result = spawnSync('ssh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }); + const result = spawnSync('ssh', args, { + encoding: 'utf8', + env: rt.env, + cwd: rt.cwd, + stdio: ['ignore', 'pipe', 'pipe'], + }); const hint = sshHostKeyHint('ssh', args, String(result.stderr ?? '')); if (hint) throw new Error(hint); return result; } +/** + * Fails before any host is touched when the published image does not exist yet; see `assertImagePublished`. The + * manifest is looked up with this run's environment, so a Docker on its PATH is the one that answers. + */ +export function assertPublished(rt: CliRuntime, image: string): void { + assertImagePublished(image, (ref) => { + const result = spawnSync('docker', ['manifest', 'inspect', ref], { + encoding: 'utf8', + timeout: 20_000, + env: rt.env, + cwd: rt.cwd, + }); + return { status: result.status, stderr: String(result.stderr ?? '') }; + }); +} + /** Whether the host already has a working Docker Engine. */ -export function hostHasDocker(target: string): boolean { - return probe(target, 'docker version >/dev/null 2>&1').status === 0; +export function hostHasDocker(rt: CliRuntime, target: string): boolean { + return probe(rt, target, 'docker version >/dev/null 2>&1').status === 0; } /** The host's short hostname, or undefined when it cannot be read. */ -export function remoteHostname(target: string): string | undefined { - const result = probe(target, 'hostname -s'); +export function remoteHostname(rt: CliRuntime, target: string): string | undefined { + const result = probe(rt, target, 'hostname -s'); return result.status === 0 ? String(result.stdout).trim() || undefined : undefined; } /** The host's global IPv4 addresses, private ones first; empty when the host cannot say. */ -export function discoverAddresses(target: string): AddressCandidate[] { - const result = probe(target, LIST_ADDRESSES_COMMAND); +export function discoverAddresses(rt: CliRuntime, target: string): AddressCandidate[] { + const result = probe(rt, target, LIST_ADDRESSES_COMMAND); return result.status === 0 ? sortCandidates(parseAddressCandidates(String(result.stdout))) : []; } diff --git a/src/cli/commands/image.ts b/src/cli/commands/image.ts index deeb45a..3600a98 100644 --- a/src/cli/commands/image.ts +++ b/src/cli/commands/image.ts @@ -1,7 +1,8 @@ import type { Command } from 'commander'; import { print, request } from './context.ts'; +import type { CliRuntime } from '../runtime.ts'; -export function registerImage(program: Command): void { +export function registerImage(rt: CliRuntime, program: Command): void { const image = program.command('image').description('manage the build archives kept on control'); image .command('prune') @@ -12,7 +13,8 @@ export function registerImage(program: Command): void { .option('--dry-run', 'list what would be deleted without deleting it') .action(async (o: { keep: string; dryRun?: boolean }) => print( - await request('POST', '/api/v1/images/prune', { + rt, + await request(rt, 'POST', '/api/v1/images/prune', { keep: Number(o.keep), dryRun: Boolean(o.dryRun), }), diff --git a/src/cli/commands/import-values.read.test.ts b/src/cli/commands/import-values.read.test.ts index d983ea4..e137164 100644 --- a/src/cli/commands/import-values.read.test.ts +++ b/src/cli/commands/import-values.read.test.ts @@ -1,7 +1,7 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { loadExistingNames } from './import-values.ts'; -import type { request } from './context.ts'; +import type { ControlGet } from './context.ts'; test('import reads secret and variable names one request after the other, never both in flight', async () => { const routes: string[] = []; @@ -15,7 +15,7 @@ test('import reads secret and variable names one request after the other, never inFlight--; if (route.startsWith('/api/v1/secrets')) return { secrets: [{ name: 'API_KEY' }] }; return { vars: [{ name: 'GREETING' }] }; - }) as unknown as typeof request; + }) as unknown as ControlGet; const names = await loadExistingNames(get, 'site'); diff --git a/src/cli/commands/import-values.ts b/src/cli/commands/import-values.ts index eaf5bbc..152ed7e 100644 --- a/src/cli/commands/import-values.ts +++ b/src/cli/commands/import-values.ts @@ -1,9 +1,11 @@ import fs from 'node:fs/promises'; -import { ask, canPrompt } from '../prompt.ts'; +import { canPrompt, prompter } from '../prompt.ts'; import { classifyEnvFile } from '../values.ts'; import type { ImportEntry } from '../values.ts'; import { projectOf, request } from './context.ts'; -import type { CommonOpts } from './context.ts'; +import type { CommonOpts, ControlGet } from './context.ts'; +import { out, err, resolvePath } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; const word = (kind: 'secret' | 'var'): string => (kind === 'var' ? 'variable' : 'secret'); @@ -12,7 +14,7 @@ const word = (kind: 'secret' | 'var'): string => (kind === 'var' ? 'variable' : * CLI process made control reset the second connection (ECONNRESET). */ export async function loadExistingNames( - get: typeof request, + get: ControlGet, project: string, ): Promise<{ secrets: { name: string }[]; vars: { name: string }[] }> { const query = `?project=${encodeURIComponent(project)}`; @@ -37,25 +39,29 @@ export interface ImportOpts extends CommonOpts { * `--overwrite`. */ export async function importValues( + rt: CliRuntime, file: string | undefined, o: ImportOpts, mode: 'secret' | 'var', ): Promise { - const project = await projectOf(o); + const project = projectOf(rt, o); const path = file ?? '.env'; let text: string; try { - text = await fs.readFile(path, 'utf8'); + text = await fs.readFile(resolvePath(rt, path), 'utf8'); } catch (error) { throw new Error(`could not read ${path}: ${(error as Error).message}`, { cause: error }); } - const interactive = canPrompt(); + const interactive = canPrompt(rt); const { entries, skipped } = classifyEnvFile(text, { vars: o.vars, secrets: o.secrets, fallback: mode, }); - const { secrets, vars } = await loadExistingNames(request, project); + const { secrets, vars } = await loadExistingNames( + (method, route) => request(rt, method, route), + project, + ); const existing = new Map([ ...secrets.map((row) => [row.name, 'secret'] as const), ...vars.map((row) => [row.name, 'var'] as const), @@ -77,8 +83,8 @@ export async function importValues( todo.push(entry); } if (!todo.length) { - for (const note of notes) console.error(note); - console.log(`nothing to import from ${path}`); + for (const note of notes) err(rt, note); + out(rt, `nothing to import from ${path}`); return; } if (interactive && !o.yes) { @@ -86,7 +92,7 @@ export async function importValues( const chosen: ImportEntry[] = []; for (const entry of todo) { const answer = ( - await ask( + await prompter(rt)( `${entry.name} → ${word(entry.kind)}. [s]ecret, [v]ariable, e[x]clude, or Enter to keep ${word(entry.kind)}? `, ) ) @@ -100,27 +106,29 @@ export async function importValues( } todo = chosen; } else { - console.error(`From ${path} into project ${project}:`); - for (const entry of todo) console.error(` ${entry.name.padEnd(32)} ${word(entry.kind)}`); + err(rt, `From ${path} into project ${project}:`); + for (const entry of todo) err(rt, ` ${entry.name.padEnd(32)} ${word(entry.kind)}`); if (todo.some((entry) => entry.kind === 'var')) - console.error( - 'Variables are visible to anyone with a deploy credential; secrets never are.', - ); - const answer = (await ask(`Store these ${todo.length}? [Y/n] `)).trim().toLowerCase(); + err(rt, 'Variables are visible to anyone with a deploy credential; secrets never are.'); + const answer = (await prompter(rt)(`Store these ${todo.length}? [Y/n] `)) + .trim() + .toLowerCase(); if (answer === 'n' || answer === 'no') { - console.error('nothing stored'); + err(rt, 'nothing stored'); return; } } } - for (const note of notes) console.error(note); + for (const note of notes) err(rt, note); for (const entry of todo) { const result = await request<{ version: number }>( + rt, 'POST', entry.kind === 'secret' ? '/api/v1/secrets' : '/api/v1/vars', { project, name: entry.name, value: entry.value }, ); - console.log( + out( + rt, `${entry.name.padEnd(32)} ${word(entry.kind).padEnd(8)} stored (version ${result.version})`, ); } diff --git a/src/cli/commands/ingress.ts b/src/cli/commands/ingress.ts index 73513b6..1f1e19a 100644 --- a/src/cli/commands/ingress.ts +++ b/src/cli/commands/ingress.ts @@ -3,26 +3,28 @@ import { printResult, request, runLive, waitForCommand } from './context.ts'; import { formatIngressTls } from '../status.ts'; import type { IngressTlsNode } from '../status.ts'; import { selectIngressNode } from './selection.ts'; +import type { CliRuntime } from '../runtime.ts'; /** Shared by `tug ingress logs` and its `tug logs --ingress` shorthand. */ export async function ingressLogs( + rt: CliRuntime, node: string | undefined, o: { tail: string; follow?: boolean }, ): Promise { - node = await selectIngressNode(node); + node = await selectIngressNode(rt, node); if (o.follow) { - await runLive('ingress-logs', { node, tail: o.tail }); + await runLive(rt, 'ingress-logs', { node, tail: o.tail }); return; } - const created = await request('POST', '/api/v1/ingress/logs', { node, tail: Number(o.tail) }); - const cmd = await waitForCommand(created.commandId, 60); + const created = await request(rt, 'POST', '/api/v1/ingress/logs', { node, tail: Number(o.tail) }); + const cmd = await waitForCommand(rt, created.commandId, 60); const result = JSON.parse(cmd.result_json || '{}'); - if (result.stdout) process.stdout.write(result.stdout); - if (result.stderr) process.stderr.write(result.stderr); + if (result.stdout) rt.stdout.write(result.stdout); + if (result.stderr) rt.stderr.write(result.stderr); if (result.error) throw new Error(result.error); } -export function registerIngress(program: Command): void { +export function registerIngress(rt: CliRuntime, program: Command): void { const ingress = program .command('ingress') .description( @@ -34,7 +36,7 @@ export function registerIngress(program: Command): void { .option('--tail ', 'number of lines', '200') .option('-f, --follow', 'follow live logs') .action(async (node: string | undefined, o: { tail: string; follow?: boolean }) => - ingressLogs(node, o), + ingressLogs(rt, node, o), ); ingress .command('tls [node]') @@ -43,9 +45,13 @@ export function registerIngress(program: Command): void { ) .option('--json', 'print the report as JSON') .action(async (node: string | undefined, o: { json?: boolean }) => { - const { nodes } = await request<{ nodes: IngressTlsNode[] }>('GET', '/api/v1/ingress/tls'); + const { nodes } = await request<{ nodes: IngressTlsNode[] }>( + rt, + 'GET', + '/api/v1/ingress/tls', + ); const shown = node ? nodes.filter((n) => n.node === node) : nodes; if (node && !shown.length) throw new Error(`node ${node} is not an enabled ingress node`); - printResult(o.json, shown, formatIngressTls); + printResult(rt, o.json, shown, formatIngressTls); }); } diff --git a/src/cli/commands/init.import.test.ts b/src/cli/commands/init.import.test.ts index ce203d1..4d99c97 100644 --- a/src/cli/commands/init.import.test.ts +++ b/src/cli/commands/init.import.test.ts @@ -6,18 +6,18 @@ import path from 'node:path'; import { Pki, fingerprintPem, type Credential } from '../../pki.ts'; import type { ResolvedCliConfig } from '../config.ts'; import { importCredential } from './init.ts'; +import { testRuntime } from '../../../tests/cli-runtime.ts'; const LIFETIME_MS = 24 * 60 * 60 * 1000; -interface Harness { - cfg: ResolvedCliConfig; -} - -async function harness(): Promise { +/** A runtime whose credentials directory is private to the test, plus the config an import starts from. */ +async function harness() { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-init-import-')); - // Keep imports out of the real user config directory; importCredential reads this on every call. - process.env.TUG_CREDENTIALS_DIR = path.join(dir, 'credentials'); + const credentials = path.join(dir, 'credentials'); + const run = testRuntime({ env: { ...process.env, TUG_CREDENTIALS_DIR: credentials } }); return { + ...run, + credentials, cfg: { file: path.join(dir, 'cfg.yml'), fileExists: false, @@ -42,19 +42,15 @@ async function credential( return issued.credential; } +const ca12 = (cred: Credential) => + fingerprintPem(cred.ca).replace(/:/g, '').toLowerCase().slice(0, 12); + test('importCredential records the first credential without a CA-change notice', async () => { const h = await harness(); const pki = await Pki.load(await fs.mkdtemp(path.join(os.tmpdir(), 'tug-pki-a-')), true); - const errors: string[] = []; - const original = console.error; - console.error = (...args: unknown[]) => errors.push(args.join(' ')); - try { - await importCredential(h.cfg, JSON.stringify(await credential(pki, 'first')), {}); - } finally { - console.error = original; - } + await importCredential(h.rt, h.cfg, JSON.stringify(await credential(pki, 'first')), {}); assert.ok( - !errors.some((line) => line.includes('signed by CA')), + !h.stderr().includes('signed by CA'), 'the first import cannot be a CA change and must not warn', ); }); @@ -63,21 +59,13 @@ test('the imported file name embeds the credential CA fingerprint', async () => const h = await harness(); const pki = await Pki.load(await fs.mkdtemp(path.join(os.tmpdir(), 'tug-pki-a-')), true); const cred = await credential(pki, 'named'); - const printed: string[] = []; - const original = console.log; - console.log = (...args: unknown[]) => printed.push(args.join(' ')); - try { - await importCredential(h.cfg, JSON.stringify(cred), {}); - } finally { - console.log = original; - } - const ca12 = fingerprintPem(cred.ca).replace(/:/g, '').toLowerCase().slice(0, 12); + await importCredential(h.rt, h.cfg, JSON.stringify(cred), {}); assert.match( - printed.join('\n'), - new RegExp(`control\\.test_8443\\.${ca12}\\.json`), + h.stdout(), + new RegExp(`control\\.test_8443\\.${ca12(cred)}\\.json`), 'the imported file name carries the CA fingerprint prefix', ); - await fs.access(path.join(process.env.TUG_CREDENTIALS_DIR!, `control.test_8443.${ca12}.json`)); + await fs.access(path.join(h.credentials, `control.test_8443.${ca12(cred)}.json`)); }); test('importing a credential from a different CA never overwrites the previously imported file', async () => { @@ -93,29 +81,14 @@ test('importing a credential from a different CA never overwrites the previously ); h.cfg.credential = oldCred; - const errors: string[] = []; - const original = console.error; - const originalLog = console.log; - console.error = (...args: unknown[]) => errors.push(args.join(' ')); - console.log = () => {}; - try { - await importCredential(h.cfg, JSON.stringify(oldCred), {}); - // The resolved config still points at the previous credential when the replacement is imported; - // `writeInitConfig` flips the pointer only after the import decision. - h.cfg.credentialFile = path.join( - process.env.TUG_CREDENTIALS_DIR!, - `control.test_8443.${fingerprintPem(oldCred.ca).replace(/:/g, '').toLowerCase().slice(0, 12)}.json`, - ); - await importCredential(h.cfg, JSON.stringify(newCred), {}); - } finally { - console.error = original; - console.log = originalLog; - } + await importCredential(h.rt, h.cfg, JSON.stringify(oldCred), {}); + // The resolved config still points at the previous credential when the replacement is imported; + // `writeInitConfig` flips the pointer only after the import decision. + h.cfg.credentialFile = path.join(h.credentials, `control.test_8443.${ca12(oldCred)}.json`); + await importCredential(h.rt, h.cfg, JSON.stringify(newCred), {}); - const caOld = fingerprintPem(oldCred.ca).replace(/:/g, '').toLowerCase().slice(0, 12); - const caNew = fingerprintPem(newCred.ca).replace(/:/g, '').toLowerCase().slice(0, 12); - const oldPath = path.join(process.env.TUG_CREDENTIALS_DIR!, `control.test_8443.${caOld}.json`); - const newPath = path.join(process.env.TUG_CREDENTIALS_DIR!, `control.test_8443.${caNew}.json`); + const oldPath = path.join(h.credentials, `control.test_8443.${ca12(oldCred)}.json`); + const newPath = path.join(h.credentials, `control.test_8443.${ca12(newCred)}.json`); const oldFile = JSON.parse(await fs.readFile(oldPath, 'utf8')); const newFile = JSON.parse(await fs.readFile(newPath, 'utf8')); assert.equal( @@ -129,11 +102,11 @@ test('importing a credential from a different CA never overwrites the previously 'the different-CA credential is written to its own fingerprint-named file', ); assert.ok( - errors.join('\n').includes(fingerprintPem(newCred.ca)), + h.stderr().includes(fingerprintPem(newCred.ca)), 'the warning names the incoming credential CA fingerprint', ); assert.match( - errors.join('\n'), + h.stderr(), /previous file stays/, 'the warning points at the preserved previous file', ); @@ -143,19 +116,12 @@ test('re-importing the same CA credential reuses one file (idempotent, no name c const h = await harness(); const pki = await Pki.load(await fs.mkdtemp(path.join(os.tmpdir(), 'tug-pki-a-')), true); const cred = await credential(pki, 'stable'); - const originalLog = console.log; - console.log = () => {}; - try { - await importCredential(h.cfg, JSON.stringify(cred), {}); - await importCredential(h.cfg, JSON.stringify(cred), {}); - } finally { - console.log = originalLog; - } - const dir = process.env.TUG_CREDENTIALS_DIR!; - const files = (await fs.readdir(dir)).filter((name) => name.endsWith('.json')); + await importCredential(h.rt, h.cfg, JSON.stringify(cred), {}); + await importCredential(h.rt, h.cfg, JSON.stringify(cred), {}); + const files = (await fs.readdir(h.credentials)).filter((name) => name.endsWith('.json')); assert.equal(files.length, 1, 'two imports of one credential produce one file'); assert.equal( - JSON.parse(await fs.readFile(files[0] && path.join(dir, files[0]), 'utf8')).ca, + JSON.parse(await fs.readFile(files[0] && path.join(h.credentials, files[0]), 'utf8')).ca, cred.ca, ); }); @@ -165,16 +131,9 @@ test('replacing a credential whose CA is unreadable still imports and skips the const pki = await Pki.load(await fs.mkdtemp(path.join(os.tmpdir(), 'tug-pki-bad-')), true); const good = await credential(pki, 'repair'); h.cfg = { ...h.cfg, credential: { ...good, ca: 'not a certificate' } } as ResolvedCliConfig; - const errors: string[] = []; - const original = console.error; - console.error = (...args: unknown[]) => errors.push(args.join(' ')); - try { - await importCredential(h.cfg, JSON.stringify(good), {}); - } finally { - console.error = original; - } + await importCredential(h.rt, h.cfg, JSON.stringify(good), {}); assert.ok( - !errors.some((line) => line.includes('signed by CA')), + !h.stderr().includes('signed by CA'), 'a corrupt previous credential is exactly what a re-import repairs; it must not block or confuse the import', ); }); diff --git a/src/cli/commands/init.ts b/src/cli/commands/init.ts index b09d8c7..a0d4b38 100644 --- a/src/cli/commands/init.ts +++ b/src/cli/commands/init.ts @@ -1,11 +1,12 @@ import fs from 'node:fs/promises'; -import os from 'node:os'; import path from 'node:path'; import type { Command } from 'commander'; import { writeInitConfig } from '../config.ts'; import type { ResolvedCliConfig } from '../config.ts'; import { decodeCredential, fingerprintPem, writeFileDurable } from '../../pki.ts'; import { loadCfg, print, readStdin } from './context.ts'; +import { out, err, homeDir, resolvePath } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; /** * Store a credential document in a 0600 file under the user's config directory and point the git-ignored overlay @@ -13,6 +14,7 @@ import { loadCfg, print, readStdin } from './context.ts'; * `quiet`, and returns the files either way. */ export async function importCredential( + rt: CliRuntime, cfg: ResolvedCliConfig, text: string, connection: { controlUrl?: string; project?: string; quiet?: boolean }, @@ -39,7 +41,8 @@ export async function importCredential( } })(); if (previousFingerprint && previousFingerprint !== caFingerprint) - console.error( + err( + rt, `note: this credential is signed by CA ${caFingerprint}, replacing one signed by ${previousFingerprint}; the CLI now trusts a different control` + (cfg.credentialFile ? `, and the previous file stays at ${cfg.credentialFile} until you switch back` @@ -47,9 +50,9 @@ export async function importCredential( ); // TUG_CREDENTIALS_DIR keeps scripts and tests out of the real home directory. const dir = - process.env.TUG_CREDENTIALS_DIR || + (rt.env.TUG_CREDENTIALS_DIR ? resolvePath(rt, rt.env.TUG_CREDENTIALS_DIR) : undefined) || path.join( - process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), + resolvePath(rt, rt.env.XDG_CONFIG_HOME || path.join(homeDir(rt), '.config')), 'tug', 'credentials', ); @@ -66,32 +69,33 @@ export async function importCredential( cfg, source, { controlUrl: connection.controlUrl, project: connection.project }, + rt.env, credential.url, ); if (connection.quiet) return { files, credentialFile: source }; - for (const file of files) console.log(`wrote ${file}`); - console.log(`imported credential to ${source}`); + for (const file of files) out(rt, `wrote ${file}`); + out(rt, `imported credential to ${source}`); return { files, credentialFile: source }; } -export function registerInit(program: Command): void { +export function registerInit(rt: CliRuntime, program: Command): void { program .command('init [credentialFile]') .description( 'create the config file if missing and import a credential (a file, or - for stdin) into a 0600 user-config file that the git-ignored .local overlay points at', ) .action(async (credentialFile: string | undefined, o: { json?: boolean }, command: Command) => { - const cfg = await loadCfg(); + const cfg = loadCfg(rt); const { controlUrl, project } = command.optsWithGlobals<{ controlUrl?: string; project?: string; }>(); let text: string | undefined; - if (credentialFile === '-') text = await readStdin(); - else if (credentialFile) text = await fs.readFile(credentialFile, 'utf8'); + if (credentialFile === '-') text = await readStdin(rt); + else if (credentialFile) text = await fs.readFile(resolvePath(rt, credentialFile), 'utf8'); else if (cfg.credential) text = JSON.stringify(cfg.credential); if (!text) throw new Error('tug init needs a credential file (or - for stdin)'); - const result = await importCredential(cfg, text, { controlUrl, project, quiet: o.json }); - if (o.json) print({ ok: true, ...result }); + const result = await importCredential(rt, cfg, text, { controlUrl, project, quiet: o.json }); + if (o.json) print(rt, { ok: true, ...result }); }); } diff --git a/src/cli/commands/lint.test.ts b/src/cli/commands/lint.test.ts index c0f6907..77129fc 100644 --- a/src/cli/commands/lint.test.ts +++ b/src/cli/commands/lint.test.ts @@ -1,14 +1,10 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { execFile } from 'node:child_process'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { promisify } from 'node:util'; import { lintComposeFile } from './lint.ts'; - -const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); +import { execCli } from '../../../tests/cli-inprocess.ts'; const writeFile = async (dir: string, name: string, text: string): Promise => { const file = path.join(dir, name); @@ -43,7 +39,7 @@ test('lintComposeFile passes a well-written file and reports its path', async () const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-lint-')); try { const file = await writeFile(dir, 'compose.yml', GOOD); - const result = await lintComposeFile(file); + const result = await lintComposeFile(file, process.cwd()); assert.deepEqual( [result.file, result.errors], [file, []], @@ -51,6 +47,7 @@ test('lintComposeFile passes a well-written file and reports its path', async () ); const normalized = await lintComposeFile( await writeFile(dir, 'short.yml', GOOD.replace(' - "8080:80"\n', ' - "8080:80"\n')), + process.cwd(), ); assert.deepEqual(normalized.errors, [], 'short syntax is what operators write'); } finally { @@ -80,7 +77,7 @@ volumes: persistant: true `, ); - const result = await lintComposeFile(file); + const result = await lintComposeFile(file, process.cwd()); assert.ok( result.errors.some((e) => e === 'web: x-tug.health.type must be docker, tcp or http'), 'the health type is checked against its enum', @@ -101,16 +98,29 @@ volumes: test('lint reports an unreadable, invalid or empty file instead of throwing', async () => { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-lint-')); try { - const missing = await lintComposeFile(path.join(dir, 'nope.yml')); + const missing = await lintComposeFile(path.join(dir, 'nope.yml'), process.cwd()); assert.equal(missing.errors.length, 1, 'one finding for a missing file'); assert.match( missing.errors[0], /could not be read/, 'the finding says the file could not be read', ); - const broken = await lintComposeFile(await writeFile(dir, 'broken.yml', 'services: [unclosed')); + const relative = await lintComposeFile('nope.yml', dir); + assert.match( + relative.errors[0], + /open 'nope\.yml'/, + 'a file named relative to the working directory is reported as it was typed, not as an absolute path', + ); + assert.ok( + !relative.errors[0].includes(dir), + 'the finding must not leak the directory the path was resolved against', + ); + const broken = await lintComposeFile( + await writeFile(dir, 'broken.yml', 'services: [unclosed'), + process.cwd(), + ); assert.match(broken.errors[0], /is not valid YAML/, 'a YAML syntax error is a lint finding'); - const empty = await lintComposeFile(await writeFile(dir, 'empty.yml', '')); + const empty = await lintComposeFile(await writeFile(dir, 'empty.yml', ''), process.cwd()); assert.deepEqual( empty.errors, ['compose file must define services'], @@ -125,7 +135,7 @@ test('tug lint exits nonzero with findings on stderr and prints ok on a passing const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-lint-')); try { await writeFile(dir, 'compose.yml', GOOD); - const okRun = await exec(process.execPath, [entry, 'lint'], { + const okRun = await execCli(['lint'], { cwd: dir, env: { ...process.env }, }); @@ -136,7 +146,7 @@ test('tug lint exits nonzero with findings on stderr and prints ok on a passing 'bad.yml', 'services:\n web:\n image: nginx\n x-tug:\n replicas: 0\n', ); - const error = (await exec(process.execPath, [entry, 'lint', '-f', 'bad.yml'], { + const error = (await execCli(['lint', '-f', 'bad.yml'], { cwd: dir, env: { ...process.env }, }).catch((e: Error & { stdout?: string; stderr?: string }) => e)) as Error & { @@ -164,14 +174,10 @@ test('tug lint --json prints a machine-readable result and no human summary', as 'bad.yml', 'services:\n web:\n image: nginx\n x-tug:\n health:\n type: htp\n', ); - const { stdout } = await exec( - process.execPath, - [entry, 'lint', '--file', 'bad.yml', '--json'], - { - cwd: dir, - env: { ...process.env }, - }, - ).catch((e: Error & { stdout?: string }) => e as never); + const { stdout } = await execCli(['lint', '--file', 'bad.yml', '--json'], { + cwd: dir, + env: { ...process.env }, + }).catch((e: Error & { stdout?: string }) => e as never); const result = JSON.parse(String(stdout)); assert.deepEqual( { ok: result.ok, file: path.basename(result.file), errors: result.errors }, @@ -185,7 +191,7 @@ test('tug lint --json prints a machine-readable result and no human summary', as const good = await writeFile(dir, 'compose.yml', GOOD); const ok = JSON.parse( ( - await exec(process.execPath, [entry, 'lint', '--json'], { + await execCli(['lint', '--json'], { cwd: dir, env: { ...process.env }, }).catch((e: Error & { stdout?: string }) => e as never) @@ -212,7 +218,7 @@ test('the tug.yml file setting defaults the file lint looks at', async () => { await writeFile(dir, 'compose.yml', 'services:\n web:\n x-tug: 5\n'); const alt = await writeFile(dir, 'compose.alt.yml', GOOD); await writeFile(dir, 'tug.yml', 'file: compose.alt.yml\n'); - const { stdout } = await exec(process.execPath, [entry, 'lint', '--json'], { + const { stdout } = await execCli(['lint', '--json'], { cwd: dir, env: { ...process.env }, }); @@ -236,7 +242,7 @@ test('lint reports env_file, which tug deploy no longer reads, and names the imp 'compose.yaml', 'services:\n web:\n image: nginx\n env_file: app.env\n db:\n image: mariadb\n', ); - const result = await lintComposeFile(file); + const result = await lintComposeFile(file, process.cwd()); assert.equal(result.errors.length, 1, 'only the service that uses env_file is reported'); assert.match( result.errors[0], diff --git a/src/cli/commands/lint.ts b/src/cli/commands/lint.ts index 6d4a677..2faa59d 100644 --- a/src/cli/commands/lint.ts +++ b/src/cli/commands/lint.ts @@ -1,10 +1,13 @@ import fs from 'node:fs/promises'; +import path from 'node:path'; import type { Command } from 'commander'; import * as yaml from 'js-yaml'; import { composeErrors } from '../../compose/compose.ts'; import { errMessage } from '../../errors.ts'; import type { ComposeFile } from '../../protocol.ts'; import { defaultComposeFile } from './deploy.ts'; +import { out, err } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; /** What `tug lint` found in one file: deploy's rejection reasons, or an empty list. */ export interface LintResult { @@ -21,12 +24,14 @@ const finding = (file: string, error: string) => `${file}: ${error}`; * Docker, a control connection or a credential. The file is linted as written: deploy expands short * syntax when it reads the file, so short-form volumes are not reported here. */ -export async function lintComposeFile(file: string): Promise { +export async function lintComposeFile(file: string, cwd: string): Promise { let text: string; try { - text = await fs.readFile(file, 'utf8'); + text = await fs.readFile(path.resolve(cwd, file), 'utf8'); } catch (error) { - return { file, errors: [`could not be read: ${errMessage(error)}`] }; + // Name the file as it was typed, as the error did when it was opened relative to the process directory. + const reason = errMessage(error).split(path.resolve(cwd, file)).join(file); + return { file, errors: [`could not be read: ${reason}`] }; } let compose: ComposeFile | undefined; try { @@ -50,27 +55,27 @@ export async function lintComposeFile(file: string): Promise { return { file, errors: [...envFiles, ...others] }; } -export function registerLint(program: Command): void { +export function registerLint(rt: CliRuntime, program: Command): void { program .command('lint') .description( 'check a Compose file against the x-tug schema without deploying or talking to control', ) - .option('-f, --file ', 'compose file', defaultComposeFile()) + .option('-f, --file ', 'compose file', defaultComposeFile(rt)) .option('--json', 'print the findings as JSON for scripts and editors') .action(async (o: { file: string; json?: boolean }) => { - const result = await lintComposeFile(o.file); + const result = await lintComposeFile(o.file, rt.cwd); if (o.json) { - console.log(JSON.stringify({ ok: !result.errors.length, ...result }, null, 2)); + out(rt, JSON.stringify({ ok: !result.errors.length, ...result }, null, 2)); } else { // One finding per line on stderr, keeping any piped stdout clean for editors and scripts; // findings already name their service or volume, so the prefix only adds the file. - for (const error of result.errors) console.error(finding(result.file, error)); + for (const error of result.errors) err(rt, finding(result.file, error)); } if (result.errors.length) { - process.exitCode = 1; + rt.exitCode = 1; return; } - if (!o.json) console.log(`${result.file}: ok`); + if (!o.json) out(rt, `${result.file}: ok`); }); } diff --git a/src/cli/commands/list-flags.test.ts b/src/cli/commands/list-flags.test.ts index 87f28e4..47e4bb3 100644 --- a/src/cli/commands/list-flags.test.ts +++ b/src/cli/commands/list-flags.test.ts @@ -3,6 +3,7 @@ import assert from 'node:assert/strict'; import { Command } from 'commander'; import type { Option } from 'commander'; import { collectList } from './context.ts'; +import { testRuntime } from '../../../tests/cli-runtime.ts'; import { registerBackup } from './backup.ts'; import { registerControl } from './control.ts'; import { registerCredential } from './credential.ts'; @@ -45,6 +46,7 @@ function everyOption(command: Command): { path: string; option: Option }[] { } test('every flag that takes several values accepts a comma-separated list', () => { + const { rt } = testRuntime(); const program = new Command(); for (const register of [ registerBackup, @@ -63,7 +65,7 @@ test('every flag that takes several values accepts a comma-separated list', () = registerVar, registerVolume, ]) - register(program); + register(rt, program); const multi = everyOption(program).filter(({ option }) => Array.isArray(option.defaultValue)); assert.deepEqual( [...new Set(multi.map(({ option }) => option.long))].sort(), diff --git a/src/cli/commands/node.test.ts b/src/cli/commands/node.test.ts index 3a0cad6..e4179d5 100644 --- a/src/cli/commands/node.test.ts +++ b/src/cli/commands/node.test.ts @@ -1,6 +1,7 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { agentIdentityArgs, planNodeAdd } from './node.ts'; +import { testRuntime } from '../../../tests/cli-runtime.ts'; import type { NodeIdentityOpts, PlanDeps } from './node.ts'; const opts = (over: Partial = {}): NodeIdentityOpts => ({ @@ -30,15 +31,8 @@ function deps(over: Partial, answers: string[] = []): PlanDeps & { ask }; } -const quiet = async (run: () => Promise): Promise => { - const original = console.error; - console.error = () => {}; - try { - return await run(); - } finally { - console.error = original; - } -}; +// Everything the plan prints goes to this runtime's streams, not the test output. +const { rt } = testRuntime(); test('without a terminal node add neither probes the host nor asks anything', async () => { let probed = false; @@ -48,7 +42,7 @@ test('without a terminal node add neither probes the host nor asks anything', as discover: () => ((probed = true), []), }); const o = opts(); - await quiet(() => planNodeAdd('root@app1', 'app1', o, d)); + await planNodeAdd(rt, 'root@app1', 'app1', o, d); assert.deepEqual(d.asked, [], 'a script must never be prompted'); assert.equal(probed, false, 'a script run must not SSH to probe Docker or addresses'); assert.deepEqual( @@ -61,7 +55,7 @@ test('without a terminal node add neither probes the host nor asks anything', as test('flags answer the questions so a terminal asks only what is still open', async () => { const d = deps({ discover: () => assert.fail('an explicit --address needs no discovery') }, ['']); const o = opts({ installDocker: true, address: '10.0.0.7', ingress: true, yes: true }); - await quiet(() => planNodeAdd('root@app1', 'app1', o, d)); + await planNodeAdd(rt, 'root@app1', 'app1', o, d); assert.deepEqual(d.asked, [], 'every choice was given by a flag and -y skips the confirmation'); }); @@ -77,7 +71,7 @@ test('a terminal offers Docker, a private address first, ingress and a final con ['y', 'y', ''], ); const o = opts(); - await quiet(() => planNodeAdd('root@app1', 'app1', o, d)); + await planNodeAdd(rt, 'root@app1', 'app1', o, d); assert.equal(o.installDocker, true, 'accepting the offer installs Docker'); assert.equal(o.address, '10.0.0.7', 'enter on the highlighted entry takes the private address'); assert.equal(o.ingress, true, 'accepting the ingress question enables ingress'); @@ -89,14 +83,14 @@ test('a public-only host defaults to leaving the address unset', async () => { discover: () => [{ interface: 'eth0', address: '203.0.113.7', private: false }], }); const o = opts({ ingress: false, yes: true }); - await quiet(() => planNodeAdd('root@app1', 'app1', o, d)); + await planNodeAdd(rt, 'root@app1', 'app1', o, d); assert.equal(o.address, undefined, 'a public address is never the default'); }); test('declining the final confirmation cancels before anything changes', async () => { const d = deps({}, ['n']); await assert.rejects( - quiet(() => planNodeAdd('root@app1', 'app1', opts({ ingress: false, address: '10.0.0.7' }), d)), + planNodeAdd(rt, 'root@app1', 'app1', opts({ ingress: false, address: '10.0.0.7' }), d), /cancelled; nothing was changed/, 'saying no stops node add with a clear message', ); diff --git a/src/cli/commands/node.ts b/src/cli/commands/node.ts index 8f7ae42..f2b35b3 100644 --- a/src/cli/commands/node.ts +++ b/src/cli/commands/node.ts @@ -12,12 +12,12 @@ import { } from '../install.ts'; import type { AddressCandidate } from '../onboarding.ts'; import { formatNodePlan, inferNodeName, isValidNodeName } from '../onboarding.ts'; -import { ask, canPrompt, confirm } from '../prompt.ts'; +import { canPrompt, confirm, prompter } from '../prompt.ts'; import { terminalPicker } from '../pick.ts'; import { runStep, SshHostKeyError, STAGE_MARKER } from '../process.ts'; import type { Prompter } from '../prompt.ts'; import { isNodeHost } from '../../node-address.ts'; -import { assertImagePublished, defaultImage, resolveImage } from '../../images/image.ts'; +import { defaultImage, resolveImage } from '../../images/image.ts'; import { alreadyRunning, assertNotAheadOfControl, @@ -51,6 +51,7 @@ import { } from './context.ts'; import type { InstallOpts } from './context.ts'; import { + assertPublished, bootstrapDocker, discoverAddresses, remoteHostname, @@ -61,6 +62,8 @@ import { transferTugImage, } from './host.ts'; import fs from 'node:fs/promises'; +import { out, err, resolvePath } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; /** Everything the SSH-assisted node commands share. */ export interface NodeIdentityOpts extends InstallOpts { @@ -115,6 +118,7 @@ export function agentIdentityArgs(mode: 'create' | 'replace', name: string): str } async function installNodeIdentity( + rt: CliRuntime, sshTarget: string, name: string, mode: 'create' | 'replace', @@ -123,32 +127,32 @@ async function installNodeIdentity( /** False in batch mode, where only the final per-node results are printed. */ printResult = true, ): Promise { - return withProgress(`Preparing node ${name}`, async (progress) => { - const cfg = await loadCfg(); + return withProgress(rt, `Preparing node ${name}`, async (progress) => { + const cfg = loadCfg(rt); const connectUrl = o.agentControlUrl ? normalizeControlUrl(o.agentControlUrl) : undefined; // Fail before touching the host: no credential, or a control older than this CLI (not after Docker is installed). - await transportFor(cfg, 'probe').then((t) => t.close()); - assertImagePublished(resolveImage(o.image, o.buildLocalImage)); + await transportFor(rt, cfg, 'probe').then((t) => t.close()); + assertPublished(rt, resolveImage(o.image, o.buildLocalImage, rt.version)); if (o.installDocker) { progress.stage(`Installing Docker on node ${name}`); - await bootstrapDocker(sshTarget, progress); + await bootstrapDocker(rt, sshTarget, progress); } progress.stage(`Checking host ${name}`); - await preflightRemote(sshTarget, { + await preflightRemote(rt, sshTarget, { controlUrl: connectUrl ?? cfg.credential?.url, progress, }); - const requestedImage = resolveImage(o.image, o.buildLocalImage); + const requestedImage = resolveImage(o.image, o.buildLocalImage, rt.version); const image = o.buildLocalImage - ? await transferTugImage(sshTarget, requestedImage, progress) + ? await transferTugImage(rt, sshTarget, requestedImage, progress) : requestedImage; const started = new Date().toISOString(); // Before anything is written: a host that still keeps its state in the old directory must migrate first, or the // agent would start on an empty volume. progress.stage(`Checking agent state on ${name}`); - await runStep('ssh', ['--', sshTarget, agentGuardScript(image, name)], { progress }); + await runStep(rt, 'ssh', ['--', sshTarget, agentGuardScript(image, name)], { progress }); if (repair) - await runLocal('ssh', [ + await runLocal(rt, 'ssh', [ '--', sshTarget, `docker run --rm --entrypoint sh -v ${AGENT_VOLUME}:/s ${sh(image)} -c 'cd /s && for f in agent.json agent-pending.json; do [ -e "$f" ] && mv "$f" "$f.corrupt-$(date +%s)"; done; true'`, @@ -158,13 +162,18 @@ async function installNodeIdentity( progress.stage(`Creating identity for node ${name}`); // Adding a node the host is already enrolled as reuses its key, so re-running `node add` upgrades the agent in place; // `node replace` and `node repair` deliberately ask for a new key. - const csr = await runCapture('ssh', ['--', sshTarget, agent(agentIdentityArgs(mode, name))]); + const csr = await runCapture(rt, 'ssh', [ + '--', + sshTarget, + agent(agentIdentityArgs(mode, name)), + ]); const response = await request( + rt, 'POST', `/api/v1/nodes/${encodeURIComponent(name)}/identity`, { csr, mode, address: o.address, labels: o.label }, ); - await runCapture('ssh', ['--', sshTarget, agent('install-cert', true)], { + await runCapture(rt, 'ssh', ['--', sshTarget, agent('install-cert', true)], { input: JSON.stringify(response), }); progress.stage(`Installing agent on node ${name}`); @@ -176,9 +185,11 @@ async function installNodeIdentity( MARKER: STAGE_MARKER, RUN_FLAGS: `${HOST_NETWORK_FLAG} `, }); - await runStep('ssh', ['--', sshTarget, remote], { progress }); + await runStep(rt, 'ssh', ['--', sshTarget, remote], { progress }); if (o.ingress) - await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/ingress`, { enabled: true }); + await request(rt, 'POST', `/api/v1/nodes/${encodeURIComponent(name)}/ingress`, { + enabled: true, + }); const result = { ok: true, node: response.node, ...(o.ingress ? { ingress: true } : {}) }; let reporting = !o.wait; if (o.wait) { @@ -186,6 +197,7 @@ async function installNodeIdentity( // A report from the new identity: wait for a report after the install began, not a replaced node's stale status. for (let i = 0; i < 30; i++) { const { nodes } = await request<{ nodes: { name: string; last_seen_at: string | null }[] }>( + rt, 'GET', '/api/v1/nodes', ); @@ -197,11 +209,9 @@ async function installNodeIdentity( await new Promise((r) => setTimeout(r, 2000)); } if (!reporting) - console.error( - `node ${name} has not reported yet; check \`docker logs tug-agent\` on the host`, - ); + err(rt, `node ${name} has not reported yet; check \`docker logs tug-agent\` on the host`); } - if (printResult) print(o.wait ? { ...result, reporting } : result); + if (printResult) print(rt, o.wait ? { ...result, reporting } : result); return reporting; }); } @@ -216,12 +226,12 @@ export interface PlanDeps { pickOne: (question: string, labels: readonly string[], initial: number) => Promise; } -const realPlanDeps = (): PlanDeps => ({ - interactive: canPrompt(), - hasDocker: (target) => hostHasDocker(target), - discover: discoverAddresses, - prompt: ask, - pickOne: (question, labels, initial) => terminalPicker.one(question, labels, initial), +const realPlanDeps = (rt: CliRuntime): PlanDeps => ({ + interactive: canPrompt(rt), + hasDocker: (target) => hostHasDocker(rt, target), + discover: (target) => discoverAddresses(rt, target), + prompt: prompter(rt), + pickOne: (question, labels, initial) => terminalPicker(rt).one(question, labels, initial), }); /** @@ -229,14 +239,16 @@ const realPlanDeps = (): PlanDeps => ({ * ingress role are asked about, never assumed. Without a terminal nothing is probed or asked and only the plan is printed. */ export async function planNodeAdd( + rt: CliRuntime, sshTarget: string, name: string, o: NodeIdentityOpts, - deps: PlanDeps = realPlanDeps(), + deps: PlanDeps = realPlanDeps(rt), ): Promise { const { interactive, prompt } = deps; if (interactive && !o.installDocker && !deps.hasDocker(sshTarget)) o.installDocker = await confirm( + rt, `Docker is not installed on ${sshTarget}. Install it now (needs root)?`, true, prompt, @@ -262,11 +274,13 @@ export async function planNodeAdd( } if (interactive && o.ingress === undefined) o.ingress = await confirm( + rt, `Should ${name} handle ingress (managed Caddy on ports 80 and 443)?`, false, prompt, ); - console.error( + err( + rt, formatNodePlan({ name, ssh: sshTarget, @@ -274,10 +288,10 @@ export async function planNodeAdd( probed: interactive, address: o.address, ingress: o.ingress, - image: resolveImage(o.image, o.buildLocalImage), + image: resolveImage(o.image, o.buildLocalImage, rt.version), }), ); - if (interactive && !o.yes && !(await confirm(`Add ${name}?`, true, prompt))) + if (interactive && !o.yes && !(await confirm(rt, `Add ${name}?`, true, prompt))) throw new Error('cancelled; nothing was changed'); } @@ -285,28 +299,31 @@ export async function planNodeAdd( * A name for a node when the SSH host does not suggest one (an IP address): in a terminal ask for it, offering the * host's own hostname as the default. Without a terminal there is nobody to ask. */ -async function promptNodeName(sshTarget?: string): Promise { - if (!canPrompt()) return undefined; - const suggestion = sshTarget ? remoteHostname(sshTarget) : undefined; +async function promptNodeName(rt: CliRuntime, sshTarget?: string): Promise { + if (!canPrompt(rt)) return undefined; + const suggestion = sshTarget ? remoteHostname(rt, sshTarget) : undefined; const fallback = suggestion && isValidNodeName(suggestion) ? suggestion : undefined; for (;;) { - const answer = (await ask(`Node name${fallback ? ` (${fallback})` : ''}: `)).trim() || fallback; + const answer = + (await prompter(rt)(`Node name${fallback ? ` (${fallback})` : ''}: `)).trim() || fallback; if (!answer) continue; if (isValidNodeName(answer)) return answer; - console.error( + err( + rt, 'Use letters, numbers, dots, underscores or hyphens, starting with a letter or number.', ); } } async function runNodeIdentity( + rt: CliRuntime, positional: { name?: string; ssh?: string }, o: NodeIdentityOpts, mode: 'create' | 'replace', command: Command, repair = false, ): Promise { - const cfg = await loadCfg(); + const cfg = loadCfg(rt); const verb = repair ? 'node repair' : mode === 'create' ? 'node add' : 'node replace'; if (o.select && o.all) throw new Error('--select and --all cannot be combined'); if (o.all || o.select) { @@ -314,7 +331,10 @@ async function runNodeIdentity( throw new Error(`${verb} --all/--select cannot be combined with a node or SSH target`); const results: { node: string; ok: boolean; reporting?: boolean; error?: string }[] = []; const names = o.select - ? await selectNodes(Object.keys(cfg.nodes).filter((name) => cfg.nodes[name].ssh)) + ? await selectNodes( + rt, + Object.keys(cfg.nodes).filter((name) => cfg.nodes[name].ssh), + ) : Object.keys(cfg.nodes); for (const name of names) { const settings = cfg.nodes[name]; @@ -323,19 +343,19 @@ async function runNodeIdentity( const merged = { ...o, name }; applyConfigDefaults(command, merged, nodeSettings(cfg, name)); try { - const reporting = await installNodeIdentity(target, name, mode, merged, repair, false); + const reporting = await installNodeIdentity(rt, target, name, mode, merged, repair, false); results.push({ node: name, ok: true, ...(merged.wait ? { reporting } : {}) }); } catch (e) { results.push({ node: name, ok: false, error: errMessage(e) }); } } - print({ results }); - if (results.some((r) => !r.ok || r.reporting === false)) process.exitCode = 1; + print(rt, { results }); + if (results.some((r) => !r.ok || r.reporting === false)) rt.exitCode = 1; return; } let name = positional.name ?? (positional.ssh ? inferNodeName(positional.ssh) : undefined); - if (!name && mode === 'replace') name = await selectNode(); - if (!name && mode === 'create') name = await promptNodeName(positional.ssh); + if (!name && mode === 'replace') name = await selectNode(rt); + if (!name && mode === 'create') name = await promptNodeName(rt, positional.ssh); if (!name) throw new Error( mode === 'create' @@ -352,10 +372,10 @@ async function runNodeIdentity( ); if (mode === 'create') { if (o.agentControlUrl) normalizeControlUrl(o.agentControlUrl); - await transportFor(cfg, 'probe').then((t) => t.close()); // no questions about a host this CLI cannot enroll - await planNodeAdd(sshTarget, name, o); + await transportFor(rt, cfg, 'probe').then((t) => t.close()); // no questions about a host this CLI cannot enroll + await planNodeAdd(rt, sshTarget, name, o); } - if (!(await installNodeIdentity(sshTarget, name, mode, o, repair))) process.exitCode = 1; + if (!(await installNodeIdentity(rt, sshTarget, name, mode, o, repair))) rt.exitCode = 1; } /** @@ -365,45 +385,54 @@ async function runNodeIdentity( * carried over unless one is given. */ async function migrateNode( + rt: CliRuntime, sshTarget: string, name: string, o: NodeIdentityOpts, printResult = true, ): Promise { if (!o.agentControlUrl) { - const legacy = (await runCapture('ssh', ['--', sshTarget, readLegacyControlUrlScript])).trim(); + const legacy = ( + await runCapture(rt, 'ssh', ['--', sshTarget, readLegacyControlUrlScript]) + ).trim(); if (legacy) { - console.error(`keeping the agent's connect URL ${legacy} from /etc/tug/agent.env`); + err(rt, `keeping the agent's connect URL ${legacy} from /etc/tug/agent.env`); o.agentControlUrl = legacy; } } // Everything that can fail before the agent is reinstalled is checked first: once the old agent is stopped, a node // that cannot be reinstalled (no credential, an http:// connect URL, an unreachable control) would be left down. - await withProgress(`Checking node ${name} before migrating`, async (progress) => { - const cfg = await loadCfg(); - await transportFor(cfg, 'probe').then((t) => t.close()); - assertImagePublished(resolveImage(o.image, o.buildLocalImage)); + await withProgress(rt, `Checking node ${name} before migrating`, async (progress) => { + const cfg = loadCfg(rt); + await transportFor(rt, cfg, 'probe').then((t) => t.close()); + assertPublished(rt, resolveImage(o.image, o.buildLocalImage, rt.version)); const connectUrl = o.agentControlUrl ? normalizeControlUrl(o.agentControlUrl) : undefined; - await preflightRemote(sshTarget, { controlUrl: connectUrl ?? cfg.credential?.url, progress }); + await preflightRemote(rt, sshTarget, { + controlUrl: connectUrl ?? cfg.credential?.url, + progress, + }); }); await withProgress( + rt, `Copying agent state of node ${name} into the ${AGENT_VOLUME} volume`, (progress) => runStep( + rt, 'ssh', - ['--', sshTarget, agentMigrateScript(resolveImage(o.image, o.buildLocalImage))], + ['--', sshTarget, agentMigrateScript(resolveImage(o.image, o.buildLocalImage, rt.version))], { progress }, ), ); - const reporting = await installNodeIdentity(sshTarget, name, 'create', o, false, false); + const reporting = await installNodeIdentity(rt, sshTarget, name, 'create', o, false, false); if (printResult) - print({ + print(rt, { ok: true, node: name, ...(o.wait ? { reporting } : {}), leftover: AGENT_LEFTOVERS, }); - console.error( + err( + rt, `node ${name}: the old ${LEGACY_AGENT_DIR} and /etc/tug are no longer used; remove them on the host once the node reports online`, ); return reporting; @@ -434,6 +463,7 @@ type UpgradeResult = { * (read from the running container) unchanged. A node already on the target image is skipped. */ async function upgradeNode( + rt: CliRuntime, sshTarget: string, name: string, o: NodeUpgradeOpts, @@ -443,7 +473,7 @@ async function upgradeNode( throw new Error(`node ${name} is not registered with control; \`tug node add\` enrolls it`); let current: AgentInstall; try { - current = parseAgentInspect(await runCapture('ssh', ['--', sshTarget, inspectAgentScript])); + current = parseAgentInspect(await runCapture(rt, 'ssh', ['--', sshTarget, inspectAgentScript])); } catch (e) { if (e instanceof SshHostKeyError) throw e; throw new Error( @@ -451,17 +481,24 @@ async function upgradeNode( { cause: e }, ); } - const image = resolveImage(o.image ?? (o.to ? defaultImage(o.to) : undefined), o.buildLocalImage); - const targetId = parseImageId(await runCapture('ssh', ['--', sshTarget, imageIdScript(image)])); + const image = resolveImage( + o.image ?? (o.to ? defaultImage(o.to) : undefined), + o.buildLocalImage, + rt.version, + ); + const targetId = parseImageId( + await runCapture(rt, 'ssh', ['--', sshTarget, imageIdScript(image)]), + ); if (alreadyRunning(current.imageId, targetId, o.force) && !o.buildLocalImage) { - console.error(`node ${name} already runs ${image}; skipped (--force reinstalls it)`); + err(rt, `node ${name} already runs ${image}; skipped (--force reinstalls it)`); return { node: name, ok: true, upgraded: false }; } const agentControlUrl = o.agentControlUrl ?? current.controlUrl; if (!o.agentControlUrl && current.controlUrl) - console.error(`node ${name}: keeping the agent's connect URL ${current.controlUrl}`); - console.error(`node ${name}: ${current.image} -> ${image}`); + err(rt, `node ${name}: keeping the agent's connect URL ${current.controlUrl}`); + err(rt, `node ${name}: ${current.image} -> ${image}`); const reporting = await installNodeIdentity( + rt, sshTarget, name, 'create', @@ -481,11 +518,12 @@ async function upgradeNode( /** `node upgrade`, also what `tug upgrade` runs for every configured node once control is upgraded. */ export async function runNodeUpgrade( + rt: CliRuntime, positional: { name?: string; ssh?: string }, o: NodeUpgradeOpts, command: Command, ): Promise { - const cfg = await loadCfg(); + const cfg = loadCfg(rt); if (o.select && o.all) throw new Error('--select and --all cannot be combined'); if ((o.all || o.select) && (positional.name || positional.ssh)) throw new Error('node upgrade --all/--select cannot be combined with a node or SSH target'); @@ -495,15 +533,18 @@ export async function runNodeUpgrade( ); if (o.agentControlUrl) normalizeControlUrl(o.agentControlUrl); // Fail before touching any host: no credential, a control older than this CLI, or --to newer than the control. - const control = await transportFor(cfg, 'probe'); + const control = await transportFor(rt, cfg, 'probe'); await control.close(); if (o.to) - assertNotAheadOfControl(o.to, (await request<{ v: string }>('GET', '/api/v1/version')).v); - const { nodes } = await request<{ nodes: { name: string }[] }>('GET', '/api/v1/nodes'); + assertNotAheadOfControl(o.to, (await request<{ v: string }>(rt, 'GET', '/api/v1/version')).v); + const { nodes } = await request<{ nodes: { name: string }[] }>(rt, 'GET', '/api/v1/nodes'); const registered = new Set(nodes.map((n) => n.name)); if (o.all || o.select) { const names = o.select - ? await selectNodes(Object.keys(cfg.nodes).filter((name) => cfg.nodes[name].ssh)) + ? await selectNodes( + rt, + Object.keys(cfg.nodes).filter((name) => cfg.nodes[name].ssh), + ) : Object.keys(cfg.nodes); const results: UpgradeResult[] = []; for (const name of names) { @@ -512,15 +553,15 @@ export async function runNodeUpgrade( const merged = { ...o, name }; applyConfigDefaults(command, merged, nodeSettings(cfg, name)); try { - results.push(await upgradeNode(target, name, merged, registered)); + results.push(await upgradeNode(rt, target, name, merged, registered)); } catch (e) { results.push({ node: name, ok: false, error: errMessage(e) }); } } - print({ results }); + print(rt, { results }); return !results.some((r) => !r.ok || r.reporting === false); } - const name = positional.name ?? (await selectNode()); + const name = positional.name ?? (await selectNode(rt)); o.name = name; applyConfigDefaults(command, o, nodeSettings(cfg, name)); const sshTarget = positional.ssh ?? (nodeSettings(cfg, name).ssh as string | undefined); @@ -528,24 +569,28 @@ export async function runNodeUpgrade( throw new Error( `node upgrade needs an SSH target: pass or set nodes.${name}.ssh in ${cfg.file}`, ); - const result = await upgradeNode(sshTarget, name, o, registered); - print(result); + const result = await upgradeNode(rt, sshTarget, name, o, registered); + print(rt, result); return result.reporting !== false; } async function runNodeMigrate( + rt: CliRuntime, positional: { name?: string; ssh?: string }, o: NodeIdentityOpts, command: Command, ): Promise { - const cfg = await loadCfg(); + const cfg = loadCfg(rt); if (o.select && o.all) throw new Error('--select and --all cannot be combined'); if (o.all || o.select) { if (positional.name || positional.ssh) throw new Error('node migrate --all/--select cannot be combined with a node or SSH target'); const results: { node: string; ok: boolean; reporting?: boolean; error?: string }[] = []; const names = o.select - ? await selectNodes(Object.keys(cfg.nodes).filter((name) => cfg.nodes[name].ssh)) + ? await selectNodes( + rt, + Object.keys(cfg.nodes).filter((name) => cfg.nodes[name].ssh), + ) : Object.keys(cfg.nodes); for (const name of names) { const target = cfg.nodes[name].ssh as string | undefined; @@ -553,17 +598,17 @@ async function runNodeMigrate( const merged = { ...o, name }; applyConfigDefaults(command, merged, nodeSettings(cfg, name)); try { - const reporting = await migrateNode(target, name, merged, false); + const reporting = await migrateNode(rt, target, name, merged, false); results.push({ node: name, ok: true, ...(merged.wait ? { reporting } : {}) }); } catch (e) { results.push({ node: name, ok: false, error: errMessage(e) }); } } - print({ results }); - if (results.some((r) => !r.ok || r.reporting === false)) process.exitCode = 1; + print(rt, { results }); + if (results.some((r) => !r.ok || r.reporting === false)) rt.exitCode = 1; return; } - const name = positional.name ?? (await selectNode()); + const name = positional.name ?? (await selectNode(rt)); o.name = name; applyConfigDefaults(command, o, nodeSettings(cfg, name)); const sshTarget = positional.ssh ?? (nodeSettings(cfg, name).ssh as string | undefined); @@ -572,10 +617,10 @@ async function runNodeMigrate( `node migrate needs an SSH target: pass or set nodes.${name}.ssh in ${cfg.file}`, ); if (o.agentControlUrl) normalizeControlUrl(o.agentControlUrl); - if (!(await migrateNode(sshTarget, name, o))) process.exitCode = 1; + if (!(await migrateNode(rt, sshTarget, name, o))) rt.exitCode = 1; } -export function registerNode(program: Command): void { +export function registerNode(rt: CliRuntime, program: Command): void { const node = program.command('node').description('add, inspect, repair and remove nodes'); addNodeIdentityOptions( @@ -588,7 +633,7 @@ export function registerNode(program: Command): void { .option('--ingress', 'also make the node an ingress node (managed Caddy on ports 80/443)') .option('-y, --yes', 'do not ask for confirmation in a terminal'), ).action(async (ssh: string | undefined, o: NodeIdentityOpts, command: Command) => - runNodeIdentity({ name: o.name, ssh }, o, 'create', command), + runNodeIdentity(rt, { name: o.name, ssh }, o, 'create', command), ); for (const [verb, description, repair] of [ @@ -621,7 +666,7 @@ export function registerNode(program: Command): void { ssh: string | undefined, o: NodeIdentityOpts, command: Command, - ) => runNodeIdentity({ name, ssh }, o, 'replace', command, repair), + ) => runNodeIdentity(rt, { name, ssh }, o, 'replace', command, repair), ); } @@ -654,7 +699,7 @@ export function registerNode(program: Command): void { o: NodeUpgradeOpts, command: Command, ) => { - if (!(await runNodeUpgrade({ name, ssh }, o, command))) process.exitCode = 1; + if (!(await runNodeUpgrade(rt, { name, ssh }, o, command))) rt.exitCode = 1; }, ); @@ -688,7 +733,7 @@ export function registerNode(program: Command): void { ssh: string | undefined, o: NodeIdentityOpts, command: Command, - ) => runNodeMigrate({ name, ssh }, { ...o, label: [] }, command), + ) => runNodeMigrate(rt, { name, ssh }, { ...o, label: [] }, command), ); node @@ -699,9 +744,9 @@ export function registerNode(program: Command): void { ) .option('--json', 'print the raw API result as JSON') .action(async (o: { json?: boolean }) => { - const result = await request<{ nodes: NodeListing[] }>('GET', '/api/v1/nodes'); - if (o.json) print(result); - else console.log(formatNodes(result.nodes)); + const result = await request<{ nodes: NodeListing[] }>(rt, 'GET', '/api/v1/nodes'); + if (o.json) print(rt, result); + else out(rt, formatNodes(result.nodes)); }); node @@ -741,14 +786,15 @@ export function registerNode(program: Command): void { cmd: Command, ) => { if (!o.name) { - o.name = await promptNodeName(); + o.name = await promptNodeName(rt); if (!o.name) throw new Error('node enroll needs --name'); - applyConfigDefaults(cmd, o, nodeSettings(await loadCfg(), o.name)); + applyConfigDefaults(cmd, o, nodeSettings(loadCfg(rt), o.name)); } if (o.address !== undefined && !isNodeHost(o.address)) throw new Error('address must be an IP address or hostname without a port'); const connectUrl = o.agentControlUrl ? normalizeControlUrl(o.agentControlUrl) : undefined; const minted = await request( + rt, 'POST', '/api/v1/nodes/enrollment-credential', { @@ -764,12 +810,16 @@ export function registerNode(program: Command): void { ...(connectUrl ? { connectUrl } : {}), }; const joinKey = Buffer.from(JSON.stringify(keyPayload)).toString('base64url'); - const command = dockerRunSnippet(resolveImage(o.image), joinKey, o.address); + const command = dockerRunSnippet( + resolveImage(o.image, false, rt.version), + joinKey, + o.address, + ); const cloudInit = o.installDocker ? enrollmentCloudInit(await dockerBootstrap(), command) : undefined; if (o.json) { - print({ + print(rt, { name: minted.name, expiresAt: minted.expiresAt, joinKey, @@ -779,13 +829,14 @@ export function registerNode(program: Command): void { return; } if (cloudInit) { - process.stdout.write(cloudInit); + rt.stdout.write(cloudInit); return; } - console.log( + out( + rt, `# Join key for ${minted.name} valid until ${minted.expiresAt}, single use. Run on the fresh host:\n`, ); - console.log(command); + out(rt, command); }, ); @@ -802,9 +853,12 @@ export function registerNode(program: Command): void { async (name: string, o: { csr: string; mode: string; address?: string; label: string[] }) => { if (o.mode !== 'create' && o.mode !== 'replace') throw new Error("--mode must be 'create' or 'replace'"); - const csr = o.csr === '-' ? await readStdin() : await fs.readFile(o.csr, 'utf8'); + const csr = + o.csr === '-' ? await readStdin(rt) : await fs.readFile(resolvePath(rt, o.csr), 'utf8'); print( + rt, await request( + rt, 'POST', `/api/v1/nodes/${encodeURIComponent(name)}/identity`, { csr, mode: o.mode, address: o.address, labels: o.label }, @@ -821,9 +875,10 @@ export function registerNode(program: Command): void { address = address || o.to || ''; if (!address) throw new Error('node address needs an address; use --to when selecting a node'); - name = await selectNode(name); + name = await selectNode(rt, name); return print( - await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/address`, { address }), + rt, + await request(rt, 'POST', `/api/v1/nodes/${encodeURIComponent(name)}/address`, { address }), ); }); node @@ -833,9 +888,11 @@ export function registerNode(program: Command): void { ) .action(async (name: string) => print( + rt, await request( + rt, 'POST', - `/api/v1/nodes/${encodeURIComponent(await selectNode(name))}/disable`, + `/api/v1/nodes/${encodeURIComponent(await selectNode(rt, name))}/disable`, {}, ), ), @@ -864,47 +921,58 @@ export function registerNode(program: Command): void { if (!o.teardown) { if (ssh || o.deleteData || o.yes) throw new Error('an SSH target, --delete-data and --yes need --teardown'); - name = await selectNode(name); + name = await selectNode(rt, name); return print( + rt, await request( + rt, 'DELETE', `/api/v1/nodes/${encodeURIComponent(name)}${o.force ? '?force=true' : ''}`, ), ); } - name = await selectNode(name); - const cfg = await loadCfg(); + name = await selectNode(rt, name); + const cfg = loadCfg(rt); const sshTarget = ssh ?? (nodeSettings(cfg, name).ssh as string | undefined); if (!sshTarget) throw new Error( `--teardown needs an SSH target: pass or set nodes.${name}.ssh in ${cfg.file}`, ); if (!o.yes) { - if (!canPrompt()) + if (!canPrompt(rt)) throw new Error( '--teardown deletes data on the host; pass -y to confirm without a terminal', ); - console.error( + err( + rt, `This will stop the Tug agent on ${sshTarget}, remove its Tug containers and networks and delete the agent's identity (the ${AGENT_VOLUME} volume, and /etc/tug and /var/lib/tug on a host not yet migrated)${ o.deleteData ? ', and DELETE every project volume and the ingress certificates' : ' (project volumes are kept)' }.`, ); - if (!(await confirm('Continue?', false))) throw new Error('cancelled'); + if (!(await confirm(rt, 'Continue?', false))) throw new Error('cancelled'); } // The control record goes first: it refuses a node that is still placed in a current deployment before any // host is touched. A node control no longer knows is cleaned anyway, so a failed cleanup can be retried. let removed: unknown = { ok: true, node: name, alreadyRemoved: true }; try { - removed = await request('DELETE', `/api/v1/nodes/${encodeURIComponent(name)}?force=true`); + removed = await request( + rt, + 'DELETE', + `/api/v1/nodes/${encodeURIComponent(name)}?force=true`, + ); } catch (error) { if (!/node not found/.test(errMessage(error))) throw error; } - await withProgress(`Cleaning node host ${sshTarget}`, async () => { - await runLocal('ssh', ['--', sshTarget, teardownScript(Boolean(o.deleteData))]); + await withProgress(rt, `Cleaning node host ${sshTarget}`, async () => { + await runLocal(rt, 'ssh', ['--', sshTarget, teardownScript(Boolean(o.deleteData))]); + }); + print(rt, { + ...(removed as object), + teardown: sshTarget, + deleteData: Boolean(o.deleteData), }); - print({ ...(removed as object), teardown: sshTarget, deleteData: Boolean(o.deleteData) }); }, ); @@ -915,14 +983,15 @@ export function registerNode(program: Command): void { ) .option('--disable', 'stop acting as an ingress node') .action(async (name: string, o: { disable?: boolean }) => { - const target = await selectNode(name); + const target = await selectNode(rt, name); print( - await request('POST', `/api/v1/nodes/${encodeURIComponent(target)}/ingress`, { + rt, + await request(rt, 'POST', `/api/v1/nodes/${encodeURIComponent(target)}/ingress`, { enabled: !o.disable, }), ); // Caddy starts on the node's next poll, so ports cannot be probed yet; tug never opens them either. - if (!o.disable) console.error(INGRESS_PORTS_HINT(target)); + if (!o.disable) err(rt, INGRESS_PORTS_HINT(target)); }); } diff --git a/src/cli/commands/node.upgrade.test.ts b/src/cli/commands/node.upgrade.test.ts index 6f017e2..09d372d 100644 --- a/src/cli/commands/node.upgrade.test.ts +++ b/src/cli/commands/node.upgrade.test.ts @@ -1,16 +1,12 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { execFile } from 'node:child_process'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { promisify } from 'node:util'; import { startMtlsControl, writeStubDocker } from '../../../tests/helpers.ts'; import { createCsr, generateKeyPair } from '../../pki.ts'; import { defaultImage } from '../../images/image.ts'; - -const execFileAsync = promisify(execFile); -const cliEntry = path.resolve('src/cli.ts'); +import { execCli } from '../../../tests/cli-inprocess.ts'; /** A stub `ssh` that logs every script and answers the agent inspection and identity steps. */ async function stubSsh(dir: string) { @@ -53,8 +49,7 @@ test('node upgrade replaces an enrolled agent, keeps its connect URL, skips curr TUG_STUB_AGENT_INSPECT: inspectFile, }; await fs.writeFile(env.TUG_CONFIG as string, '{}'); - const cli = (...args: string[]) => - execFileAsync(process.execPath, [cliEntry, ...args], { env, cwd: dir }); + const cli = (...args: string[]) => execCli([...args], { env, cwd: dir }); const script = () => fs.readFile(ssh.log, 'utf8'); try { await cli('node', 'add', 'root@node.test', '--name', 'n-up', '--no-wait'); diff --git a/src/cli/commands/observe.ts b/src/cli/commands/observe.ts index 0f85008..bd8e44b 100644 --- a/src/cli/commands/observe.ts +++ b/src/cli/commands/observe.ts @@ -8,18 +8,20 @@ import { formatStatus } from '../status.ts'; import type { StatusResponse } from '../status.ts'; import { loadCfg, print, request, runCapture, waitForCommand } from './context.ts'; import type { CommonOpts } from './context.ts'; +import { out } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; /** Why `tug doctor` does not fail on a machine with no Docker daemon. */ export const LOCAL_DOCKER_SKIP = 'needed only for --build-local'; -export function registerObserve(program: Command): void { +export function registerObserve(rt: CliRuntime, program: Command): void { program .command('status') .description('summarize projects, deployments and nodes') .option('--json', 'print the raw status as JSON for scripts') .action(async (o: { json?: boolean }) => { - const status = await request('GET', '/api/v1/status'); - console.log(o.json ? JSON.stringify(status, null, 2) : formatStatus(status)); + const status = await request(rt, 'GET', '/api/v1/status'); + out(rt, o.json ? JSON.stringify(status, null, 2) : formatStatus(status)); }); program .command('events') @@ -34,12 +36,12 @@ export function registerObserve(program: Command): void { .option('--json', 'print the raw API result as JSON for scripts') .action(async (o: CommonOpts & { limit: string; all?: boolean; json?: boolean }) => { if (o.all && o.project) throw new Error('--all and --project cannot be combined'); - const cfg = await loadCfg(); + const cfg = loadCfg(rt); const project = o.all ? undefined : o.project || cfg.project; const query = `limit=${encodeURIComponent(o.limit)}${project ? `&project=${encodeURIComponent(project)}` : ''}`; - const result = await request<{ events: EventRow[] }>('GET', `/api/v1/events?${query}`); - if (o.json) print(result); - else console.log(formatEvents(result.events, { showProject: !project })); + const result = await request<{ events: EventRow[] }>(rt, 'GET', `/api/v1/events?${query}`); + if (o.json) print(rt, result); + else out(rt, formatEvents(result.events, { showProject: !project })); }); program .command('doctor') @@ -53,8 +55,8 @@ export function registerObserve(program: Command): void { .action( async (o: { nodes?: boolean; node?: string | boolean; timeout: string; json?: boolean }) => { if (o.nodes && o.node) throw new Error('--nodes and --node cannot be combined'); - if (o.node === true) o.node = await selectNode(); - const cfg = await loadCfg(); + if (o.node === true) o.node = await selectNode(rt); + const cfg = loadCfg(rt); const local: { name: string; ok: boolean; @@ -67,7 +69,7 @@ export function registerObserve(program: Command): void { ['docker', 'docker', ['version', '--format', '{{.Server.Version}}']], ] as [string, string, string[]][]) { try { - local.push({ name, ok: true, output: (await runCapture(cmd, args)).trim() }); + local.push({ name, ok: true, output: (await runCapture(rt, cmd, args)).trim() }); } catch (e) { // The operator's Docker daemon builds images only for `deploy --build-local`, so its absence is not a problem. if (name === 'docker') local.push({ name, ok: true, skipped: LOCAL_DOCKER_SKIP }); @@ -77,7 +79,7 @@ export function registerObserve(program: Command): void { let controlDiagnostics: { ok: boolean; checks?: { name: string; warnings?: string[] }[] } | undefined; try { - controlDiagnostics = await request('GET', '/api/v1/diagnostics'); + controlDiagnostics = await request(rt, 'GET', '/api/v1/diagnostics'); } catch (error) { // Name both fingerprints on a trust mismatch, so the operator can compare the credential with the server in one look. const code = caTrustCode(error); @@ -123,13 +125,14 @@ export function registerObserve(program: Command): void { }; if (o.nodes || o.node) { const queued = await request<{ commands: { commandId: string; nodeId: string }[] }>( + rt, 'POST', '/api/v1/diagnostics/nodes', { node: o.node || null }, ); const commands = []; for (const command of queued.commands) { - const finished = await waitForCommand(command.commandId, Number(o.timeout)); + const finished = await waitForCommand(rt, command.commandId, Number(o.timeout)); commands.push({ nodeId: command.nodeId, state: finished.state, @@ -139,9 +142,9 @@ export function registerObserve(program: Command): void { output.nodeDiagnostics = { commands }; if (commands.some((command) => command.state !== 'succeeded')) output.ok = false; } - if (o.json) print(output); - else console.log(formatDoctor(output as DoctorReport)); - if (!output.ok) process.exitCode = 1; + if (o.json) print(rt, output); + else out(rt, formatDoctor(output as DoctorReport)); + if (!output.ok) rt.exitCode = 1; }, ); } diff --git a/src/cli/commands/restore.ts b/src/cli/commands/restore.ts index a26f40b..3c39b36 100644 --- a/src/cli/commands/restore.ts +++ b/src/cli/commands/restore.ts @@ -1,8 +1,10 @@ -import { selectMany } from '../selection.ts'; +import { selectMany, terminalSelection } from '../selection.ts'; import { selectBackup, selectRestore, selectSnapshot, serviceChoices } from './selection.ts'; import { withProgress } from '../progress.ts'; import type { Command } from 'commander'; import { collectList, loadCfg, print, request } from './context.ts'; +import { out, err } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; interface RestorePlanView { target: string; @@ -25,7 +27,7 @@ interface RestoreRecord { started_at: string | null; } -export function registerRestore(program: Command): void { +export function registerRestore(rt: CliRuntime, program: Command): void { const restore = program .command('restore') .description('restore services and volumes from backups'); @@ -76,18 +78,22 @@ export function registerRestore(program: Command): void { throw new Error('--select-writers cannot be combined with --writers or --no-writers'); if (o.scratch && o.selectWriters) throw new Error('--select-writers does not apply to scratch restores'); - target = await selectBackup(target); - if (o.selectSnapshot) o.from = await selectSnapshot(target); + target = await selectBackup(rt, target); + if (o.selectSnapshot) o.from = await selectSnapshot(rt, target); if (o.selectWriters) - o.writers = await selectMany('Select services to stop for the restore', serviceChoices); - return withProgress(`Preparing restore for ${target}`, async (progress) => { - const project = (await loadCfg()).project || 'site'; + o.writers = await selectMany( + 'Select services to stop for the restore', + () => serviceChoices(rt), + terminalSelection(rt), + ); + return withProgress(rt, `Preparing restore for ${target}`, async (progress) => { + const project = loadCfg(rt).project || 'site'; const explicit = Array.isArray(o.writers) && o.writers.length > 0 ? o.writers : undefined; const result = await request<{ confirmed: boolean; plan: RestorePlanView; restoreId?: string; - }>('POST', '/api/v1/restores', { + }>(rt, 'POST', '/api/v1/restores', { project, target, from: o.from, @@ -100,10 +106,10 @@ export function registerRestore(program: Command): void { const plan = result.plan; /** With --json the plan and the outcome are one document, printed when the command ends. */ const finish = (outcome: object = {}): void => { - if (o.json) print({ ...result, ...outcome }); + if (o.json) print(rt, { ...result, ...outcome }); }; const say = (line: string): void => { - if (!o.json) console.log(line); + if (!o.json) out(rt, line); }; say(`target: ${plan.target} on ${plan.node}`); say(`snapshot: ${plan.snapshotId}${plan.snapshotTime ? ` (${plan.snapshotTime})` : ''}`); @@ -126,13 +132,14 @@ export function registerRestore(program: Command): void { for (;;) { await new Promise((resolve) => setTimeout(resolve, 2000)); const { restores } = await request<{ restores: RestoreRecord[] }>( + rt, 'GET', `/api/v1/restores?project=${encodeURIComponent(project)}`, ); const record = restores.find((item) => item.id === result.restoreId); if (record) progress.stage(`Restore ${record.id}: ${record.state}`); if (record?.state === 'succeeded') { - if (record.error) console.error(`warning: ${record.error}`); + if (record.error) err(rt, `warning: ${record.error}`); say( `restore ${record.id} completed${record.scratch_volume ? `; files are in volume ${record.scratch_volume}` : ''}`, ); @@ -140,21 +147,23 @@ export function registerRestore(program: Command): void { return; } if (record && ['failed', 'interrupted', 'released'].includes(record.state)) { - console.error(`restore ${record.id} ${record.state}: ${record.error ?? ''}`); + err(rt, `restore ${record.id} ${record.state}: ${record.error ?? ''}`); if (record.state === 'interrupted') - console.error( + err( + rt, `the services stay stopped; run tug restore resume ${record.id} to try again or tug restore release ${record.id} to start them (data may be partly restored)`, ); finish({ restore: record }); - process.exitCode = 1; + rt.exitCode = 1; return; } if (Date.now() > deadline) { - console.error( + err( + rt, `timed out waiting; restore ${result.restoreId} continues on control (tug restore list)`, ); finish({ timedOut: true }); - process.exitCode = 1; + rt.exitCode = 1; return; } } @@ -165,15 +174,17 @@ export function registerRestore(program: Command): void { .command('list') .description('show recent restores and their state') .action(async (o: { json?: boolean }) => { - const project = (await loadCfg()).project || 'site'; + const project = loadCfg(rt).project || 'site'; const { restores } = await request<{ restores: RestoreRecord[] }>( + rt, 'GET', `/api/v1/restores?project=${encodeURIComponent(project)}`, ); - if (o.json) return print({ restores }); - if (!restores.length) console.log('no restores'); + if (o.json) return print(rt, { restores }); + if (!restores.length) out(rt, 'no restores'); for (const r of restores) - console.log( + out( + rt, `${r.started_at}\t${r.id}\t${r.target}\t${r.mode}\t${r.state}\t${r.snapshot_id.slice(0, 8)}${r.error ? `\t${r.error}` : ''}`, ); }); @@ -181,11 +192,13 @@ export function registerRestore(program: Command): void { .command('resume [id]') .description('run an interrupted restore again; the stopped services stay stopped meanwhile') .action(async (id: string) => - console.log( + out( + rt, JSON.stringify( await request( + rt, 'POST', - `/api/v1/restores/${encodeURIComponent(await selectRestore(id))}/resume`, + `/api/v1/restores/${encodeURIComponent(await selectRestore(rt, id))}/resume`, ), ), ), @@ -196,11 +209,13 @@ export function registerRestore(program: Command): void { 'start the services an interrupted restore stopped and unlock the project; the data may be partly restored', ) .action(async (id: string) => - console.log( + out( + rt, JSON.stringify( await request( + rt, 'POST', - `/api/v1/restores/${encodeURIComponent(await selectRestore(id))}/release`, + `/api/v1/restores/${encodeURIComponent(await selectRestore(rt, id))}/release`, ), ), ), @@ -211,6 +226,6 @@ export function registerRestore(program: Command): void { 'stop a restore that is waiting on its safety backup (nothing has changed) or restoring (it is interrupted, its services stay stopped until resume or release)', ) .action(async (id: string) => - print(await request('POST', `/api/v1/restores/${encodeURIComponent(id)}/cancel`)), + print(rt, await request(rt, 'POST', `/api/v1/restores/${encodeURIComponent(id)}/cancel`)), ); } diff --git a/src/cli/commands/secret.test.ts b/src/cli/commands/secret.process.test.ts similarity index 93% rename from src/cli/commands/secret.test.ts rename to src/cli/commands/secret.process.test.ts index 277bc0a..ef7ce42 100644 --- a/src/cli/commands/secret.test.ts +++ b/src/cli/commands/secret.process.test.ts @@ -6,15 +6,15 @@ import os from 'node:os'; import path from 'node:path'; import { promisify } from 'node:util'; import { startMtlsControl } from '../../../tests/helpers.ts'; +import { cliEntry } from '../../../tests/cli-process.ts'; const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); test('secret set exits after reading stdin even when the input stays open', async () => { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-secret-exit-')); const control = await startMtlsControl(dir); const run = (...args: string[]) => - exec(process.execPath, [entry, 'secret', 'set', 'DB_PASSWORD', ...args], { + exec(process.execPath, [cliEntry, 'secret', 'set', 'DB_PASSWORD', ...args], { cwd: dir, env: { ...process.env, ...control.env, TUG_CREDENTIAL: '', TUG_PROJECT: 'site' }, timeout: 60_000, diff --git a/src/cli/commands/secret.ts b/src/cli/commands/secret.ts index acd80d2..5fdfc34 100644 --- a/src/cli/commands/secret.ts +++ b/src/cli/commands/secret.ts @@ -6,8 +6,9 @@ import { importValues } from './import-values.ts'; import type { ImportOpts } from './import-values.ts'; import { readValue } from './value-input.ts'; import type { ValueInputOpts } from './value-input.ts'; +import type { CliRuntime } from '../runtime.ts'; -export function registerSecret(program: Command): void { +export function registerSecret(rt: CliRuntime, program: Command): void { const secret = program .command('secret') .description('manage the project secrets that Compose files reference'); @@ -19,8 +20,11 @@ export function registerSecret(program: Command): void { .option('--value ') .option('--from-file ', 'read the exact contents of a file, newlines included') .action(async (name: string, o: CommonOpts & ValueInputOpts) => { - const value = await readValue(name, o); - print(await request('POST', '/api/v1/secrets', { project: await projectOf(o), name, value })); + const value = await readValue(rt, name, o); + print( + rt, + await request(rt, 'POST', '/api/v1/secrets', { project: projectOf(rt, o), name, value }), + ); }); secret .command('import [file]') @@ -32,13 +36,14 @@ export function registerSecret(program: Command): void { .option('--select', 'choose secret, variable or exclude for each entry in a terminal') .option('--overwrite', 'replace a name that already exists as the same kind') .option('-y, --yes', 'skip the confirmation in a terminal') - .action(async (file: string | undefined, o: ImportOpts) => importValues(file, o, 'secret')); + .action(async (file: string | undefined, o: ImportOpts) => importValues(rt, file, o, 'secret')); secret .command('list') .description('list secret names and versions, never values') .action(async (o: CommonOpts) => print( - await request('GET', `/api/v1/secrets?project=${encodeURIComponent(await projectOf(o))}`), + rt, + await request(rt, 'GET', `/api/v1/secrets?project=${encodeURIComponent(projectOf(rt, o))}`), ), ); secret @@ -46,9 +51,11 @@ export function registerSecret(program: Command): void { .description('delete a secret') .action(async (name: string, o: CommonOpts) => print( + rt, await request( + rt, 'DELETE', - `/api/v1/secrets/${encodeURIComponent(await selectResource(name, 'secrets'))}?project=${encodeURIComponent(await projectOf(o))}`, + `/api/v1/secrets/${encodeURIComponent(await selectResource(rt, name, 'secrets'))}?project=${encodeURIComponent(projectOf(rt, o))}`, ), ), ); diff --git a/src/cli/commands/selection.ts b/src/cli/commands/selection.ts index 1c39277..d1a6e06 100644 --- a/src/cli/commands/selection.ts +++ b/src/cli/commands/selection.ts @@ -1,27 +1,34 @@ -import { selectMany, selectOne } from '../selection.ts'; +import { selectMany as pickMany, selectOne as pickOne, terminalSelection } from '../selection.ts'; import type { Choice } from '../selection.ts'; +import type { CliRuntime } from '../runtime.ts'; import { projectOf, request } from './context.ts'; -export const projectQuery = async (): Promise => - `project=${encodeURIComponent(await projectOf({}))}`; +type Load = () => Promise; +const one = (rt: CliRuntime, value: string | undefined, question: string, load: Load) => + pickOne(value, question, load, terminalSelection(rt)); +const many = (rt: CliRuntime, question: string, load: Load) => + pickMany(question, load, terminalSelection(rt)); + +export const projectQuery = (rt: CliRuntime): string => + `project=${encodeURIComponent(projectOf(rt, {}))}`; export interface ServiceChoice { name: string; nodes: { name: string; status: string }[]; } -export async function services(): Promise { +export async function services(rt: CliRuntime): Promise { return ( - await request<{ services: ServiceChoice[] }>('GET', `/api/v1/services?${await projectQuery()}`) + await request<{ services: ServiceChoice[] }>(rt, 'GET', `/api/v1/services?${projectQuery(rt)}`) ).services; } -export const serviceChoices = async (): Promise => - (await services()).map((service) => ({ +export const serviceChoices = async (rt: CliRuntime): Promise => + (await services(rt)).map((service) => ({ value: service.name, label: `${service.name} (${service.nodes.map((node) => `${node.name}: ${node.status}`).join(', ') || 'no nodes'})`, })); -export const selectService = (name?: string): Promise => - selectOne(name, 'Select a service', serviceChoices); -export const selectNode = (name?: string): Promise => - selectOne(name, 'Select a node', async () => { +export const selectService = (rt: CliRuntime, name?: string): Promise => + one(rt, name, 'Select a service', () => serviceChoices(rt)); +export const selectNode = (rt: CliRuntime, name?: string): Promise => + one(rt, name, 'Select a node', async () => { const { nodes } = await request<{ nodes: { name: string; @@ -31,27 +38,28 @@ export const selectNode = (name?: string): Promise => ingress: number; labels: string[]; }[]; - }>('GET', '/api/v1/nodes'); + }>(rt, 'GET', '/api/v1/nodes'); return nodes.map((node) => ({ value: node.name, label: `${node.name} (${node.disabled_at ? 'disabled' : node.status}, ${node.address || 'no address'}${node.ingress ? ', ingress' : ''}${node.labels.length ? `, ${node.labels.join(', ')}` : ''})`, })); }); /** Offers only enabled ingress nodes: the picker for `tug ingress` commands. */ -export const selectIngressNode = (name?: string): Promise => - selectOne(name, 'Select an ingress node', async () => { +export const selectIngressNode = (rt: CliRuntime, name?: string): Promise => + one(rt, name, 'Select an ingress node', async () => { const { nodes } = await request<{ nodes: { name: string; status: string; disabled_at: string | null; ingress: number }[]; - }>('GET', '/api/v1/nodes'); + }>(rt, 'GET', '/api/v1/nodes'); return nodes .filter((node) => node.ingress && !node.disabled_at) .map((node) => ({ value: node.name, label: `${node.name} (${node.status})` })); }); export const selectResource = ( + rt: CliRuntime, name: string | undefined, resource: 'secrets' | 'vars' | 'volumes' | 'credentials', ): Promise => - selectOne(name, `Select a ${resource.slice(0, -1)}`, async () => { + one(rt, name, `Select a ${resource.slice(0, -1)}`, async () => { const listing = await request< Record< string, @@ -70,7 +78,7 @@ export const selectResource = ( projects?: string[] | null; }[] > - >('GET', `/api/v1/${resource}${resource === 'credentials' ? '' : `?${await projectQuery()}`}`); + >(rt, 'GET', `/api/v1/${resource}${resource === 'credentials' ? '' : `?${projectQuery(rt)}`}`); return listing[resource] .filter((row) => !row.revokedAt && !row.usedBy?.length) .map((row) => { @@ -89,18 +97,18 @@ export const selectResource = ( return { value: row.name, label: details ? `${row.name} (${details})` : row.name }; }); }); -export const selectDeployment = (id?: string): Promise => - selectOne(id, 'Select an active deployment to cancel', async () => { +export const selectDeployment = (rt: CliRuntime, id?: string): Promise => + one(rt, id, 'Select an active deployment to cancel', async () => { const { deployments } = await request<{ deployments: { id: string; version: string; state: string; created_at: string }[]; - }>('GET', `/api/v1/deployments?${await projectQuery()}`); + }>(rt, 'GET', `/api/v1/deployments?${projectQuery(rt)}`); return deployments.map((row) => ({ value: row.id, label: `${row.version} (${row.state}, ${row.created_at}, ${row.id})`, })); }); -export const selectRestore = (id?: string): Promise => - selectOne(id, 'Select an interrupted restore', async () => { +export const selectRestore = (rt: CliRuntime, id?: string): Promise => + one(rt, id, 'Select an interrupted restore', async () => { const { restores } = await request<{ restores: { id: string; @@ -110,7 +118,7 @@ export const selectRestore = (id?: string): Promise => started_at: string; error: string | null; }[]; - }>('GET', `/api/v1/restores?${await projectQuery()}&state=interrupted`); + }>(rt, 'GET', `/api/v1/restores?${projectQuery(rt)}&state=interrupted`); return restores .filter((row) => row.state === 'interrupted') .map((row) => ({ @@ -118,7 +126,7 @@ export const selectRestore = (id?: string): Promise => label: `${row.target} (${row.started_at}, snapshot ${row.snapshot_id}, ${row.id}${row.error ? `, ${row.error}` : ''})`, })); }); -export const backupChoices = async (): Promise => { +export const backupChoices = async (rt: CliRuntime): Promise => { const { targets } = await request<{ targets: { target: string; @@ -126,7 +134,7 @@ export const backupChoices = async (): Promise => { node: string | null; lastSuccessAt: string | null; }[]; - }>('GET', `/api/v1/backups?${await projectQuery()}`); + }>(rt, 'GET', `/api/v1/backups?${projectQuery(rt)}`); return targets .filter((row) => row.enabled) .map((row) => ({ @@ -134,14 +142,14 @@ export const backupChoices = async (): Promise => { label: `${row.target} (${row.node || 'no node'}, last success ${row.lastSuccessAt || 'never'})`, })); }; -export const selectBackup = (target?: string): Promise => - selectOne(target, 'Select a backup target', backupChoices); -export const selectBackups = (): Promise => - selectMany('Select backup targets', backupChoices); -export const selectSnapshot = (target: string): Promise => - selectOne(undefined, 'Select a backup snapshot', async () => { +export const selectBackup = (rt: CliRuntime, target?: string): Promise => + one(rt, target, 'Select a backup target', () => backupChoices(rt)); +export const selectBackups = (rt: CliRuntime): Promise => + many(rt, 'Select backup targets', () => backupChoices(rt)); +export const selectSnapshot = (rt: CliRuntime, target: string): Promise => + one(rt, undefined, 'Select a backup snapshot', async () => { // Resolve short target names the same way as the restore endpoint, but reject ambiguity. - const targets = await backupChoices(); + const targets = await backupChoices(rt); const matching = targets.filter( (row) => row.value === target || row.value.split(':').slice(1).join(':') === target, ); @@ -156,28 +164,30 @@ export const selectSnapshot = (target: string): Promise => trigger: string; }[]; }>( + rt, 'GET', - `/api/v1/backup/snapshots?${await projectQuery()}&target=${encodeURIComponent(matching[0].value)}`, + `/api/v1/backup/snapshots?${projectQuery(rt)}&target=${encodeURIComponent(matching[0].value)}`, ); return snapshots.map((row) => ({ value: row.id, label: `${row.finished_at} (${row.snapshot_id}, ${row.size_bytes ?? '?'} bytes, ${row.trigger}, ${row.id})`, })); }); -export const selectHolds = (): Promise => - selectMany('Select move holds to release', async () => { +export const selectHolds = (rt: CliRuntime): Promise => + many(rt, 'Select move holds to release', async () => { const { holds } = await request<{ holds: { service: string; reason: string; created_at: string }[]; - }>('GET', `/api/v1/holds?${await projectQuery()}`); + }>(rt, 'GET', `/api/v1/holds?${projectQuery(rt)}`); return holds.map((row) => ({ value: row.service, label: `${row.service} (${row.reason}, ${row.created_at})`, })); }); -export const selectNodes = (configured: string[]): Promise => - selectMany('Select nodes to replace or repair', async () => { +export const selectNodes = (rt: CliRuntime, configured: string[]): Promise => + many(rt, 'Select nodes to replace or repair', async () => { const { nodes } = await request<{ nodes: { name: string; status: string }[] }>( + rt, 'GET', '/api/v1/nodes', ); diff --git a/src/cli/commands/service.ts b/src/cli/commands/service.ts index 9818b2b..83b97d1 100644 --- a/src/cli/commands/service.ts +++ b/src/cli/commands/service.ts @@ -6,8 +6,9 @@ import { ingressLogs } from './ingress.ts'; import type { Command } from 'commander'; import { projectOf, request, runLive, waitForCommand } from './context.ts'; import type { CommonOpts } from './context.ts'; +import type { CliRuntime } from '../runtime.ts'; -export function registerService(program: Command): void { +export function registerService(rt: CliRuntime, program: Command): void { program .command('exec [service] [command...]') .description('execute a command on a service container (default: sh)') @@ -22,8 +23,8 @@ export function registerService(program: Command): void { o: { interactive?: boolean; tty?: boolean; node?: string; select?: boolean }, ) => { if (o.select && service) command.unshift(service); - service = await selectService(o.select ? undefined : service); - await runLive('exec', { service, command, ...o }); + service = await selectService(rt, o.select ? undefined : service); + await runLive(rt, 'exec', { service, command, ...o }); }, ); program @@ -37,8 +38,8 @@ export function registerService(program: Command): void { if (o.select && service) command.unshift(service); if (!command.length) throw new Error('run needs a command, such as: tug run web -- wp core update-db'); - service = await selectService(o.select ? undefined : service); - await runLive('exec', { service, command, node: o.node, oneOff: true }); + service = await selectService(rt, o.select ? undefined : service); + await runLive(rt, 'exec', { service, command, node: o.node, oneOff: true }); }); program .command('ps') @@ -47,6 +48,7 @@ export function registerService(program: Command): void { .option('--json', "print Docker's container list as JSON for scripts") .action(async (o: { node?: string; json?: boolean }) => { await runLive( + rt, 'ps', { node: o.node }, o.json @@ -62,8 +64,8 @@ export function registerService(program: Command): void { .description('print container details as JSON') .option('--node ', 'select one node') .action(async (service: string, o: { node?: string }) => { - service = await selectService(service); - await runLive('inspect', { service, ...o }); + service = await selectService(rt, service); + await runLive(rt, 'inspect', { service, ...o }); }); program .command('logs [service]') @@ -80,24 +82,24 @@ export function registerService(program: Command): void { if (o.ingress) { if (svc || o.project) throw new Error('--ingress reads the edge, which belongs to no project or service'); - await ingressLogs(o.node, o); + await ingressLogs(rt, o.node, o); return; } if (o.node && !o.follow) throw new Error('--node requires --follow for logs'); - svc = await selectService(svc); + svc = await selectService(rt, svc); if (o.follow) { - await runLive('logs', { service: svc, node: o.node, tail: o.tail }); + await runLive(rt, 'logs', { service: svc, node: o.node, tail: o.tail }); return; } - const created = await request('POST', '/api/v1/logs', { - project: await projectOf(o), + const created = await request(rt, 'POST', '/api/v1/logs', { + project: projectOf(rt, o), service: svc, tail: Number(o.tail), }); - const cmd = await waitForCommand(created.commandId, 60); + const cmd = await waitForCommand(rt, created.commandId, 60); const result = JSON.parse(cmd.result_json || '{}'); - if (result.stdout) process.stdout.write(result.stdout); - if (result.stderr) process.stderr.write(result.stderr); + if (result.stdout) rt.stdout.write(result.stdout); + if (result.stderr) rt.stderr.write(result.stderr); if (result.error) throw new Error(result.error); }, ); diff --git a/src/cli/commands/tui.ts b/src/cli/commands/tui.ts index e959223..806645a 100644 --- a/src/cli/commands/tui.ts +++ b/src/cli/commands/tui.ts @@ -1,5 +1,4 @@ import type { Command } from 'commander'; -import { packageVersion } from '../../images/image.ts'; import { createCliLiveTransport } from '../live-transport.ts'; import { WatchClient } from '../watch-client.ts'; import { emptySnapshot } from '../tui/types.ts'; @@ -9,6 +8,8 @@ import { formatOnce, onceReport } from '../tui/once.ts'; import { Poller } from '../tui/poller.ts'; import { COMMANDS, resolveCommand } from '../tui/state.ts'; import { loadCfg, print, request, transportFor } from './context.ts'; +import { out } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; const VIEWS = COMMANDS.filter((name) => name !== 'help' && name !== 'quit'); @@ -21,7 +22,7 @@ function controlLabel(url: string | undefined): string { } } -export function registerTui(program: Command): void { +export function registerTui(rt: CliRuntime, program: Command): void { program .command('tui [view]') .description( @@ -38,25 +39,30 @@ export function registerTui(program: Command): void { view: string | undefined, o: { once?: boolean; readonly?: boolean; json?: boolean }, ) => { - const cfg = await loadCfg(); + const cfg = loadCfg(rt); const project = cfg.project || 'site'; const name = view === undefined ? undefined : resolveCommand(view); if (view !== undefined && (!name || !(VIEWS as readonly string[]).includes(name))) throw new Error(`unknown view "${view}"; choose one of: ${VIEWS.join(', ')}`); const api = { - request, + request: ( + method: string, + route: string, + body?: unknown, + multipart?: boolean, + ) => request(rt, method, route, body, multipart), sleep: (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)), }; if (o.once || o.json) { const snapshot = emptySnapshot(); await new Poller(api, snapshot, () => {}).pollOnce(); - const report = onceReport(snapshot, Date.now(), packageVersion()); - if (o.json) print(report); - else console.log(formatOnce(report, Date.now())); - if (!report.ok) process.exitCode = 1; + const report = onceReport(snapshot, Date.now(), rt.version); + if (o.json) print(rt, report); + else out(rt, formatOnce(report, Date.now())); + if (!report.ok) rt.exitCode = 1; return; } - await transportFor(cfg, 'probe').then((transport) => transport.close()); + await transportFor(rt, cfg, 'probe').then((transport) => transport.close()); const ref: ViewRef | undefined = name && name !== 'overview' ? { @@ -64,21 +70,23 @@ export function registerTui(program: Command): void { ...(['domains', 'volumes', 'secrets'].includes(name) ? { project } : {}), } : undefined; - process.exitCode = await runTui({ + rt.exitCode = await runTui({ api, - transport: createCliLiveTransport(cfg.credential, cfg.controlUrl), + transport: createCliLiveTransport(cfg.credential, cfg.controlUrl, rt.version), watch: (handlers) => new WatchClient({ credential: cfg.credential!, controlUrl: cfg.controlUrl, + clientVersion: rt.version, ...handlers, }), - io: { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr }, + io: { stdin: rt.stdin, stdout: rt.stdout, stderr: rt.stderr, signals: rt.signals }, + env: rt.env, readonly: Boolean(o.readonly), project, view: ref, controlLabel: controlLabel(cfg.credential?.url), - cliVersion: packageVersion(), + cliVersion: rt.version, }); }, ); diff --git a/src/cli/commands/upgrade.test.ts b/src/cli/commands/upgrade.test.ts index 48399c2..508d911 100644 --- a/src/cli/commands/upgrade.test.ts +++ b/src/cli/commands/upgrade.test.ts @@ -1,13 +1,10 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { execFile, spawnSync } from 'node:child_process'; +import { spawnSync } from 'node:child_process'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { promisify } from 'node:util'; - -const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); +import { execCli } from '../../../tests/cli-inprocess.ts'; /** A fake `docker` that logs every call and answers the few queries `control upgrade` makes from files in $FAKE_DIR. */ const FAKE_DOCKER = `#!${process.execPath} @@ -104,19 +101,15 @@ async function withHost( await fs.writeFile(path.join(dir, 'calls.log'), ''); const upgrade = async (...args: string[]) => { try { - const { stdout, stderr } = await exec( - process.execPath, - [entry, 'control', 'upgrade', ...args], - { - cwd: dir, - env: { - ...process.env, - PATH: `${bin}:${process.env.PATH}`, - FAKE_DIR: dir, - TUG_CONFIG: 'tug.yml', - }, + const { stdout, stderr } = await execCli(['control', 'upgrade', ...args], { + cwd: dir, + env: { + ...process.env, + PATH: `${bin}:${process.env.PATH}`, + FAKE_DIR: dir, + TUG_CONFIG: 'tug.yml', }, - ); + }); return { code: 0, stdout, stderr }; } catch (e) { const err = e as { code: number; stdout: string; stderr: string }; @@ -373,7 +366,7 @@ test('control upgrade needs a host and an existing installation', async () => { test('tug upgrade needs controlSsh before it touches anything', async () => { await withHost( async ({ dir, calls }) => { - const result = await exec(process.execPath, [entry, 'upgrade', '--yes'], { + const result = await execCli(['upgrade', '--yes'], { cwd: dir, env: { ...process.env, @@ -400,10 +393,8 @@ test('tug upgrade needs controlSsh before it touches anything', async () => { test('control setup over an existing control says which of its settings the run changes', async () => { await withHost(async ({ dir }) => { const setup = (...args: string[]) => - exec( - process.execPath, + execCli( [ - entry, 'control', 'setup', 'ops@control.test', diff --git a/src/cli/commands/upgrade.ts b/src/cli/commands/upgrade.ts index 1203f38..a5fdfa6 100644 --- a/src/cli/commands/upgrade.ts +++ b/src/cli/commands/upgrade.ts @@ -2,6 +2,7 @@ import type { Command } from 'commander'; import { loadCfg } from './context.ts'; import { runControlUpgrade } from './control.ts'; import { runNodeUpgrade } from './node.ts'; +import type { CliRuntime } from '../runtime.ts'; interface UpgradeAllOpts { to?: string; @@ -14,7 +15,7 @@ interface UpgradeAllOpts { * `tug upgrade`: control first, then every configured node, because control refuses agents that run ahead of it. It stops * when control fails, so no agent is touched against a control that did not upgrade. */ -export function registerUpgrade(program: Command): void { +export function registerUpgrade(rt: CliRuntime, program: Command): void { program .command('upgrade') .description( @@ -31,20 +32,21 @@ export function registerUpgrade(program: Command): void { ) .option('-y, --yes', 'do not ask for confirmation in a terminal') .action(async (o: UpgradeAllOpts, command: Command) => { - const cfg = await loadCfg(); + const cfg = loadCfg(rt); if (!cfg.controlSsh) throw new Error( `upgrade needs controlSsh in ${cfg.file}: the SSH target of the control host`, ); - if (!(await runControlUpgrade(undefined, o))) { - process.exitCode = 1; + if (!(await runControlUpgrade(rt, undefined, o))) { + rt.exitCode = 1; return; } const ok = await runNodeUpgrade( + rt, {}, { all: true, wait: true, to: o.to, buildLocalImage: o.buildLocalImage, force: o.force }, command, ); - if (!ok) process.exitCode = 1; + if (!ok) rt.exitCode = 1; }); } diff --git a/src/cli/commands/value-input.ts b/src/cli/commands/value-input.ts index 1e304b1..4ef8cd4 100644 --- a/src/cli/commands/value-input.ts +++ b/src/cli/commands/value-input.ts @@ -1,5 +1,7 @@ import fs from 'node:fs/promises'; import { readStdin } from './context.ts'; +import { resolvePath } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; /** A stored value is text; 500 KiB covers a certificate chain or a private key with room to spare. */ const MAX_FILE_BYTES = 500 * 1024; @@ -14,11 +16,14 @@ export interface ValueInputOpts { * or one line typed or piped on stdin. A file keeps every newline and space, so a PEM key survives; a line is * trimmed, as before, because `echo` and a terminal both end it with a newline. */ -export async function readValue(name: string, o: ValueInputOpts): Promise { +export async function readValue(rt: CliRuntime, name: string, o: ValueInputOpts): Promise { if (o.value !== undefined && o.fromFile !== undefined) throw new Error('pass --value or --from-file, not both'); if (o.fromFile !== undefined) { - const text = o.fromFile === '-' ? await readStdin() : await fs.readFile(o.fromFile, 'utf8'); + const text = + o.fromFile === '-' + ? await readStdin(rt) + : await fs.readFile(resolvePath(rt, o.fromFile), 'utf8'); if (text.includes('\0')) throw new Error(`${o.fromFile === '-' ? 'stdin' : o.fromFile} is binary; values are text`); if (Buffer.byteLength(text) > MAX_FILE_BYTES) @@ -29,10 +34,10 @@ export async function readValue(name: string, o: ValueInputOpts): Promise((resolve) => { - process.stdout.write(`${name}: `); - process.stdin.once('data', (d) => { + rt.stdout.write(`${name}: `); + rt.stdin.once('data', (d) => { // This command needs no more input; an open stdin can otherwise keep Node alive. - process.stdin.destroy(); + rt.stdin.destroy(); resolve(String(d).trim()); }); }); diff --git a/src/cli/commands/var.test.ts b/src/cli/commands/var.test.ts index 0b73fb7..121eaaf 100644 --- a/src/cli/commands/var.test.ts +++ b/src/cli/commands/var.test.ts @@ -1,14 +1,10 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { execFile } from 'node:child_process'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { promisify } from 'node:util'; import { startMtlsControl } from '../../../tests/helpers.ts'; - -const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); +import { execCli } from '../../../tests/cli-inprocess.ts'; async function withControl( run: (ctx: { @@ -21,7 +17,7 @@ async function withControl( const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-vars-cli-')); const control = await startMtlsControl(dir); const tug = (args: string[], stdin?: string) => { - const child = exec(process.execPath, [entry, ...args], { + return execCli(args, { cwd: dir, env: { ...process.env, @@ -33,10 +29,8 @@ async function withControl( TUG_TEST_SHELL: 'from-shell', COMPOSE_PROFILES: 'debug', }, - timeout: 60_000, + input: stdin, }); - if (stdin !== undefined) child.child.stdin!.end(stdin); - return child; }; try { await run({ diff --git a/src/cli/commands/var.ts b/src/cli/commands/var.ts index 803884a..a55aeae 100644 --- a/src/cli/commands/var.ts +++ b/src/cli/commands/var.ts @@ -6,8 +6,10 @@ import type { ImportOpts } from './import-values.ts'; import { selectResource } from './selection.ts'; import { readValue } from './value-input.ts'; import type { ValueInputOpts } from './value-input.ts'; +import { err } from '../runtime.ts'; +import type { CliRuntime } from '../runtime.ts'; -export function registerVar(program: Command): void { +export function registerVar(rt: CliRuntime, program: Command): void { const vars = program .command('var') .description( @@ -21,15 +23,16 @@ export function registerVar(program: Command): void { .option('--value ') .option('--from-file ', 'read the exact contents of a file, newlines included') .action(async (name: string, o: CommonOpts & ValueInputOpts) => { - const value = await readValue(name, o); - const result = await request<{ version: number }>('POST', '/api/v1/vars', { - project: await projectOf(o), + const value = await readValue(rt, name, o); + const result = await request<{ version: number }>(rt, 'POST', '/api/v1/vars', { + project: projectOf(rt, o), name, value, }); - print(result); + print(rt, result); // On stderr, so a script reading the JSON result is unaffected. - console.error( + err( + rt, `variable ${name} stored (version ${result.version}); it takes effect on the next tug deploy. Variables are visible to anyone with a deploy credential: use tug secret set for private values`, ); }); @@ -39,9 +42,11 @@ export function registerVar(program: Command): void { .option('--values', 'show values (needs a deploy credential)') .action(async (o: CommonOpts & { values?: boolean }) => print( + rt, await request( + rt, 'GET', - `/api/v1/vars${o.values ? '/values' : ''}?project=${encodeURIComponent(await projectOf(o))}`, + `/api/v1/vars${o.values ? '/values' : ''}?project=${encodeURIComponent(projectOf(rt, o))}`, ), ), ); @@ -52,9 +57,11 @@ export function registerVar(program: Command): void { ) .action(async (name: string, o: CommonOpts) => print( + rt, await request( + rt, 'DELETE', - `/api/v1/vars/${encodeURIComponent(await selectResource(name, 'vars'))}?project=${encodeURIComponent(await projectOf(o))}`, + `/api/v1/vars/${encodeURIComponent(await selectResource(rt, name, 'vars'))}?project=${encodeURIComponent(projectOf(rt, o))}`, ), ), ); @@ -68,6 +75,6 @@ export function registerVar(program: Command): void { .option('--overwrite', 'replace a name that already exists as the same kind') .option('-y, --yes', 'skip the confirmation in a terminal') .action(async (file: string | undefined, o: Omit) => - importValues(file, { ...o, vars: [] }, 'var'), + importValues(rt, file, { ...o, vars: [] }, 'var'), ); } diff --git a/src/cli/commands/volume.ts b/src/cli/commands/volume.ts index af82fbc..778bc80 100644 --- a/src/cli/commands/volume.ts +++ b/src/cli/commands/volume.ts @@ -2,15 +2,17 @@ import { selectResource } from './selection.ts'; import type { Command } from 'commander'; import { print, projectOf, request } from './context.ts'; import type { CommonOpts } from './context.ts'; +import type { CliRuntime } from '../runtime.ts'; -export function registerVolume(program: Command): void { +export function registerVolume(rt: CliRuntime, program: Command): void { const volume = program.command('volume').description("list and remove a project's volumes"); volume .command('list') .description('list the volumes of the project and where they live') .action(async (o: CommonOpts) => print( - await request('GET', `/api/v1/volumes?project=${encodeURIComponent(await projectOf(o))}`), + rt, + await request(rt, 'GET', `/api/v1/volumes?project=${encodeURIComponent(projectOf(rt, o))}`), ), ); volume @@ -19,9 +21,11 @@ export function registerVolume(program: Command): void { .option('--delete-data', 'delete underlying Docker volume data') .action(async (name: string, o: CommonOpts & { deleteData?: boolean }) => print( + rt, await request( + rt, 'DELETE', - `/api/v1/volumes/${encodeURIComponent(await selectResource(name, 'volumes'))}?project=${encodeURIComponent(await projectOf(o))}&deleteData=${Boolean(o.deleteData)}`, + `/api/v1/volumes/${encodeURIComponent(await selectResource(rt, name, 'volumes'))}?project=${encodeURIComponent(projectOf(rt, o))}&deleteData=${Boolean(o.deleteData)}`, ), ), ); diff --git a/src/cli/config.test.ts b/src/cli/config.test.ts index b84be68..7754e11 100644 --- a/src/cli/config.test.ts +++ b/src/cli/config.test.ts @@ -3,10 +3,10 @@ import assert from 'node:assert/strict'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { execFile, spawnSync } from 'node:child_process'; -import { promisify } from 'node:util'; +import { spawnSync } from 'node:child_process'; import { Command } from 'commander'; import { writeCredentialFile } from '../../tests/helpers.ts'; +import { execCli } from '../../tests/cli-inprocess.ts'; import { CONFIG_NAMES, COMMAND_SETTINGS, @@ -18,9 +18,6 @@ import { writeInitConfig, } from './config.ts'; -const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); - async function withDir(run: (dir: string) => Promise): Promise { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-config-file-')); try { @@ -398,7 +395,7 @@ test('every config key is the camelCase of the flag it defaults, and every liste const helps = new Map(); const help = async (command: string): Promise => { if (!helps.has(command)) { - const { stdout } = await exec(process.execPath, [entry, ...command.split(' '), '--help']); + const { stdout } = await execCli([...command.split(' '), '--help']); helps.set(command, stdout); } return helps.get(command)!; @@ -432,7 +429,7 @@ test('init creates the tracked file once, keeps an existing one untouched, and g dir, true, ); - const written = await writeInitConfig(resolved, path.join(dir, 'cred1.json'), {}); + const written = await writeInitConfig(resolved, path.join(dir, 'cred1.json'), {}, process.env); assert.deepEqual( written.map((file) => path.basename(file)), ['tug.yml', 'tug.local.yml'], @@ -459,9 +456,12 @@ test('init creates the tracked file once, keeps an existing one untouched, and g const edited = `# my comment\n${tracked}nodes:\n app1:\n ssh: root@h\n`; await fs.writeFile(path.join(dir, 'tug.yml'), edited); const again = await resolveCliConfig({ controlUrl: 'https://other.test' }, {}, dir, true); - await writeInitConfig(again, path.join(dir, 'cred2.json'), { - controlUrl: 'https://other.test', - }); + await writeInitConfig( + again, + path.join(dir, 'cred2.json'), + { controlUrl: 'https://other.test' }, + process.env, + ); assert.equal( await fs.readFile(path.join(dir, 'tug.yml'), 'utf8'), edited, @@ -493,7 +493,7 @@ test('node add reads the ssh target from the config and reports a missing one by 'controlUrl: https://control.test\nnodes:\n app1:\n ssh: root@203.0.113.7\n app2:\n address: x.test\n', ); const run = (...args: string[]) => - exec(process.execPath, [entry, ...args], { cwd: dir }).then( + execCli([...args], { cwd: dir }).then( () => ({ code: 0, stderr: '' }), (error: { code: number; stderr: string }) => ({ code: error.code, stderr: error.stderr }), ); @@ -532,7 +532,7 @@ test('node add reads the ssh target from the config and reports a missing one by test('every config key applies to every command that has its option, and to no other', async () => { const run = (...args: string[]) => - exec(process.execPath, [entry, ...args], { env: { ...process.env, TUG_CONFIG: '' } }).then( + execCli([...args], { env: { ...process.env, TUG_CONFIG: '' } }).then( (r) => r.stdout, (e: { stdout?: string }) => e.stdout ?? '', ); @@ -570,7 +570,13 @@ test('every config key applies to every command that has its option, and to no o test('init writes the credential URL into a new tracked file when no URL was given', async () => { await withDir(async (dir) => { const resolved = await resolveCliConfig({}, {}, dir, true); - await writeInitConfig(resolved, path.join(dir, 'cred.json'), {}, 'https://control.test:8443'); + await writeInitConfig( + resolved, + path.join(dir, 'cred.json'), + {}, + process.env, + 'https://control.test:8443', + ); assert.match( await fs.readFile(path.join(dir, 'tug.yml'), 'utf8'), /controlUrl: https:\/\/control\.test:8443/, diff --git a/src/cli/config.ts b/src/cli/config.ts index f6894e5..9792f4c 100644 --- a/src/cli/config.ts +++ b/src/cli/config.ts @@ -434,6 +434,7 @@ export async function writeInitConfig( config: ResolvedCliConfig, credentialFile: string, explicit: ConnectionOptions, + env: NodeJS.ProcessEnv, credentialUrl?: string, ): Promise { const written: string[] = []; @@ -469,14 +470,14 @@ export async function writeInitConfig( await fs.writeFile(config.localFile, serialize(config.localFile, local), { mode: 0o600 }); await fs.chmod(config.localFile, 0o600); written.push(config.localFile); - await gitIgnore(config.localFile); + await gitIgnore(config.localFile, env); return written; } /** Add `file` to the .gitignore next to it when it sits in a git work tree and is not ignored yet. */ -async function gitIgnore(file: string): Promise { +async function gitIgnore(file: string, env: NodeJS.ProcessEnv): Promise { const cwd = path.dirname(file); - const ignored = spawnSync('git', ['check-ignore', '-q', '--', file], { cwd }); + const ignored = spawnSync('git', ['check-ignore', '-q', '--', file], { cwd, env }); if (ignored.status !== 1) return; // 0: already ignored; anything else: not a git checkout const ignoreFile = path.join(cwd, '.gitignore'); let current = ''; diff --git a/src/cli/credentials.test.ts b/src/cli/credentials.test.ts index 24097ee..96812e9 100644 --- a/src/cli/credentials.test.ts +++ b/src/cli/credentials.test.ts @@ -3,12 +3,9 @@ import assert from 'node:assert/strict'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { execFile } from 'node:child_process'; -import { promisify } from 'node:util'; import { startMtlsControl } from '../../tests/helpers.ts'; +import { execCli } from '../../tests/cli-inprocess.ts'; -const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); const OPERATOR = 'op-cli-tokens'; test('token commands reject malformed invocations before contacting control', async () => { @@ -19,16 +16,13 @@ test('token commands reject malformed invocations before contacting control', as TUG_CONTROL_URL: 'http://unreachable.invalid', }; try { - const help = (await exec(process.execPath, [entry, '--help'], { env, cwd: dir })).stdout; + const help = (await execCli(['--help'], { env, cwd: dir })).stdout; assert.ok(help.includes('credential'), 'help should list the credential group'); - const groups = ( - await exec(process.execPath, [entry, 'credential', '--help'], { env, cwd: dir }) - ).stdout; + const groups = (await execCli(['credential', '--help'], { env, cwd: dir })).stdout; for (const name of ['create', 'list', 'revoke']) assert.ok(groups.includes(name), `help for the credential group should list ${name}`); - const createHelp = ( - await exec(process.execPath, [entry, 'credential', 'create', '--help'], { env, cwd: dir }) - ).stdout; + const createHelp = (await execCli(['credential', 'create', '--help'], { env, cwd: dir })) + .stdout; assert.match(createHelp, /--role/, 'credential create help should document --role'); assert.match(createHelp, /--expires-in-days/, 'credential create help should document expiry'); for (const args of [ @@ -47,7 +41,7 @@ test('token commands reject malformed invocations before contacting control', as ['events', '--all', '--project', 'site'], ]) { await assert.rejects( - exec(process.execPath, [entry, ...args], { env, cwd: dir }), + execCli([...args], { env, cwd: dir }), (error) => { const stderr = (error as Error & { stderr: string }).stderr; assert.doesNotMatch( @@ -69,7 +63,7 @@ test('credential create, credential list and credential revoke work against cont const data = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-cli-tokens-')); const control = await startMtlsControl(data); const tug = (credential: string, ...args: string[]) => - exec(process.execPath, [entry, ...args], { + execCli([...args], { env: { ...process.env, ...control.env, @@ -193,7 +187,7 @@ test('backup commands are listed in help', async () => { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-backup-help-')); const env = { ...process.env, TUG_CONFIG: path.join(dir, 'missing.json') }; const groupHelp = async (...group: string[]) => - (await exec(process.execPath, [entry, ...group, '--help'], { env, cwd: dir })).stdout; + (await execCli([...group, '--help'], { env, cwd: dir })).stdout; for (const [group, verbs] of [ ['backup', ['run', 'list', 'password', 'destination']], ['backup destination', ['set', 'show', 'remove']], @@ -204,7 +198,7 @@ test('backup commands are listed in help', async () => { assert.match(help, new RegExp(`^ ${verb}\\b`, 'm'), `${group} help should list ${verb}`); } assert.match( - (await exec(process.execPath, [entry, '--help'], { env, cwd: dir })).stdout, + (await execCli(['--help'], { env, cwd: dir })).stdout, /^ {2}run\b/m, 'help should list the one-off run command', ); @@ -220,7 +214,7 @@ test('backup destination commands set, show and remove the destination without e AWS_SECRET_ACCESS_KEY: 'cli-secret-value', }; delete (env as Record).TUG_CONFIG; - const run = (...args: string[]) => exec(process.execPath, [entry, ...args], { env, cwd: dir }); + const run = (...args: string[]) => execCli([...args], { env, cwd: dir }); try { const set = await run( 'backup', diff --git a/src/cli/doctor.test.ts b/src/cli/doctor.test.ts index 4394b8c..9c9c371 100644 --- a/src/cli/doctor.test.ts +++ b/src/cli/doctor.test.ts @@ -3,12 +3,8 @@ import assert from 'node:assert/strict'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { execFile } from 'node:child_process'; -import { promisify } from 'node:util'; import { startMtlsControl } from '../../tests/helpers.ts'; - -const exec = promisify(execFile); -const entry = path.resolve('src/cli.ts'); +import { execCli } from '../../tests/cli-inprocess.ts'; test('doctor waits for the node diagnostic instead of returning the queued command id', async () => { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-doctor-')); @@ -20,7 +16,7 @@ test('doctor waits for the node diagnostic instead of returning the queued comma const env: NodeJS.ProcessEnv = { ...process.env, ...control.env }; delete env.TUG_CONFIG; await assert.rejects( - exec(process.execPath, [entry, 'doctor', '--node', 'n1', '--timeout', '1'], { + execCli(['doctor', '--node', 'n1', '--timeout', '1'], { cwd: dir, env, }), @@ -50,7 +46,7 @@ test('enabling ingress tells the operator to open ports 80 and 443 and that tug assert.equal((await control.registerNode('n1')).status, 200, 'the node should register'); const env: NodeJS.ProcessEnv = { ...process.env, ...control.env }; delete env.TUG_CONFIG; - const enabled = await exec(process.execPath, [entry, 'node', 'ingress', 'n1'], { + const enabled = await execCli(['node', 'ingress', 'n1'], { cwd: dir, env, }); @@ -64,7 +60,7 @@ test('enabling ingress tells the operator to open ports 80 and 443 and that tug /tug does not change firewalls/, 'the hint says tug leaves firewalls alone', ); - const disabled = await exec(process.execPath, [entry, 'node', 'ingress', 'n1', '--disable'], { + const disabled = await execCli(['node', 'ingress', 'n1', '--disable'], { cwd: dir, env, }); @@ -86,7 +82,7 @@ test('doctor prints a missing local Docker daemon as skipped and does not count const env: NodeJS.ProcessEnv = { ...process.env, ...control.env, PATH: bin }; delete env.TUG_CONFIG; const run = async (args: string[]) => - exec(process.execPath, [entry, 'doctor', ...args], { cwd: dir, env }).then( + execCli(['doctor', ...args], { cwd: dir, env }).then( (r) => ({ ...r, code: 0 }), (e: { stdout: string; stderr: string; code: number }) => e, ); diff --git a/src/cli/errors.test.ts b/src/cli/errors.test.ts index 7210215..456550e 100644 --- a/src/cli/errors.test.ts +++ b/src/cli/errors.test.ts @@ -1,21 +1,16 @@ import assert from 'node:assert/strict'; -import { execFile } from 'node:child_process'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; import test from 'node:test'; -import { promisify } from 'node:util'; import { findConfigInParents } from './config.ts'; - -const exec = promisify(execFile); -const entry = path.resolve(import.meta.dirname, '../cli.ts'); +import { execCli } from '../../tests/cli-inprocess.ts'; async function failure(args: string[], cwd: string): Promise { try { - await exec(process.execPath, [entry, ...args], { + await execCli([...args], { cwd, env: { ...process.env, TUG_CONFIG: '', TUG_CREDENTIAL: '', TUG_CREDENTIAL_FILE: '', CI: '' }, - timeout: 60_000, }); } catch (error) { return (error as { stderr: string }).stderr; diff --git a/src/cli/json-option.test.ts b/src/cli/json-option.test.ts index ad20078..c6b7c1a 100644 --- a/src/cli/json-option.test.ts +++ b/src/cli/json-option.test.ts @@ -1,16 +1,12 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { execFile } from 'node:child_process'; -import { promisify } from 'node:util'; import { Command } from 'commander'; import fsp from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; import { startMtlsControl } from '../../tests/helpers.ts'; import { addJsonOption } from './json-option.ts'; - -const exec = promisify(execFile); -const cliEntry = new URL('../cli.ts', import.meta.url).pathname; +import { execCli } from '../../tests/cli-inprocess.ts'; test('addJsonOption gives every result command a --json option and leaves the rest alone', () => { const program = new Command('tug'); @@ -51,7 +47,7 @@ test('addJsonOption gives every result command a --json option and leaves the re /** Every leaf command path of the real CLI, found by following `Commands:` in each --help. */ async function leafCommands(prefix: string[] = []): Promise<{ path: string[]; help: string }[]> { - const { stdout } = await exec('node', ['src/cli.ts', ...prefix, '--help']); + const { stdout } = await execCli([...prefix, '--help']); const section = /\nCommands:\n([\s\S]*?)(?:\n\n|\n*$)/.exec(stdout)?.[1]; const children = (section ?? '') .split('\n') @@ -99,8 +95,7 @@ test( TUG_CREDENTIALS_DIR: path.join(dir, 'credentials'), }; await fsp.writeFile(env.TUG_CONFIG as string, '{}'); - const cli = async (...args: string[]) => - (await exec(process.execPath, [cliEntry, ...args], { env, cwd: dir })).stdout; + const cli = async (...args: string[]) => (await execCli([...args], { env, cwd: dir })).stdout; try { const secrets = JSON.parse(await cli('secret', 'list', '--json')); assert.ok(Array.isArray(secrets.secrets), 'secret list --json prints the secrets document'); @@ -116,14 +111,10 @@ test( 'backup list --json prints the catalog with its targets and runs', ); for (const extra of [[], ['--allow-empty']]) { - const check = await exec( - process.execPath, - [cliEntry, 'backup', 'list', '--check', ...extra], - { - env, - cwd: dir, - }, - ).then( + const check = await execCli(['backup', 'list', '--check', ...extra], { + env, + cwd: dir, + }).then( () => ({ code: 0, stderr: '' }), (error: { code: number; stderr: string }) => error, ); diff --git a/src/cli/live-transport.test.ts b/src/cli/live-transport.process.test.ts similarity index 98% rename from src/cli/live-transport.test.ts rename to src/cli/live-transport.process.test.ts index 1d8e2d8..4ce9bce 100644 --- a/src/cli/live-transport.test.ts +++ b/src/cli/live-transport.process.test.ts @@ -16,6 +16,7 @@ import { serverTlsOptions } from '../control/tls-server.ts'; import { createCliLiveTransport } from './live-transport.ts'; import { parseLiveRequest, runCliLive } from './live.ts'; import { until } from '../../tests/wait.ts'; +import { cliEntry } from '../../tests/cli-process.ts'; const execFileAsync = promisify(execFile); async function serverFixture() { @@ -348,7 +349,7 @@ test('CLI commands route through resolved configuration and preserve exec argv i }; delete env.TUG_CONFIG; const cli = (...args: string[]) => - execFileAsync(process.execPath, [path.resolve('src/cli.ts'), ...args], { + execFileAsync(process.execPath, [cliEntry, ...args], { env, cwd: '/tmp', timeout: 60_000, @@ -416,7 +417,12 @@ test('transport maps remote adapter errors into CLI failures', async () => { }); try { await assert.rejects( - runCliLive(request, createCliLiveTransport(f.credential, f.url)), + runCliLive(request, createCliLiveTransport(f.credential, f.url), { + stdin: process.stdin, + stdout: process.stdout, + stderr: process.stderr, + signals: process, + }), /TTY adapter is unavailable/, 'agent capability errors must surface without claiming remote TTY success', ); @@ -449,7 +455,7 @@ test('interactive CLI exits on completion, failure, disconnect and cancellation for (outcome of ['success', 'nonzero', 'error', 'disconnect', 'cancel']) { const running = execFileAsync( process.execPath, - [path.resolve('src/cli.ts'), 'exec', 'web', '-i', '--', 'cat'], + [cliEntry, 'exec', 'web', '-i', '--', 'cat'], { cwd: os.tmpdir(), env: { diff --git a/src/cli/live-transport.ts b/src/cli/live-transport.ts index b091af0..9e878fa 100644 --- a/src/cli/live-transport.ts +++ b/src/cli/live-transport.ts @@ -27,6 +27,7 @@ const MAX_EVENTS = 2 * Math.ceil(LIVE_WINDOW_BYTES / LIVE_FRAME_COST); export function createCliLiveTransport( credential: Credential | undefined, controlUrl: string, + clientVersion: string = packageVersion(), ): CliLiveTransport { if (!credential) throw new CliLiveError('no credential: run `tug init `'); const url = new URL(controlUrl); @@ -41,7 +42,7 @@ export function createCliLiveTransport( ...(clientTlsOptions(credential) as object), // The control only parses this header on its HTTP routes (express middleware does not run on upgrades); // `runLive` runs the explicit version preflight for live commands instead. - headers: { [CLIENT_VERSION_HEADER]: packageVersion() }, + headers: { [CLIENT_VERSION_HEADER]: clientVersion }, }, (error) => // A bare openssl string teaches nothing; a CA mismatch names both fixes at once. diff --git a/src/cli/live.ts b/src/cli/live.ts index 134b351..57648c9 100644 --- a/src/cli/live.ts +++ b/src/cli/live.ts @@ -1,4 +1,4 @@ -import { EventEmitter } from 'node:events'; +import type { EventEmitter } from 'node:events'; import type { Readable, Writable } from 'node:stream'; import { LIVE_WINDOW_BYTES, liveOutputCost } from '../protocol.ts'; @@ -99,9 +99,10 @@ export type CliLiveStdin = Readable & { }; export type CliLiveStdout = Writable & { isTTY?: boolean; columns?: number; rows?: number }; export interface CliLiveIO { - stdin?: CliLiveStdin; - stdout?: CliLiveStdout; - stderr?: Writable; + stdin: CliLiveStdin; + stdout: CliLiveStdout; + stderr: Writable; + /** Where SIGINT is heard; the CLI passes its runtime's signals. */ signals?: EventEmitter; signal?: AbortSignal; /** Renders a `ps` or `inspect` result; defaults to indented JSON. */ @@ -129,12 +130,9 @@ const STDIN_LOW_WATER_BYTES = 64 * 1024; export async function runCliLive( request: LiveRequest, transport: CliLiveTransport, - io: CliLiveIO = {}, + io: CliLiveIO, ): Promise { - const stdin = io.stdin ?? process.stdin; - const stdout = io.stdout ?? process.stdout; - const stderr = io.stderr ?? process.stderr; - const signals = io.signals ?? process; + const { stdin, stdout, stderr, signals } = io; const controller = new AbortController(); let session: CliLiveSession | undefined; let complete = false; @@ -255,7 +253,7 @@ export async function runCliLive( } throw new CliLiveError('live session disconnected before exit'); }; - signals.on('SIGINT', cancel); + signals?.on('SIGINT', cancel); io.signal?.addEventListener('abort', cancel, { once: true }); stdout.on('error', onStreamError); stderr.on('error', onStreamError); @@ -318,7 +316,7 @@ export async function runCliLive( return code; } finally { complete = true; - signals.off('SIGINT', cancel); + signals?.off('SIGINT', cancel); io.signal?.removeEventListener('abort', cancel); stdout.off('resize', resize); if (inputAttached) { diff --git a/src/cli/onboarding.test.ts b/src/cli/onboarding.test.ts index 5ac9644..988f070 100644 --- a/src/cli/onboarding.test.ts +++ b/src/cli/onboarding.test.ts @@ -1,7 +1,5 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { execFile } from 'node:child_process'; -import { promisify } from 'node:util'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; @@ -17,9 +15,8 @@ import { import { confirm, type Prompter } from './prompt.ts'; import { commandPath } from './config.ts'; import { formatNodes } from './status.ts'; - -const exec = promisify(execFile); -const entry = path.resolve(import.meta.dirname, '../cli.ts'); +import { execCli } from '../../tests/cli-inprocess.ts'; +import { testRuntime } from '../../tests/cli-runtime.ts'; const answers = (...given: string[]): Prompter => @@ -70,10 +67,15 @@ test('parseAddressCandidates reads ip output and sortCandidates puts private add }); test('confirm takes the default on an empty answer and retries on nonsense', async () => { - assert.equal(await confirm('ok?', true, answers('')), true, 'empty takes the yes default'); - assert.equal(await confirm('ok?', false, answers('')), false, 'empty takes the no default'); - assert.equal(await confirm('ok?', false, answers('maybe', 'YES')), true, 'invalid input re-asks'); - assert.equal(await confirm('ok?', true, answers('n')), false, 'n declines'); + const { rt } = testRuntime(); + assert.equal(await confirm(rt, 'ok?', true, answers('')), true, 'empty takes the yes default'); + assert.equal(await confirm(rt, 'ok?', false, answers('')), false, 'empty takes the no default'); + assert.equal( + await confirm(rt, 'ok?', false, answers('maybe', 'YES')), + true, + 'invalid input re-asks', + ); + assert.equal(await confirm(rt, 'ok?', true, answers('n')), false, 'n declines'); }); test('commandPath joins group names and resolves the setup shortcut', () => { @@ -122,7 +124,7 @@ test('the CLI is grouped: setup mirrors control setup, node add needs a name for const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-groups-')); const env = { ...process.env, TUG_CONFIG: path.join(dir, 'cfg.json'), CI: '1' }; await fs.writeFile(env.TUG_CONFIG, '{}'); - const run = (...args: string[]) => exec(process.execPath, [entry, ...args], { env, cwd: dir }); + const run = (...args: string[]) => execCli([...args], { env, cwd: dir }); try { const flags = (help: string) => [...help.matchAll(/^\s+(--[a-z-]+)/gm)].map((m) => m[1]).sort(); assert.deepEqual( diff --git a/src/cli/pick.test.ts b/src/cli/pick.test.ts index a37186d..aac731d 100644 --- a/src/cli/pick.test.ts +++ b/src/cli/pick.test.ts @@ -212,13 +212,15 @@ test('a resize redraws the menu and finishing removes every process hook', async test('a terminated process shows the cursor again and still dies of the signal', async () => { const picker = pathToFileURL(path.resolve('src/cli/pick.ts')).href; + const runtime = pathToFileURL(path.resolve('src/cli/runtime.ts')).href; const child = spawn( process.execPath, [ '--input-type=module', '-e', - `import { createPicker } from ${JSON.stringify(picker)}; - createPicker({ input: process.stdin, output: process.stderr }).one('Target', ['a', 'b']);`, + `import { terminalPicker } from ${JSON.stringify(picker)}; + import { processRuntime } from ${JSON.stringify(runtime)}; + terminalPicker(processRuntime('0.0.0')).one('Target', ['a', 'b']);`, ], { stdio: ['pipe', 'pipe', 'pipe'] }, ); diff --git a/src/cli/pick.ts b/src/cli/pick.ts index 4cd1a15..c4c9fed 100644 --- a/src/cli/pick.ts +++ b/src/cli/pick.ts @@ -1,7 +1,8 @@ import readline from 'node:readline'; import type { Readable, Writable } from 'node:stream'; -import { ask } from './prompt.ts'; +import { prompter } from './prompt.ts'; import { suspendProgress } from './progress.ts'; +import type { CliRuntime } from './runtime.ts'; import { clipToColumns, columnWidth, plainText as plain } from './width.ts'; export interface PickIO { @@ -11,6 +12,10 @@ export interface PickIO { unref?: () => unknown; }; output: Writable & { columns?: number; rows?: number }; + /** Process signals and exit, so a menu can restore the terminal first; without it none are handled. */ + signals?: CliRuntime['signals']; + /** Re-raises a signal after the terminal is restored, so the process still dies of it. */ + raise?: CliRuntime['raise']; } /** @@ -106,10 +111,14 @@ function pick( const onExit = () => restoreTerminal(); // A signal that ends the process must not leave the cursor hidden or the terminal raw: restore, then die of it. const signals = ['SIGTERM', 'SIGHUP'] as const; + const unsubscribe = () => { + io.signals?.off('exit', onExit); + for (const name of signals) io.signals?.off(name, onSignal); + }; const onSignal = (signal: NodeJS.Signals) => { restoreTerminal(); - for (const name of signals) process.off(name, onSignal); - process.kill(process.pid, signal); + unsubscribe(); + io.raise?.(signal); }; const finish = (error: Error | undefined, indexes: number[] = []) => { if (settled) return; @@ -118,8 +127,7 @@ function pick( input.off('end', onEnd); input.off('error', onError); output.off('resize', redraw); - process.off('exit', onExit); - for (const name of signals) process.off(name, onSignal); + unsubscribe(); input.setRawMode?.(false); input.pause(); // A paused stdin can keep its handle reading after a later consumer resumed it; never let a finished menu hold the process open. @@ -186,8 +194,8 @@ function pick( input.once('end', onEnd); input.once('error', onError); output.on('resize', redraw); - process.once('exit', onExit); - for (const name of signals) process.once(name, onSignal); + io.signals?.once('exit', onExit); + for (const name of signals) io.signals?.once(name, onSignal); output.write(HIDE_CURSOR); render(); input.resume(); @@ -254,18 +262,21 @@ export function createNumberedPicker( }; } -const terminalIO = (): PickIO => ({ - input: process.stdin as PickIO['input'], - output: process.stderr, +const terminalIO = (rt: CliRuntime): PickIO => ({ + input: rt.stdin, + output: rt.stderr, + signals: rt.signals, + raise: rt.raise, }); -const numbered = createNumberedPicker(ask, (line) => console.error(line)); /** A terminal that announces itself as dumb gets numbered menus; everything else gets the keyboard menu. */ -const choosePicker = (): Picker => - process.env.TERM === 'dumb' ? numbered : createPicker(terminalIO()); +const choosePicker = (rt: CliRuntime): Picker => + rt.env.TERM === 'dumb' + ? createNumberedPicker(prompter(rt), (line) => void rt.stderr.write(`${line}\n`)) + : createPicker(terminalIO(rt)); /** A menu owns the terminal while it is open, so a live progress line is lifted off the screen for the duration. */ -async function whileMenuOpen(run: () => Promise): Promise { - const resume = suspendProgress(); +async function whileMenuOpen(rt: CliRuntime, run: () => Promise): Promise { + const resume = suspendProgress(rt); try { return await run(); } finally { @@ -273,9 +284,9 @@ async function whileMenuOpen(run: () => Promise): Promise { } } -/** Resolved on use so importing this module never touches stdin. */ -export const terminalPicker: Picker = { +/** The menus of this run's terminal, chosen when one opens. */ +export const terminalPicker = (rt: CliRuntime): Picker => ({ one: (question, labels, initial) => - whileMenuOpen(() => choosePicker().one(question, labels, initial)), - many: (question, labels) => whileMenuOpen(() => choosePicker().many(question, labels)), -}; + whileMenuOpen(rt, () => choosePicker(rt).one(question, labels, initial)), + many: (question, labels) => whileMenuOpen(rt, () => choosePicker(rt).many(question, labels)), +}); diff --git a/src/cli/process.test.ts b/src/cli/process.test.ts index ef90ad5..95a7a3a 100644 --- a/src/cli/process.test.ts +++ b/src/cli/process.test.ts @@ -1,12 +1,14 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { runCapture, runLocal, runProcess } from './process.ts'; +import { runCapture, runLocal, runProcess, runStep, STAGE_MARKER } from './process.ts'; import { createProgress } from './progress.ts'; import { RUN_OUTPUT_LIMIT } from '../images/build.ts'; +import { testRuntime } from '../../tests/cli-runtime.ts'; test('child processes keep progress timers running and capture stdin/stdout/stderr separately', async () => { + const { rt } = testRuntime(); const lines: string[] = []; - const progress = createProgress({ + const progress = createProgress(rt, { intervalMs: 10, write: (line) => { lines.push(line); @@ -15,6 +17,7 @@ test('child processes keep progress timers running and capture stdin/stdout/stde progress.stage('Installing'); try { const result = await runProcess( + rt, process.execPath, [ '-e', @@ -40,27 +43,31 @@ test('child processes keep progress timers running and capture stdin/stdout/stde }); test('async process helpers preserve errors and bound captured output', async () => { + const { rt } = testRuntime(); assert.equal( - await runCapture(process.execPath, ['-e', "process.stdout.write('csr')"]), + await runCapture(rt, process.execPath, ['-e', "process.stdout.write('csr')"]), 'csr', 'capture must return stdout unchanged', ); await assert.rejects( - runLocal(process.execPath, ['-e', 'process.exit(7)']), + runLocal(rt, process.execPath, ['-e', 'process.exit(7)']), /exit 7/, 'inherited-output processes must reject nonzero exits', ); await assert.rejects( - runCapture(process.execPath, ['-e', "process.stderr.write('failure detail'); process.exit(8)"]), + runCapture(rt, process.execPath, [ + '-e', + "process.stderr.write('failure detail'); process.exit(8)", + ]), /failure detail/, 'captured process failures must retain actionable stderr', ); await assert.rejects( - runLocal('tug-missing-install-command', []), + runLocal(rt, 'tug-missing-install-command', []), /ENOENT/, 'spawn errors must reject instead of hanging', ); - const result = await runCapture(process.execPath, [ + const result = await runCapture(rt, process.execPath, [ '-e', "process.stdout.write('x'.repeat(2 * 1024 * 1024) + 'END')", ]); @@ -70,85 +77,83 @@ test('async process helpers preserve errors and bound captured output', async () ); }); +test("a child's output reaches the runtime's streams, and its environment and directory are the runtime's", async () => { + const run = testRuntime({ env: { ...process.env, TUG_PROBE: 'from-runtime' }, cwd: '/' }); + await runLocal(run.rt, process.execPath, [ + '-e', + "process.stdout.write(process.env.TUG_PROBE + ' ' + process.cwd()); process.stderr.write('warned')", + ]); + assert.equal( + run.stdout(), + 'from-runtime /', + 'the child should see the runtime environment and working directory and write to its stdout', + ); + assert.equal(run.stderr(), 'warned', 'the child stderr should reach the runtime stderr'); +}); + test('runStep hides output, turns markers into stages, and reports the tail on failure', async () => { - const { setVerbose } = await import('./process.ts'); - setVerbose(false); + const run = testRuntime(); const stages: string[] = []; const details: string[] = []; - const seen: string[] = []; - const write = process.stderr.write.bind(process.stderr); - process.stderr.write = ((chunk: string) => (seen.push(String(chunk)), true)) as typeof write; - try { - const { runStep, STAGE_MARKER } = await import('./process.ts'); - const script = ` - console.log(${JSON.stringify(STAGE_MARKER)} + 'Pulling image'); - process.stdout.write('layer 1: Downloading\\rlayer 1: Extracting\\n'); - console.error('layer 2: Pull complete'); - console.log(${JSON.stringify(STAGE_MARKER)} + 'Starting');`; - await runStep(process.execPath, ['-e', script], { - progress: { stage: (label) => stages.push(label), detail: (line) => details.push(line) }, - }); - assert.deepEqual(stages, ['Pulling image', 'Starting'], 'marker lines should become stages'); - assert.ok( - details.includes('layer 1: Downloading') && details.includes('layer 1: Extracting'), - 'carriage-return redraws should count as separate lines for the status line', - ); - assert.ok( - !details.some((line) => line.includes(STAGE_MARKER.trim())), - 'markers should not appear as output lines', - ); - assert.deepEqual(seen, [], 'a successful quiet step must print nothing'); - await assert.rejects( - runStep(process.execPath, ['-e', "console.error('boom: no space left'); process.exit(3)"]), - /failed \(exit 3\)\nboom: no space left/, - 'a failure should include the lines the step printed', - ); - } finally { - process.stderr.write = write; - } + const script = ` + console.log(${JSON.stringify(STAGE_MARKER)} + 'Pulling image'); + process.stdout.write('layer 1: Downloading\\rlayer 1: Extracting\\n'); + console.error('layer 2: Pull complete'); + console.log(${JSON.stringify(STAGE_MARKER)} + 'Starting');`; + await runStep(run.rt, process.execPath, ['-e', script], { + progress: { stage: (label) => stages.push(label), detail: (line) => details.push(line) }, + }); + assert.deepEqual(stages, ['Pulling image', 'Starting'], 'marker lines should become stages'); + assert.ok( + details.includes('layer 1: Downloading') && details.includes('layer 1: Extracting'), + 'carriage-return redraws should count as separate lines for the status line', + ); + assert.ok( + !details.some((line) => line.includes(STAGE_MARKER.trim())), + 'markers should not appear as output lines', + ); + assert.equal(run.stderr(), '', 'a successful quiet step must print nothing'); + await assert.rejects( + runStep(run.rt, process.execPath, [ + '-e', + "console.error('boom: no space left'); process.exit(3)", + ]), + /failed \(exit 3\)\nboom: no space left/, + 'a failure should include the lines the step printed', + ); }); test('runStep streams output under --verbose and accepts stdin', async () => { - const { runStep, setVerbose } = await import('./process.ts'); - const seen: string[] = []; - const write = process.stderr.write.bind(process.stderr); - process.stderr.write = ((chunk: string) => (seen.push(String(chunk)), true)) as typeof write; - try { - setVerbose(true); - await runStep( - process.execPath, - ['-e', "process.stdin.on('data', (d) => console.log('got ' + d))"], - { input: 'credential' }, - ); - } finally { - process.stderr.write = write; - setVerbose(false); - } - assert.deepEqual(seen, ['got credential\n'], 'verbose mode should stream the step output'); + const run = testRuntime(); + run.rt.state.verbose = true; + await runStep( + run.rt, + process.execPath, + ['-e', "process.stdin.on('data', (d) => console.log('got ' + d))"], + { input: 'credential' }, + ); + assert.equal(run.stderr(), 'got credential\n', 'verbose mode should stream the step output'); }); test("verbose output goes through the progress line, and only this run's marker starts a stage", async () => { - const { runStep, setVerbose, STAGE_MARKER } = await import('./process.ts'); + const { rt } = testRuntime(); + rt.state.verbose = true; const printed: string[] = []; const stages: string[] = []; - try { - setVerbose(true); - await runStep( - process.execPath, - [ - '-e', - `console.log(${JSON.stringify(STAGE_MARKER)} + 'Real stage'); console.log('::tug:: Spoofed'); console.log('plain output')`, - ], - { - progress: { - stage: (label) => stages.push(label), - print: (line) => printed.push(line), - }, + await runStep( + rt, + process.execPath, + [ + '-e', + `console.log(${JSON.stringify(STAGE_MARKER)} + 'Real stage'); console.log('::tug:: Spoofed'); console.log('plain output')`, + ], + { + progress: { + stage: (label) => stages.push(label), + print: (line) => printed.push(line), }, - ); - } finally { - setVerbose(false); - } + }, + ); assert.deepEqual( printed, ['::tug:: Spoofed', 'plain output'], @@ -162,10 +167,9 @@ test("verbose output goes through the progress line, and only this run's marker }); test('a step that never ends its line cannot grow memory without bound', async () => { - const { runStep, setVerbose } = await import('./process.ts'); - setVerbose(false); + const { rt } = testRuntime(); await assert.rejects( - runStep(process.execPath, ['-e', "process.stdout.write('x'.repeat(1e6)); process.exit(4)"]), + runStep(rt, process.execPath, ['-e', "process.stdout.write('x'.repeat(1e6)); process.exit(4)"]), (error: Error) => { assert.ok(error.message.length < 10_000, 'the failure message must be bounded'); return /failed \(exit 4\)/.test(error.message); diff --git a/src/cli/process.ts b/src/cli/process.ts index 93da322..deffc09 100644 --- a/src/cli/process.ts +++ b/src/cli/process.ts @@ -2,7 +2,8 @@ import { spawn } from 'node:child_process'; import { randomBytes } from 'node:crypto'; import { RUN_OUTPUT_LIMIT } from '../images/build.ts'; import { suspendProgress } from './progress.ts'; -import { markWorkStarted } from './usage.ts'; +import { markWorkStarted } from './runtime.ts'; +import type { CliRuntime } from './runtime.ts'; const HOST_KEY_FAILED = /Host key verification failed/i; @@ -44,32 +45,41 @@ function sshFailure(message: string, cmd: string, args: string[], output: string /** Keep the event loop free for progress timers during SSH, Docker and file transfers. */ export function runProcess( + rt: CliRuntime, cmd: string, args: string[], { capture = false, input }: { capture?: boolean; input?: string } = {}, ): Promise<{ status: number | null; stdout: string; stderr: string }> { - markWorkStarted(); + markWorkStarted(rt); // ssh and scp may prompt on the terminal even when their output is captured. - const mayPrompt = Boolean(process.stdin.isTTY) && (cmd === 'ssh' || cmd === 'scp'); - const resume = capture && !mayPrompt ? () => {} : suspendProgress(); + const mayPrompt = Boolean(rt.stdin.isTTY) && (cmd === 'ssh' || cmd === 'scp'); + const resume = capture && !mayPrompt ? () => {} : suspendProgress(rt); const mirror = !capture && (cmd === 'ssh' || cmd === 'scp'); return new Promise<{ status: number | null; stdout: string; stderr: string }>( (resolve, reject) => { + // Output goes straight to this process's terminal only when the runtime's streams are the real ones; + // otherwise it is piped and forwarded, so an in-process run captures it like any other output. + const through = rt.inheritStdio ? 'inherit' : 'pipe'; const child = spawn(cmd, args, { + env: rt.env, + cwd: rt.cwd, stdio: [ - input === undefined ? 'inherit' : 'pipe', - capture ? 'pipe' : 'inherit', + input === undefined ? (rt.inheritStdio ? 'inherit' : 'ignore') : 'pipe', + capture ? 'pipe' : through, // ssh and scp stderr is mirrored to the terminal and kept, so a failure can be explained. - capture || mirror ? 'pipe' : 'inherit', + capture || mirror ? 'pipe' : through, ], }); + if (!capture && !rt.inheritStdio) child.stdout?.on('data', (chunk) => rt.stdout.write(chunk)); + if (!capture && !mirror && !rt.inheritStdio) + child.stderr?.on('data', (chunk) => rt.stderr.write(chunk)); let stdout = ''; let stderr = ''; child.stdout?.on('data', (chunk) => { stdout = (stdout + String(chunk)).slice(-RUN_OUTPUT_LIMIT); }); child.stderr?.on('data', (chunk) => { - if (mirror) process.stderr.write(chunk); + if (mirror) rt.stderr.write(chunk); stderr = (stderr + String(chunk)).slice(-RUN_OUTPUT_LIMIT); }); child.on('error', reject); @@ -85,18 +95,19 @@ export function runProcess( ).finally(resume); } -export async function runLocal(cmd: string, args: string[]): Promise { - const result = await runProcess(cmd, args); +export async function runLocal(rt: CliRuntime, cmd: string, args: string[]): Promise { + const result = await runProcess(rt, cmd, args); if (result.status !== 0) throw sshFailure(`${cmd} failed (exit ${result.status})`, cmd, args, result.stderr); } export async function runCapture( + rt: CliRuntime, cmd: string, args: string[], opts: { input?: string } = {}, ): Promise { - const result = await runProcess(cmd, args, { ...opts, capture: true }); + const result = await runProcess(rt, cmd, args, { ...opts, capture: true }); if (result.status !== 0) throw sshFailure( `${cmd} failed (exit ${result.status})\n${result.stderr}`, @@ -107,12 +118,6 @@ export async function runCapture( return result.stdout; } -let verbose = ['1', 'true'].includes(process.env.TUG_VERBOSE ?? ''); -/** `--verbose` (or `TUG_VERBOSE=1`): stream the output of quiet steps instead of keeping it for failures. */ -export function setVerbose(value: boolean): void { - verbose = value; -} - /** * A line a script prints to start a named stage of its work: `::tug:1a2b3c4d5e6f:: Pulling the image`. The random part is * chosen per run and only the scripts this CLI sends know it, so output of the programs they run cannot spoof a stage. @@ -139,15 +144,16 @@ export interface StepProgress { * failure reports the last lines it printed. With `--verbose` every line is streamed as it arrives. */ export async function runStep( + rt: CliRuntime, cmd: string, args: string[], { progress, input }: { progress?: StepProgress; input?: string } = {}, ): Promise { - markWorkStarted(); + markWorkStarted(rt); const tail: string[] = []; // ssh and scp may ask for a password or passphrase on the terminal, which a redrawn status line would wipe: keep the // line off the screen until the step produces its first output. - const mayPrompt = Boolean(process.stdin.isTTY) && (cmd === 'ssh' || cmd === 'scp'); + const mayPrompt = Boolean(rt.stdin.isTTY) && (cmd === 'ssh' || cmd === 'scp'); let resumed = !mayPrompt; const resume = () => { if (resumed) return; @@ -156,8 +162,10 @@ export async function runStep( }; if (mayPrompt) progress?.suspend?.(); const emit = (text: string) => - progress?.print ? progress.print(text) : void process.stderr.write(`${text}\n`); + progress?.print ? progress.print(text) : void rt.stderr.write(`${text}\n`); const child = spawn(cmd, args, { + env: rt.env, + cwd: rt.cwd, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'], }); const lines = (stream: NodeJS.ReadableStream) => { @@ -168,7 +176,7 @@ export async function runStep( if (!text) return; resume(); if (text.startsWith(STAGE_MARKER)) return progress?.stage(text.slice(STAGE_MARKER.length)); - if (verbose) emit(text); + if (rt.state.verbose) emit(text); tail.push(text); if (tail.length > TAIL_LINES) tail.shift(); progress?.detail?.(text); @@ -197,7 +205,7 @@ export async function runStep( }); if (status !== 0) throw sshFailure( - `${cmd} failed (exit ${status})${verbose || !tail.length ? '' : `\n${tail.join('\n')}`}`, + `${cmd} failed (exit ${status})${rt.state.verbose || !tail.length ? '' : `\n${tail.join('\n')}`}`, cmd, args, tail.join('\n'), diff --git a/src/cli/program.test.ts b/src/cli/program.test.ts new file mode 100644 index 0000000..7fd3269 --- /dev/null +++ b/src/cli/program.test.ts @@ -0,0 +1,162 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { LAZY_COMMANDS } from './program.ts'; +import fs from 'node:fs/promises'; +import os from 'node:os'; +import path from 'node:path'; +import { cliOutcome, execCli, withDeadline } from '../../tests/cli-inprocess.ts'; +import { testRuntime } from '../../tests/cli-runtime.ts'; +import { runCli } from './program.ts'; + +const topLevel = (help: string): string[] => + [ + ...(/\nCommands:\n([\s\S]*?)(?:\n\n|\n*$)/.exec(help)?.[1] ?? '').matchAll( + /^ {2}([a-z][a-z-]*)/gm, + ), + ] + .map((m) => m[1]) + .filter((name) => name !== 'help'); + +test('runCli returns the exit code instead of exiting the process', async () => { + const help = await cliOutcome(['--help']); + assert.equal(help.code, 0, 'help should exit 0'); + assert.match(help.stdout, /Usage: tug/, 'help should go to stdout'); + assert.equal((await cliOutcome(['--version'])).code, 0, '--version should exit 0'); + const unknown = await cliOutcome(['no-such-command']); + assert.equal(unknown.code, 1, 'an unknown command should exit 1'); + assert.match(unknown.stderr, /unknown command 'no-such-command'/, 'and say which command'); + const subcommand = await cliOutcome(['credential', 'create']); + assert.equal( + subcommand.code, + 1, + 'a missing argument of a subcommand should exit 1, not end the process', + ); +}); + +test('every top-level command is reachable by name alone, so loading only it keeps it working', async () => { + const { stdout } = await execCli(['--help']); + const names = topLevel(stdout); + assert.ok(names.length >= 25, `the full help should list every command (found ${names.length})`); + assert.deepEqual( + [...LAZY_COMMANDS].sort(), + [...names].sort(), + 'every command in the help must be registered for lazy loading, and nothing else', + ); + for (const name of names) { + const own = await cliOutcome([name, '--help']); + assert.equal(own.code, 0, `tug ${name} --help should work when only that command is loaded`); + assert.match( + own.stdout, + new RegExp(`Usage: tug ${name}\\b`), + `${name} should print its own usage`, + ); + } +}); + +test('root options before the command name still select that command', async () => { + const result = await cliOutcome([ + '--project', + 'other', + '--config=none.json', + 'credential', + '--help', + ]); + assert.equal( + result.code, + 0, + 'root options with values should be skipped when finding the command', + ); + assert.match( + result.stdout, + /Usage: tug credential/, + 'the named command should be the one loaded', + ); +}); + +test('runs overlap without sharing anything: each reads its own directory, environment and flags', async () => { + const dirs = await Promise.all( + ['alpha', 'beta'].map(async (name) => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), `tug-run-${name}-`)); + // alpha is a valid Compose file; beta has a service with a bad x-tug key. + await fs.writeFile( + path.join(dir, 'compose.yml'), + name === 'alpha' + ? 'services:\n web:\n image: nginx\n' + : 'services:\n web:\n image: nginx\n x-tug:\n replicas: many\n', + ); + return dir; + }), + ); + try { + const [alpha, beta] = await Promise.all( + dirs.map((cwd) => cliOutcome(['lint', '-f', 'compose.yml', '--json'], { cwd })), + ); + assert.equal(alpha.code, 0, 'the valid file should lint clean in its own directory'); + assert.deepEqual(JSON.parse(alpha.stdout).errors, [], 'alpha should report no findings'); + assert.equal( + beta.code, + 1, + 'the invalid file should fail in its own directory, at the same time', + ); + assert.ok(JSON.parse(beta.stdout).errors.length > 0, 'beta should report its own findings'); + } finally { + await Promise.all(dirs.map((dir) => fs.rm(dir, { recursive: true, force: true }))); + } +}); + +test('a run leaves no trace on the process or on the next run', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-trace-')); + const before = { env: { ...process.env }, cwd: process.cwd(), exitCode: process.exitCode }; + try { + await fs.writeFile(path.join(dir, 'compose.yml'), 'services: {}\n'); + const first = testRuntime({ env: { ONLY_THIS: '1' }, cwd: dir }); + await runCli(['--verbose', 'lint', '-f', 'compose.yml'], first.rt); + assert.equal(first.rt.state.verbose, true, '--verbose should be recorded on its own runtime'); + assert.equal(first.rt.state.workStarted, false, 'lint does no remote work'); + const second = testRuntime(); + assert.equal(second.rt.state.verbose, false, 'the next runtime should not inherit --verbose'); + assert.deepEqual({ ...process.env }, before.env, 'the process environment should be untouched'); + assert.equal(process.cwd(), before.cwd, 'the working directory should be untouched'); + assert.equal(process.exitCode, before.exitCode, 'the process exit code should be untouched'); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } +}); + +test('the exit code a command asks for is returned, not set on the process', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-exit-')); + try { + // A bad x-tug value makes `lint` ask for exit code 1 by setting rt.exitCode, the way commands do. + await fs.writeFile( + path.join(dir, 'bad.yml'), + 'services:\n web:\n image: nginx\n x-tug:\n replicas: many\n', + ); + await fs.writeFile(path.join(dir, 'ok.yml'), 'services: {}\n'); + const failing = testRuntime({ cwd: dir }); + assert.equal( + await runCli(['lint', '-f', 'bad.yml'], failing.rt), + 1, + 'runCli should return the code the command asked for', + ); + assert.equal(failing.rt.exitCode, 1, 'the command should record its code on the runtime'); + const passing = testRuntime({ cwd: dir }); + assert.equal(await runCli(['lint', '-f', 'ok.yml'], passing.rt), 0, 'a clean file exits 0'); + assert.equal(passing.rt.exitCode, undefined, 'a command that succeeds asks for no code'); + assert.equal(process.exitCode, undefined, 'the test process must not carry either code'); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } +}); + +test('withDeadline rejects a hung call and passes a finished one through', async () => { + await assert.rejects( + withDeadline(new Promise(() => {}), 20, 'stuck'), + /stuck/, + 'a promise that never settles should be abandoned with the given message', + ); + assert.equal( + await withDeadline(Promise.resolve(7), 1000, 'unused'), + 7, + 'a result passes through', + ); +}); diff --git a/src/cli/program.ts b/src/cli/program.ts new file mode 100644 index 0000000..31b8bd8 --- /dev/null +++ b/src/cli/program.ts @@ -0,0 +1,263 @@ +import { Command, CommanderError } from 'commander'; +import { + applyConfigDefaults, + commandPath, + integerOption, + nodeSettings, + resolveCliConfig, +} from './config.ts'; +import { CliLiveError } from './live.ts'; +import { err, processRuntime } from './runtime.ts'; +import type { CliRuntime } from './runtime.ts'; +import { addJsonOption } from './json-option.ts'; +import { CREDENTIAL_NAME_PATTERN, PROJECT_NAME_PATTERN } from '../roles.ts'; +import { packageVersion } from '../images/image.ts'; +import { errMessage } from '../errors.ts'; +import { CONFIG_HELP } from './commands/context.ts'; + +const VERBOSE_HELP = + 'show the output of quiet steps, such as Docker pulls and installers on a remote host (also TUG_VERBOSE=1)'; + +type Register = (rt: CliRuntime, program: Command) => void; + +/** + * The modules that register the top-level commands, in the order `tug --help` lists them. Each lists every top-level + * name it adds, so `tug credential list` loads one module, not all of them; `--help`, `--version` and a name that no + * module lists load every module. src/cli/program.test.ts compares the names with the real help. + */ +const REGISTRARS: { names: string[]; load: () => Promise }[] = [ + { names: ['init'], load: async () => (await import('./commands/init.ts')).registerInit }, + { + names: ['control', 'setup'], + load: async () => (await import('./commands/control.ts')).registerControl, + }, + { names: ['upgrade'], load: async () => (await import('./commands/upgrade.ts')).registerUpgrade }, + { names: ['node'], load: async () => (await import('./commands/node.ts')).registerNode }, + { + names: ['deploy', 'rollback', 'scale', 'restart'], + load: async () => (await import('./commands/deploy.ts')).registerDeploy, + }, + { + names: ['status', 'events', 'doctor'], + load: async () => (await import('./commands/observe.ts')).registerObserve, + }, + { names: ['tui'], load: async () => (await import('./commands/tui.ts')).registerTui }, + { + names: ['exec', 'run', 'ps', 'inspect', 'logs'], + load: async () => (await import('./commands/service.ts')).registerService, + }, + { names: ['hold'], load: async () => (await import('./commands/hold.ts')).registerHold }, + { names: ['image'], load: async () => (await import('./commands/image.ts')).registerImage }, + { names: ['lint'], load: async () => (await import('./commands/lint.ts')).registerLint }, + { names: ['secret'], load: async () => (await import('./commands/secret.ts')).registerSecret }, + { names: ['var'], load: async () => (await import('./commands/var.ts')).registerVar }, + { names: ['domain'], load: async () => (await import('./commands/domain.ts')).registerDomain }, + { names: ['ingress'], load: async () => (await import('./commands/ingress.ts')).registerIngress }, + { names: ['backup'], load: async () => (await import('./commands/backup.ts')).registerBackup }, + { names: ['restore'], load: async () => (await import('./commands/restore.ts')).registerRestore }, + { + names: ['credential'], + load: async () => (await import('./commands/credential.ts')).registerCredential, + }, + { names: ['volume'], load: async () => (await import('./commands/volume.ts')).registerVolume }, +]; + +/** The top-level command names that load on their own; the test compares them with `tug --help`. */ +export const LAZY_COMMANDS = REGISTRARS.flatMap((registrar) => registrar.names); + +/** + * The command the arguments name, or undefined when they ask for help, the version or something unknown. The root + * options come from the program itself, so an option added there cannot be mistaken for the command. + */ +function namedCommand(program: Command, argv: readonly string[]): string | undefined { + const flags = (option: { long?: string; short?: string }) => + [option.long, option.short].filter((flag): flag is string => !!flag); + const takesValue = new Set( + program.options.filter((o) => o.required || o.optional).flatMap(flags), + ); + const known = new Set(program.options.flatMap(flags)); + for (let i = 0; i < argv.length; i++) { + const arg = argv[i]; + const flag = arg.startsWith('--') ? arg.split('=')[0] : arg; + if (known.has(flag)) { + if (takesValue.has(flag) && !arg.includes('=')) i++; + continue; + } + return LAZY_COMMANDS.includes(arg) ? arg : undefined; + } + return undefined; +} + +async function createProgram(rt: CliRuntime, argv: readonly string[]): Promise { + const program = new Command(); + // Set before any command is added: commands copy these settings when they are created. + program.exitOverride().configureOutput({ + writeOut: (text) => void rt.stdout.write(text), + writeErr: (text) => void rt.stderr.write(text), + getOutHelpWidth: () => rt.stdout.columns ?? 80, + getErrHelpWidth: () => rt.stderr.columns ?? 80, + getOutHasColors: () => !!rt.stdout.isTTY && !rt.env.NO_COLOR, + getErrHasColors: () => !!rt.stderr.isTTY && !rt.env.NO_COLOR, + }); + program + .name('tug') + .description('Deploy Docker Compose applications to your own servers') + .version(rt.version) + .enablePositionalOptions() + .option('--config ', CONFIG_HELP) + .option( + '--control-url ', + 'connect target for the control API (the credential still verifies its own public URL)', + ) + .option( + '--credential ', + 'credential file (overrides TUG_CREDENTIAL, TUG_CREDENTIAL_FILE and config)', + ) + .option('--project ', 'project (overrides TUG_PROJECT and config; default: site)') + .option('--verbose', VERBOSE_HELP); + + const only = namedCommand(program, argv); + for (const registrar of REGISTRARS) + if (!only || registrar.names.includes(only)) (await registrar.load())(rt, program); + + /** Commands that may create the config file, so a selected file need not exist yet. */ + const CREATES_CONFIG = ['init', 'control setup']; + const NODE_NAME_FROM_ARGUMENT = ['node register', 'node replace', 'node repair', 'node upgrade']; + const NODE_NAME_FROM_OPTION = ['node add', 'node enroll']; + + program.hook('preAction', async (_root, command) => { + const path = commandPath(command); + const options = command.opts(); + for (const [key, min, max] of [ + ['port', 1, 65535], + ['timeout', 1, 86400], + ['ttl', 1, 31536000], + ['uses', 1, 1000000], + ['expiresInDays', 1, 3650], + ['limit', 1, 500], + ['tail', 0, 1000000], + ] as const) { + if (options[key] !== undefined) + integerOption( + String(options[key]), + '--' + key.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase()), + min, + max, + ); + } + if (path === 'control restore' && options.snapshot && !options.fromDestination) + throw new Error('--snapshot goes with --from-destination'); + if (path === 'control restore' && options.passwordStdin && !options.fromDestination) + throw new Error('--password-stdin goes with --from-destination'); + const positional = path === 'exec' ? command.args.slice(0, 1) : command.args; + for (const value of [ + ...positional, + ...Object.values(options), + ...Object.values(program.opts()), + ]) + if (typeof value === 'string' && /[\r\n\0]/.test(value)) + throw new Error('arguments and option values must not contain line breaks or NUL'); + if (path === 'exec' && command.args.slice(1).some((value) => value.includes('\0'))) + throw new Error('exec command arguments must not contain NUL'); + if (options.name && !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(options.name)) + throw new Error('--name must contain only letters, numbers, dots, underscores or hyphens'); + const connection = command.optsWithGlobals(); + if (connection.verbose) rt.state.verbose = true; + if (path === 'credential create') { + // --project is repeatable here and scopes the new credential, so it must not also select the connection project. + if (!CREDENTIAL_NAME_PATTERN.test(command.args[0])) + throw new Error( + 'credential name must be 1-64 letters, numbers, dots, underscores or hyphens, starting with a letter or number', + ); + for (const project of options.project as string[]) + if (!PROJECT_NAME_PATTERN.test(project)) + throw new Error( + '--project must contain only letters, numbers, dots, underscores or hyphens', + ); + if (options.role === 'admin' && options.project.length) + throw new Error( + 'admin credentials cannot be limited to projects; use --role read or --role deploy with --project', + ); + connection.project = undefined; + } + const resolved = await resolveCliConfig( + connection, + rt.env, + rt.cwd, + CREATES_CONFIG.includes(path), + ); + rt.state.config = resolved; + // Config values are defaults for options not given on the command line; nodes are only read by the + // commands that create or register one, never by commands that talk to an existing node. + const nodeName = NODE_NAME_FROM_ARGUMENT.includes(path) + ? command.args[0] + : NODE_NAME_FROM_OPTION.includes(path) + ? (options.name as string | undefined) + : undefined; + applyConfigDefaults(command, options, { + ...resolved.commandDefaults, + ...(path.startsWith('node ') || path === 'control setup' || path === 'control upgrade' + ? nodeSettings(resolved, nodeName) + : {}), + }); + }); + + /** Every command that does work accepts the connection options, so they can follow the command. */ + function addConnectionOptions(command: Command): void { + if (command.commands.length) { + for (const child of command.commands) addConnectionOptions(child); + // `deploy` is both a command and the parent of `deploy cancel`. + if (!command.options.length) return; + } + command + .option('--config ', CONFIG_HELP) + .option( + '--control-url ', + 'connect target for the control API (the credential still verifies its own public URL)', + ) + .option( + '--credential ', + 'credential file (overrides TUG_CREDENTIAL, TUG_CREDENTIAL_FILE and config)', + ); + // exec and run forward everything after the service to a remote command, which may take its own --verbose. + if (!['exec', 'run'].includes(command.name())) command.option('--verbose', VERBOSE_HELP); + if (!command.options.some((option) => option.long === '--project')) + command.option( + '--project ', + 'project (overrides TUG_PROJECT and config; default: site)', + ); + } + function forbidExtraArguments(command: Command): void { + command.allowExcessArguments(false); + for (const child of command.commands) forbidExtraArguments(child); + } + for (const command of program.commands) addJsonOption(command); + for (const command of program.commands) addConnectionOptions(command); + forbidExtraArguments(program); + program.showHelpAfterError(); + + return program; +} + +/** + * Runs the CLI with the given arguments (without node and the script) and returns the exit code. Everything it reads + * from or writes to the process goes through `rt`, so a test passes a runtime of its own and runs it in-process. + */ +export async function runCli( + argv: readonly string[], + rt: CliRuntime = processRuntime(packageVersion()), +): Promise { + try { + const program = await createProgram(rt, argv); + await program.parseAsync([...argv], { from: 'user' }); + return rt.exitCode ?? 0; + } catch (e) { + // Commander has already printed its own usage errors, help and version. + if (e instanceof CommanderError) return e.exitCode; + const message = errMessage(e); + // An error before any work began is a mistake in the arguments; one after that, or a cancellation, is not. + const usage = !rt.state.workStarted && !/^cancelled/.test(message); + err(rt, usage ? `${message}\nRun tug --help for usage.` : message); + return e instanceof CliLiveError ? e.exitCode : 1; + } +} diff --git a/src/cli/progress.test.ts b/src/cli/progress.test.ts index 5b0b95e..33b994f 100644 --- a/src/cli/progress.test.ts +++ b/src/cli/progress.test.ts @@ -1,11 +1,13 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { createProgress, suspendProgress } from './progress.ts'; +import { testRuntime } from '../../tests/cli-runtime.ts'; test('progress reports stages immediately and elapsed time while work is pending', (t) => { + const { rt } = testRuntime(); t.mock.timers.enable({ apis: ['Date', 'setInterval'], now: 0 }); const lines: string[] = []; - const progress = createProgress({ write: (line) => lines.push(line) }); + const progress = createProgress(rt, { write: (line) => lines.push(line) }); try { progress.stage('Building images'); assert.deepEqual(lines, ['[0s] Building images'], 'a stage must be visible before work starts'); @@ -33,15 +35,17 @@ test('progress reports stages immediately and elapsed time while work is pending }); test('scoped progress stops heartbeats on success, early return and rejection', async (t) => { + const run = testRuntime(); const { withProgress } = await import('./progress.ts'); t.mock.timers.enable({ apis: ['Date', 'setInterval'], now: 0 }); - const lines: string[] = []; - t.mock.method(process.stderr, 'write', (line: string) => { - lines.push(line); - return true; - }); + // Progress writes one line per report to the runtime's stderr. + const lines = { + get length() { + return run.stderr().split('\n').length - 1; + }, + }; for (const fails of [false, true]) { - const operation = withProgress('Waiting', async () => { + const operation = withProgress(run.rt, 'Waiting', async () => { t.mock.timers.tick(10_000); if (fails) throw new Error('operation failed'); return 42; @@ -64,9 +68,10 @@ test('scoped progress stops heartbeats on success, early return and rejection', }); test('a terminal gets one live line and finished stages stay as lines', (t) => { + const { rt } = testRuntime(); t.mock.timers.enable({ apis: ['Date', 'setInterval'], now: 0 }); let screen = ''; - const progress = createProgress({ + const progress = createProgress(rt, { live: { write: (text) => (screen += text), columns: () => 60 }, }); progress.stage('Pulling image'); @@ -97,9 +102,10 @@ test('a terminal gets one live line and finished stages stay as lines', (t) => { }); test('printing above the live line clears it first and draws it again', (t) => { + const { rt } = testRuntime(); t.mock.timers.enable({ apis: ['Date', 'setInterval'], now: 0 }); let screen = ''; - const progress = createProgress({ + const progress = createProgress(rt, { live: { write: (text) => (screen += text), columns: () => 80 }, }); progress.stage('Installing'); @@ -114,10 +120,11 @@ test('printing above the live line clears it first and draws it again', (t) => { }); test('other output is kept off the live line, and an unfinished line keeps the status hidden', (t) => { + const { rt } = testRuntime(); t.mock.timers.enable({ apis: ['Date', 'setInterval'], now: 0 }); let screen = ''; let hook: { before(): void; after(endedLine: boolean): void } | undefined; - const progress = createProgress({ + const progress = createProgress(rt, { live: { write: (text) => (screen += text), columns: () => 80, @@ -148,9 +155,10 @@ test('other output is kept off the live line, and an unfinished line keeps the s }); test('remote output is shown as data and a started progress can be suspended by prompts and menus', (t) => { + const { rt } = testRuntime(); t.mock.timers.enable({ apis: ['Date', 'setInterval'], now: 0 }); let screen = ''; - const progress = createProgress({ + const progress = createProgress(rt, { live: { write: (text) => (screen += text), columns: () => 80 }, }); progress.stage('Installing'); @@ -160,7 +168,7 @@ test('remote output is shown as data and a started progress can be suspended by !/[\x07\t]|\x1b\]/.test(screen.split('\r\x1b[K').pop()!), 'control characters from a remote host must not reach the terminal', ); - const resume = suspendProgress(); + const resume = suspendProgress(rt); screen = ''; t.mock.timers.tick(3_000); assert.equal( diff --git a/src/cli/progress.ts b/src/cli/progress.ts index 6645d5f..ec4aee0 100644 --- a/src/cli/progress.ts +++ b/src/cli/progress.ts @@ -1,5 +1,6 @@ import { clipToColumns, plainText } from './width.ts'; -import { markWorkStarted } from './usage.ts'; +import { markWorkStarted } from './runtime.ts'; +import type { CliRuntime } from './runtime.ts'; /** Where a live (terminal) status line is drawn. */ export interface LiveOutput { @@ -12,14 +13,14 @@ export interface LiveOutput { const CLEAR_LINE = '\r\x1b[K'; /** A single rewritten status line only makes sense on an interactive stderr outside CI. */ -function terminalOutput(): LiveOutput | undefined { - if (!process.stderr.isTTY || process.env.CI) return undefined; - const raw = process.stderr.write.bind(process.stderr); +function terminalOutput(rt: CliRuntime): LiveOutput | undefined { + if (!rt.stderr.isTTY || rt.env.CI) return undefined; + const raw = rt.stderr.write.bind(rt.stderr); return { write: (text) => void raw(text), - columns: () => process.stderr.columns || 80, + columns: () => rt.stderr.columns || 80, intercept(hook) { - const restores = [process.stdout, process.stderr].map((stream) => { + const restores = [rt.stdout, rt.stderr].map((stream) => { const original = stream.write; const wrapped = function (this: unknown, ...args: unknown[]) { hook.before(); @@ -46,26 +47,27 @@ function terminalOutput(): LiveOutput | undefined { }; } -let current: ReturnType | undefined; - /** * Progress on stderr, so stdout results stay clean. On a terminal it is one live line, `[12s] label · latest output`, and a * finished stage stays behind as `[Ns] label`; other output written meanwhile appears above it. Without a terminal (or in * CI) it prints a line per stage plus an elapsed-time heartbeat, which reads well in logs. */ -export function createProgress({ - write = (line: string): void => { - process.stderr.write(`${line}\n`); - }, - now = Date.now, - intervalMs = 10_000, - live = terminalOutput(), -}: { - write?: (line: string) => void; - now?: () => number; - intervalMs?: number; - live?: LiveOutput; -} = {}) { +export function createProgress( + rt: CliRuntime, + { + write = (line: string): void => { + rt.stderr.write(`${line}\n`); + }, + now = Date.now, + intervalMs = 10_000, + live = terminalOutput(rt), + }: { + write?: (line: string) => void; + now?: () => number; + intervalMs?: number; + live?: LiveOutput; + } = {}, +) { let label = ''; let detail = ''; let started = now(); @@ -75,7 +77,7 @@ export function createProgress({ let partial = false; let timer: ReturnType | undefined; let undoIntercept: (() => void) | undefined; - let outer: typeof current; + let outer: Progress | undefined; const elapsed = () => `[${Math.floor((now() - started) / 1000)}s] ${label}`; const clear = () => { if (live && drawn) live.write(CLEAR_LINE); @@ -100,8 +102,8 @@ export function createProgress({ detail = ''; started = now(); if (!timer) { - outer = current; - current = self; + outer = rt.state.progress; + rt.state.progress = self; timer = setInterval(report, live ? 1000 : intervalMs); timer.unref(); undoIntercept = live?.intercept?.({ @@ -142,7 +144,7 @@ export function createProgress({ clearInterval(timer); if (timer) { timer = undefined; - if (current === self) current = outer; + if (rt.state.progress === self) rt.state.progress = outer; } undoIntercept?.(); undoIntercept = undefined; @@ -156,19 +158,20 @@ export function createProgress({ export type Progress = ReturnType; /** Run a process, prompt or menu that writes straight to the terminal without the live status line scribbling over it. */ -export function suspendProgress(): () => void { - const progress = current; +export function suspendProgress(rt: CliRuntime): () => void { + const progress = rt.state.progress; progress?.suspend(); return () => progress?.resume(); } /** Own the timer for one operation, including failures and early returns. */ export async function withProgress( + rt: CliRuntime, label: string, operation: (progress: Progress) => Promise, ): Promise { - markWorkStarted(); - const progress = createProgress(); + markWorkStarted(rt); + const progress = createProgress(rt); try { progress.stage(label); return await operation(progress); diff --git a/src/cli/prompt.test.ts b/src/cli/prompt.process.test.ts similarity index 83% rename from src/cli/prompt.test.ts rename to src/cli/prompt.process.test.ts index 5f4485f..f214096 100644 --- a/src/cli/prompt.test.ts +++ b/src/cli/prompt.process.test.ts @@ -6,18 +6,22 @@ import path from 'node:path'; import test from 'node:test'; import { promisify } from 'node:util'; import { pathToFileURL } from 'node:url'; +import { cliEntry } from '../../tests/cli-process.ts'; const exec = promisify(execFile); test('repeated visible and hidden prompts release stdin after answering without EOF', async () => { const promptUrl = pathToFileURL(path.resolve('src/cli/prompt.ts')).href; + const runtimeUrl = pathToFileURL(path.resolve('src/cli/runtime.ts')).href; const running = exec( process.execPath, [ '--input-type=module', '-e', - `import { ask } from ${JSON.stringify(promptUrl)}; + `import { prompter } from ${JSON.stringify(promptUrl)}; + import { processRuntime } from ${JSON.stringify(runtimeUrl)}; import assert from 'node:assert/strict'; + const ask = prompter(processRuntime('0.0.0')); const events = ['keypress', 'end', 'error']; const before = events.map(event => process.stdin.listenerCount(event)); const first = await ask('First answer: '); @@ -52,13 +56,15 @@ test('repeated visible and hidden prompts release stdin after answering without test('a prompt rejects and exits when stdin closes before an answer', async () => { const promptUrl = pathToFileURL(path.resolve('src/cli/prompt.ts')).href; + const runtimeUrl = pathToFileURL(path.resolve('src/cli/runtime.ts')).href; const running = exec( process.execPath, [ '--input-type=module', '-e', - `import { ask } from ${JSON.stringify(promptUrl)}; - await ask('Answer: ');`, + `import { prompter } from ${JSON.stringify(promptUrl)}; + import { processRuntime } from ${JSON.stringify(runtimeUrl)}; + await prompter(processRuntime('0.0.0'))('Answer: ');`, ], { timeout: 60_000 }, ); @@ -85,11 +91,11 @@ test('CLI exits after a prompted command fails while stdin stays open', async () 'process.stdin.isTTY = true; process.stdout.isTTY = true;', )}`; try { - const running = exec( - process.execPath, - ['--import', terminal, path.resolve('src/cli.ts'), 'node', 'add'], - { cwd: dir, env: { ...process.env, TUG_CONFIG: '', CI: '' }, timeout: 60_000 }, - ); + const running = exec(process.execPath, ['--import', terminal, cliEntry, 'node', 'add'], { + cwd: dir, + env: { ...process.env, TUG_CONFIG: '', CI: '' }, + timeout: 60_000, + }); let answered = false; running.child.stderr!.on('data', (data) => { if (!answered && String(data).includes('Node name')) { diff --git a/src/cli/prompt.ts b/src/cli/prompt.ts index cba35f5..bd5d4dd 100644 --- a/src/cli/prompt.ts +++ b/src/cli/prompt.ts @@ -1,50 +1,54 @@ import readline from 'node:readline'; import { Writable } from 'node:stream'; import { suspendProgress } from './progress.ts'; +import type { CliRuntime } from './runtime.ts'; /** True when both ends are a terminal and the run is not CI, so asking a question can be answered. */ -export function canPrompt(env: NodeJS.ProcessEnv = process.env): boolean { - return !!process.stdin.isTTY && !!process.stdout.isTTY && !env.CI; +export function canPrompt(rt: CliRuntime): boolean { + return !!rt.stdin.isTTY && !!rt.stdout.isTTY && !rt.env.CI; } export type Prompter = (question: string, hidden?: boolean) => Promise; -/** Ask a line of text on the terminal; with `hidden` the typed characters are not echoed. */ -export const ask: Prompter = async (question, hidden = false) => { - // A keyboard menu leaves stdin unreferenced so a finished menu cannot hold the process open; a question needs it held. - process.stdin.ref?.(); - // The question owns the line it is typed on, so a live progress line must stay off the screen meanwhile. - const resumeProgress = suspendProgress(); - const muted = { on: false }; - const output = new Writable({ - write(chunk, _encoding, callback) { - if (!muted.on) process.stderr.write(chunk); - callback(); - }, - }); - const rl = readline.createInterface({ input: process.stdin, output, terminal: true }); - try { - return await new Promise((resolve, reject) => { - const onClose = () => reject(new Error('input closed before an answer was given')); - rl.once('close', onClose); - rl.question(question, (answer) => { - rl.off('close', onClose); - if (hidden) process.stderr.write('\n'); - resolve(answer); - }); - muted.on = hidden; +/** Asks a line of text on this run's terminal; with `hidden` the typed characters are not echoed. */ +export const prompter = + (rt: CliRuntime): Prompter => + async (question, hidden = false) => { + // A keyboard menu leaves stdin unreferenced so a finished menu cannot hold the process open; a question needs it held. + rt.stdin.ref?.(); + // The question owns the line it is typed on, so a live progress line must stay off the screen meanwhile. + const resumeProgress = suspendProgress(rt); + const muted = { on: false }; + const output = new Writable({ + write(chunk, _encoding, callback) { + if (!muted.on) rt.stderr.write(chunk); + callback(); + }, }); - } finally { - rl.close(); - resumeProgress(); - } -}; + const rl = readline.createInterface({ input: rt.stdin, output, terminal: true }); + try { + return await new Promise((resolve, reject) => { + const onClose = () => reject(new Error('input closed before an answer was given')); + rl.once('close', onClose); + rl.question(question, (answer) => { + rl.off('close', onClose); + if (hidden) rt.stderr.write('\n'); + resolve(answer); + }); + muted.on = hidden; + }); + } finally { + rl.close(); + resumeProgress(); + } + }; /** A yes/no question; an empty answer takes `fallback`. */ export async function confirm( + rt: CliRuntime, question: string, fallback = true, - prompt: Prompter = ask, + prompt: Prompter = prompter(rt), ): Promise { for (;;) { const answer = (await prompt(`${question} ${fallback ? '(Y/n)' : '(y/N)'} `)) diff --git a/src/cli/runtime-boundary.test.ts b/src/cli/runtime-boundary.test.ts new file mode 100644 index 0000000..b362d3e --- /dev/null +++ b/src/cli/runtime-boundary.test.ts @@ -0,0 +1,60 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { ESLint } from 'eslint'; + +// The CLI reaches its process only through a CliRuntime (docs/architecture.md#the-cli-runtime). These tests run the +// repository's own ESLint configuration over small snippets, so the rule that keeps that boundary cannot be loosened +// or bypassed by a new spelling without a test failing. + +const eslint = new ESLint({ cwd: process.cwd() }); + +async function errors(code: string, filePath: string): Promise { + const [result] = await eslint.lintText(code, { filePath }); + return result.messages.filter((m) => m.severity === 2).map((m) => `${m.ruleId}: ${m.message}`); +} + +const FORBIDDEN: [string, string][] = [ + ['reading the process environment', 'export const a = process.env.HOME;'], + ['the working directory of the process', 'export const a = process.cwd();'], + ['writing to the process streams', "process.stdout.write('x');"], + ['console output', "console.log('x');"], + ['globalThis.process', 'export const a = globalThis.process.env.HOME;'], + ['globalThis.console', "globalThis.console.log('x');"], + [ + 'the process imported by default', + "import process from 'node:process';\nexport const a = process;", + ], + ['named imports of the process', "import { env } from 'node:process';\nexport const a = env;"], + ['a bare process import', "import process from 'process';\nexport const a = process;"], + ['os.homedir', "import os from 'node:os';\nexport const a = os.homedir();"], + ['a named homedir import', "import { homedir } from 'node:os';\nexport const a = homedir();"], +]; + +test('src/cli cannot reach the process, the console or the home directory except through the runtime', async () => { + for (const [name, code] of FORBIDDEN) + assert.ok( + (await errors(code, 'src/cli/example.ts')).length > 0, + `ESLint should reject ${name} in src/cli`, + ); +}); + +test('the runtime module, tests and code outside src/cli may use the process', async () => { + const code = "export const a = process.env.HOME;\nconsole.log('x');"; + assert.deepEqual(await errors(code, 'src/cli/runtime.ts'), [], 'runtime.ts is the one boundary'); + assert.deepEqual(await errors(code, 'src/cli/example.test.ts'), [], 'tests may use the process'); + assert.deepEqual(await errors(code, 'src/control/example.ts'), [], 'other roles are not covered'); +}); + +test('code that takes everything from the runtime is accepted', async () => { + const code = [ + "import path from 'node:path';", + "import { err, homeDir, out, resolvePath } from './runtime.ts';", + "import type { CliRuntime } from './runtime.ts';", + 'export function run(rt: CliRuntime): string {', + ' out(rt, rt.env.HOME ?? homeDir(rt));', + " err(rt, 'warned');", + " return path.join(resolvePath(rt, 'x'), rt.cwd);", + '}', + ].join('\n'); + assert.deepEqual(await errors(code, 'src/cli/example.ts'), [], 'the runtime forms are the way'); +}); diff --git a/src/cli/runtime.ts b/src/cli/runtime.ts new file mode 100644 index 0000000..410d295 --- /dev/null +++ b/src/cli/runtime.ts @@ -0,0 +1,113 @@ +import type { EventEmitter } from 'node:events'; +import os from 'node:os'; +import path from 'node:path'; +import { format } from 'node:util'; +import type { Readable, Writable } from 'node:stream'; +import type { ResolvedCliConfig } from './config.ts'; +import type { Progress } from './progress.ts'; + +// The CLI's boundary with the process it runs in. Everything in src/cli that would otherwise read `process.env`, +// `process.cwd()`, `process.stdin/stdout/stderr`, `console`, a process signal or `process.exitCode` receives a +// `CliRuntime` instead. `tug` builds one from the real process (`processRuntime`); tests build one from plain objects +// (`tests/cli-inprocess.ts`), so a command runs in-process, in parallel with others, without patching any global. +// ESLint (eslint.config.js) rejects the ambient forms in src/cli outside this file and the entry point. + +/** A readable stream that may be a terminal. */ +export interface CliInput extends Readable { + isTTY?: boolean; + setRawMode?(mode: boolean): unknown; + ref?(): unknown; + unref?(): unknown; +} + +/** A writable stream that may be a terminal. */ +export interface CliOutput extends Writable { + isTTY?: boolean; + columns?: number; +} + +/** + * What one run of the CLI remembers. It lives on the runtime, so two runs never share it and nothing needs resetting + * between them. + */ +export interface CliState { + /** `--verbose` or `TUG_VERBOSE=1`: stream the output of quiet steps. */ + verbose: boolean; + /** Set once a command begins real work; an error after that is not a usage mistake (no `--help` footer). */ + workStarted: boolean; + /** The configuration the root `preAction` hook resolved for this run. */ + config?: ResolvedCliConfig; + /** Controls whose version agreement was already checked in this run (base, trusted CA mark and address override). */ + versionChecked: Set; + /** The innermost running progress display, so a prompt can pause it. */ + progress?: Progress; +} + +export interface CliRuntime { + env: NodeJS.ProcessEnv; + cwd: string; + stdin: CliInput; + stdout: CliOutput; + stderr: CliOutput; + /** True when the streams are this process's own, so child processes may inherit them instead of being piped. */ + inheritStdio: boolean; + /** The version this CLI reports and compares against the control's. */ + version: string; + /** Process signals and exit, which a command subscribes to for cleanup; a test runtime has its own emitter. */ + signals: EventEmitter; + /** Sends the signal to this process, for a handler that restored the terminal and now lets the signal act. */ + raise(signal: NodeJS.Signals): void; + /** The exit code a command asked for; the entry point applies it. Unset means success. */ + exitCode?: number; + state: CliState; +} + +export const isVerboseEnv = (env: NodeJS.ProcessEnv): boolean => + ['1', 'true'].includes(env.TUG_VERBOSE ?? ''); + +export const freshState = (env: NodeJS.ProcessEnv): CliState => ({ + verbose: isVerboseEnv(env), + workStarted: false, + versionChecked: new Set(), +}); + +/** The runtime of the real process. */ +export function processRuntime(version: string): CliRuntime { + return { + env: process.env, + cwd: process.cwd(), + stdin: process.stdin, + stdout: process.stdout, + stderr: process.stderr, + inheritStdio: true, + version, + signals: process, + raise: (signal) => void process.kill(process.pid, signal), + state: freshState(process.env), + }; +} + +/** Writes a line to stdout, formatted like `console.log`. */ +export function out(rt: CliRuntime, ...args: unknown[]): void { + rt.stdout.write(`${format(...args)}\n`); +} + +/** Writes a line to stderr, formatted like `console.error`. */ +export function err(rt: CliRuntime, ...args: unknown[]): void { + rt.stderr.write(`${format(...args)}\n`); +} + +/** The user's home directory according to this run's environment. */ +export function homeDir(rt: CliRuntime): string { + return rt.env.HOME || rt.env.USERPROFILE || os.homedir(); +} + +/** A path from the command line, resolved against this run's working directory like a shell would. */ +export function resolvePath(rt: CliRuntime, file: string): string { + return path.resolve(rt.cwd, file); +} + +/** Records that real work started, so a later error does not point at `--help`. */ +export function markWorkStarted(rt: CliRuntime): void { + rt.state.workStarted = true; +} diff --git a/src/cli/selection-live.test.ts b/src/cli/selection-live.process.test.ts similarity index 93% rename from src/cli/selection-live.test.ts rename to src/cli/selection-live.process.test.ts index 5e06a2e..97608ce 100644 --- a/src/cli/selection-live.test.ts +++ b/src/cli/selection-live.process.test.ts @@ -12,6 +12,7 @@ import { Pki, identityUri, serverNames } from '../pki.ts'; import { packageVersion } from '../images/image.ts'; import { serverTlsOptions } from '../control/tls-server.ts'; import { keysFor, menuCount } from './test-keys.ts'; +import { cliEntry } from '../../tests/cli-process.ts'; const exec = promisify(execFile); test('live command selection sends exact services, eligible nodes and remote arguments without contaminating stdout', async () => { @@ -76,25 +77,21 @@ test('live command selection sends exact services, eligible nodes and remote arg const url = `https://127.0.0.1:${(https.address() as { port: number }).port}`; const fakeTerminal = `data:text/javascript,${encodeURIComponent('process.stdin.isTTY=true; process.stdout.isTTY=true;')}`; const run = (args: string[], answers: string[] = [], env: Record = {}) => { - const running = exec( - process.execPath, - ['--import', fakeTerminal, path.resolve('src/cli.ts'), ...args], - { - cwd: dir, - env: { - ...process.env, - TUG_CONFIG: '', - TUG_PROJECT: 'site', - TUG_CREDENTIAL: '', - TUG_CREDENTIAL_FILE: credentialFile, - TUG_CONTROL_URL: url, - CI: '', - TERM: 'xterm-256color', - ...env, - }, - timeout: 60_000, + const running = exec(process.execPath, ['--import', fakeTerminal, cliEntry, ...args], { + cwd: dir, + env: { + ...process.env, + TUG_CONFIG: '', + TUG_PROJECT: 'site', + TUG_CREDENTIAL: '', + TUG_CREDENTIAL_FILE: credentialFile, + TUG_CONTROL_URL: url, + CI: '', + TERM: 'xterm-256color', + ...env, }, - ); + timeout: 60_000, + }); let text = ''; let answered = 0; running.child.stderr!.on('data', (data) => { diff --git a/src/cli/selection.ts b/src/cli/selection.ts index f226079..e6d638c 100644 --- a/src/cli/selection.ts +++ b/src/cli/selection.ts @@ -1,6 +1,7 @@ import { canPrompt } from './prompt.ts'; import { terminalPicker } from './pick.ts'; import type { Picker } from './pick.ts'; +import type { CliRuntime } from './runtime.ts'; export interface Choice { value: string; @@ -9,18 +10,18 @@ export interface Choice { export interface SelectionIO extends Picker { interactive: boolean; } -const terminal = (): SelectionIO => ({ - interactive: canPrompt(), - one: (...args) => terminalPicker.one(...args), - many: (...args) => terminalPicker.many(...args), -}); +/** Selection on this run's terminal. */ +export const terminalSelection = (rt: CliRuntime): SelectionIO => { + const picker = terminalPicker(rt); + return { interactive: canPrompt(rt), one: picker.one, many: picker.many }; +}; /** Resolve lazily so explicit arguments never need a discovery request. */ export async function selectOne( value: string | undefined, question: string, load: () => Promise, - io = terminal(), + io: SelectionIO, ): Promise { if (value) return value; const selected = await selectChoices(question, load, false, io); @@ -29,7 +30,7 @@ export async function selectOne( export async function selectMany( question: string, load: () => Promise, - io = terminal(), + io: SelectionIO, ): Promise { return selectChoices(question, load, true, io); } diff --git a/src/cli/ssh-hostkey.test.ts b/src/cli/ssh-hostkey.test.ts index 7be7547..b923d36 100644 --- a/src/cli/ssh-hostkey.test.ts +++ b/src/cli/ssh-hostkey.test.ts @@ -1,16 +1,15 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { execFile } from 'node:child_process'; import fs from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; -import { promisify } from 'node:util'; import { startMtlsControl } from '../../tests/helpers.ts'; import { discoverAddresses, hostHasDocker, remoteHostname } from './commands/host.ts'; import { runCapture, runLocal, runStep, SshHostKeyError, sshHostKeyHint } from './process.ts'; +import { execCli } from '../../tests/cli-inprocess.ts'; +import { testRuntime } from '../../tests/cli-runtime.ts'; +import type { CliRuntime } from './runtime.ts'; -const execFileAsync = promisify(execFile); -const cliEntry = path.resolve('src/cli.ts'); const REFUSAL = 'Host key verification failed.'; test('sshHostKeyHint names the host and the ssh-keygen -R remedy only for a host key refusal', () => { @@ -50,18 +49,17 @@ test('sshHostKeyHint names the host and the ssh-keygen -R remedy only for a host async function withFakeSsh( script: string, - run: (dir: string, env: NodeJS.ProcessEnv) => Promise, + run: (dir: string, env: NodeJS.ProcessEnv, rt: CliRuntime) => Promise, ): Promise { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-hostkey-')); const bin = path.join(dir, 'bin'); await fs.mkdir(bin); await fs.writeFile(path.join(bin, 'ssh'), `#!/bin/sh\n${script}\n`, { mode: 0o755 }); - const previous = process.env.PATH; - process.env.PATH = `${bin}${path.delimiter}${previous}`; + // The fake ssh is found through this run's PATH; this process's own is never touched. + const env = { ...process.env, PATH: `${bin}${path.delimiter}${process.env.PATH}` }; try { - return await run(dir, { ...process.env, PATH: process.env.PATH }); + return await run(dir, env, testRuntime({ env }).rt); } finally { - process.env.PATH = previous; await fs.rm(dir, { recursive: true, force: true }); } } @@ -69,12 +67,12 @@ async function withFakeSsh( const REFUSE = `echo '${REFUSAL}' >&2; exit 255`; test('runStep, runCapture and runLocal explain a host key refusal and keep other ssh failures as they are', async () => { - await withFakeSsh(REFUSE, async () => { + await withFakeSsh(REFUSE, async (_dir, _env, rt) => { const args = ['--', 'root@203.0.113.9', 'true']; for (const [name, run] of [ - ['runStep', () => runStep('ssh', args)], - ['runCapture', () => runCapture('ssh', args)], - ['runLocal', () => runLocal('ssh', args)], + ['runStep', () => runStep(rt, 'ssh', args)], + ['runCapture', () => runCapture(rt, 'ssh', args)], + ['runLocal', () => runLocal(rt, 'ssh', args)], ] as const) { const error = await run().then( () => undefined, @@ -91,8 +89,8 @@ test('runStep, runCapture and runLocal explain a host key refusal and keep other ); } }); - await withFakeSsh(`echo 'Connection refused' >&2; exit 255`, async () => { - const error = await runCapture('ssh', ['--', 'root@h', 'true']).then( + await withFakeSsh(`echo 'Connection refused' >&2; exit 255`, async (_dir, _env, rt) => { + const error = await runCapture(rt, 'ssh', ['--', 'root@h', 'true']).then( () => undefined, (e: unknown) => e as Error, ); @@ -104,11 +102,11 @@ test('runStep, runCapture and runLocal explain a host key refusal and keep other }); test('host probes stop on a host key refusal instead of reading it as no Docker or no answer', async () => { - await withFakeSsh(REFUSE, async () => { + await withFakeSsh(REFUSE, async (_dir, _env, rt) => { for (const [name, probe] of [ - ['hostHasDocker', () => hostHasDocker('root@203.0.113.9')], - ['remoteHostname', () => remoteHostname('root@203.0.113.9')], - ['discoverAddresses', () => discoverAddresses('root@203.0.113.9')], + ['hostHasDocker', () => hostHasDocker(rt, 'root@203.0.113.9')], + ['remoteHostname', () => remoteHostname(rt, 'root@203.0.113.9')], + ['discoverAddresses', () => discoverAddresses(rt, 'root@203.0.113.9')], ] as const) assert.throws( probe, @@ -116,9 +114,9 @@ test('host probes stop on a host key refusal instead of reading it as no Docker `${name} should raise the host key explanation`, ); }); - await withFakeSsh('exit 1', async () => { + await withFakeSsh('exit 1', async (_dir, _env, rt) => { assert.equal( - hostHasDocker('root@h'), + hostHasDocker(rt, 'root@h'), false, 'a host without Docker still reads as false, not as an error', ); @@ -146,8 +144,7 @@ test('every command that runs ssh prints the ssh-keygen -R remedy and never touc const target = 'root@203.0.113.9'; // Registered by an earlier add, as for any host that is already a node. await control.registerNode('n1'); - const cli = (...args: string[]) => - execFileAsync(process.execPath, [cliEntry, ...args], { env, cwd: dir }); + const cli = (...args: string[]) => execCli([...args], { env, cwd: dir }); try { for (const args of [ ['node', 'add', target, '--name', 'n1', '--no-wait'], diff --git a/src/cli/stdin.test.ts b/src/cli/stdin.process.test.ts similarity index 90% rename from src/cli/stdin.test.ts rename to src/cli/stdin.process.test.ts index a8a1b4e..0b2ea28 100644 --- a/src/cli/stdin.test.ts +++ b/src/cli/stdin.process.test.ts @@ -6,6 +6,7 @@ import path from 'node:path'; import test from 'node:test'; import { promisify } from 'node:util'; import { startMtlsControl } from '../../tests/helpers.ts'; +import { cliEntry, mainEntry } from '../../tests/cli-process.ts'; const exec = promisify(execFile); @@ -23,7 +24,7 @@ test('whole-document stdin commands and HTTP commands exit after completing thei AWS_SECRET_ACCESS_KEY: undefined, }; const run = (entry: string, args: string[], input?: string) => { - const running = exec(process.execPath, [path.resolve(entry), ...args], { + const running = exec(process.execPath, [entry, ...args], { cwd: dir, env, timeout: 60_000, @@ -32,7 +33,7 @@ test('whole-document stdin commands and HTTP commands exit after completing thei if (input !== undefined) running.child.stdin!.end(input); return running; }; - const cli = (args: string[], input?: string) => run('src/cli.ts', args, input); + const cli = (args: string[], input?: string) => run(cliEntry, args, input); try { const imported = await cli(['init', '-'], JSON.stringify(control.root)); assert.match( @@ -41,7 +42,7 @@ test('whole-document stdin commands and HTTP commands exit after completing thei 'init should import stdin and exit after EOF', ); - const identity = await run('src/main.ts', ['agent', 'identity']); + const identity = await run(mainEntry, ['agent', 'identity']); assert.match( identity.stdout, /BEGIN CERTIFICATE REQUEST/, @@ -53,7 +54,7 @@ test('whole-document stdin commands and HTTP commands exit after completing thei 'app1', 'node register should read the complete CSR and exit after the API response', ); - const installed = await run('src/main.ts', ['agent', 'install-cert'], registered.stdout); + const installed = await run(mainEntry, ['agent', 'install-cert'], registered.stdout); assert.match( installed.stdout, /installed identity for node app1/, diff --git a/src/cli/templates.test.ts b/src/cli/templates.process.test.ts similarity index 99% rename from src/cli/templates.test.ts rename to src/cli/templates.process.test.ts index ef11fed..fa25296 100644 --- a/src/cli/templates.test.ts +++ b/src/cli/templates.process.test.ts @@ -10,10 +10,9 @@ import { createCsr, generateKeyPair } from '../pki.ts'; import { defaultImage } from '../images/image.ts'; import { createTransport } from '../transport.ts'; import * as yaml from 'js-yaml'; +import { cliEntry } from '../../tests/cli-process.ts'; const execFileAsync = promisify(execFile); -// `src/cli.ts` in dev; `CLI_ENTRY=dist/cli.js npm run test:smoke:dist` checks the built output. -const cliEntry = path.resolve(process.env.CLI_ENTRY || 'src/cli.ts'); // Install template variables are upper-case ({{CONTROL_URL}}); Go-template braces such as {{end}} in docker --format strings are not. const unrenderedVariable = /\{\{[A-Z][A-Z0-9_]*\}\}/; diff --git a/src/cli/tui/app.test.ts b/src/cli/tui/app.test.ts index 4bdb3e3..480fd7b 100644 --- a/src/cli/tui/app.test.ts +++ b/src/cli/tui/app.test.ts @@ -18,6 +18,7 @@ test('it refuses to run without a terminal and points at --once', async () => { project: 'site', controlLabel: 'x', cliVersion: '1.2.0', + env: {}, }), /needs a terminal.*--once/, 'a script gets told how to get a summary instead of a broken screen', diff --git a/src/cli/tui/app.ts b/src/cli/tui/app.ts index 2d413d4..1637f20 100644 --- a/src/cli/tui/app.ts +++ b/src/cli/tui/app.ts @@ -1,3 +1,4 @@ +import type { EventEmitter } from 'node:events'; import readline from 'node:readline'; import type { Readable, Writable } from 'node:stream'; import { errMessage } from '../../errors.ts'; @@ -19,7 +20,9 @@ import type { Snapshot, Tone, ViewRef } from './types.ts'; export interface TuiIO { stdin: Readable & CliLiveStdin; stdout: Writable & CliLiveStdout; - stderr?: Writable; + stderr: Writable; + /** Where SIGTERM, SIGHUP and exit are heard, so the terminal is restored when the process ends; without it none are. */ + signals?: EventEmitter; } export interface TuiOptions { api: Api; @@ -33,7 +36,7 @@ export interface TuiOptions { /** Short name of the control plane for the header. */ controlLabel: string; cliVersion: string; - env?: NodeJS.ProcessEnv; + env: NodeJS.ProcessEnv; intervals?: Intervals; /** Opens the push channel from control; the screen works without it, polling faster. */ watch?: (handlers: { @@ -81,7 +84,7 @@ export async function runTui(options: TuiOptions): Promise { ); const snapshot: Snapshot = emptySnapshot(); - const style = createStyle(wantsColor(stdout.isTTY, options.env ?? process.env)); + const style = createStyle(wantsColor(stdout.isTTY, options.env)); let state: UiState = initialState({ columns: stdout.columns || 80, rows: stdout.rows || 24, @@ -307,7 +310,7 @@ export async function runTui(options: TuiOptions): Promise { tty: true, }), options.transport, - { stdin, stdout, stderr: io.stderr }, + { stdin, stdout, stderr: io.stderr, signals: io.signals }, ); if (code !== 0) message = { text: `shell exited with code ${code}`, tone: 'warn' }; } catch (error) { @@ -343,8 +346,8 @@ export async function runTui(options: TuiOptions): Promise { const onSignal = (): void => finished(0); const abort = (): void => finished(0); options.signal?.addEventListener('abort', abort, { once: true }); - process.once('SIGTERM', onSignal); - process.once('SIGHUP', onSignal); + io.signals?.once('SIGTERM', onSignal); + io.signals?.once('SIGHUP', onSignal); const restore = (): void => { try { stdout.write(LEAVE); @@ -352,7 +355,7 @@ export async function runTui(options: TuiOptions): Promise { // The terminal is already gone; nothing to restore. } }; - process.once('exit', restore); + io.signals?.once('exit', restore); try { stdout.write(ENTER); stdin.setRawMode(true); @@ -371,9 +374,9 @@ export async function runTui(options: TuiOptions): Promise { poller.stop(); live?.abort(); options.signal?.removeEventListener('abort', abort); - process.off('SIGTERM', onSignal); - process.off('SIGHUP', onSignal); - process.off('exit', restore); + io.signals?.off('SIGTERM', onSignal); + io.signals?.off('SIGHUP', onSignal); + io.signals?.off('exit', restore); stdout.off('resize', onResize); stdin.off('keypress', onKeypress); restore(); diff --git a/src/cli/usage.ts b/src/cli/usage.ts deleted file mode 100644 index 514e1a8..0000000 --- a/src/cli/usage.ts +++ /dev/null @@ -1,11 +0,0 @@ -let started = false; - -/** A command calls this when it starts real work (a control request, a remote step): an error after that is not a usage mistake. */ -export function markWorkStarted(): void { - started = true; -} - -/** Whether a failure should point at the help: the arguments were wrong, rather than the work failing or being cancelled. */ -export function isUsageError(message: string): boolean { - return !started && !/^cancelled/.test(message); -} diff --git a/src/cli/values.test.ts b/src/cli/values.test.ts index 1583647..e9526d6 100644 --- a/src/cli/values.test.ts +++ b/src/cli/values.test.ts @@ -17,6 +17,7 @@ import { referencedVariables, requiredVariables, } from './values.ts'; +import { testRuntime } from '../../tests/cli-runtime.ts'; async function withDir(run: (dir: string) => Promise): Promise { const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-values-')); @@ -62,13 +63,13 @@ test('findMissingValues counts only what control or --var supplies, never .env o process.env.TUG_TEST_SHELL_VALUE = 'set'; try { assert.deepEqual( - await findMissingValues(file, new Set(['A'])), + await findMissingValues(process.cwd(), file, new Set(['A'])), ['B', 'C', 'D'], 'a name in .env is still missing unless control holds it', ); await fs.writeFile(file, 'x: ${A} ${TUG_TEST_SHELL_VALUE}\n'); assert.deepEqual( - await findMissingValues(file, new Set(['A'])), + await findMissingValues(process.cwd(), file, new Set(['A'])), ['TUG_TEST_SHELL_VALUE'], 'an exported shell variable is still missing unless control holds it', ); @@ -76,7 +77,7 @@ test('findMissingValues counts only what control or --var supplies, never .env o delete process.env.TUG_TEST_SHELL_VALUE; } assert.deepEqual( - await findMissingValues(path.join(dir, 'absent.yml'), new Set()), + await findMissingValues(dir, path.join(dir, 'absent.yml'), new Set()), [], 'an unreadable file is left to the Compose reader to report', ); @@ -87,7 +88,7 @@ test('describeValues says where each name came from, in file order, and shows no await withDir(async (dir) => { const file = path.join(dir, 'compose.yaml'); await fs.writeFile(file, 'x: ${DB_PASSWORD} ${TAG} ${HOST} ${REGION:-eu} ${HOST}\n'); - const values = await describeValues(file, { + const values = await describeValues(process.cwd(), file, { secrets: new Set(['DB_PASSWORD']), vars: new Map([['HOST', { version: 3, value: 'db.internal' }]]), flags: { TAG: 'abc123' }, @@ -110,12 +111,12 @@ test('ignoredSourceNotes names what Tug ignored: .env entries control lacks, and const file = path.join(dir, 'compose.yaml'); await fs.writeFile(file, 'services: {}\n'); assert.deepEqual( - await ignoredSourceNotes(file, new Set(), {}), + await ignoredSourceNotes(dir, file, new Set(), {}), [], 'no .env and no profiles means nothing to say', ); await fs.writeFile(path.join(dir, '.env'), 'DB_PASSWORD=x\nexport MAIL_HOST=y\nKNOWN=z\n'); - const [note] = await ignoredSourceNotes(file, new Set(['KNOWN']), {}); + const [note] = await ignoredSourceNotes(dir, file, new Set(['KNOWN']), {}); assert.match(note, /Ignored \.env/, 'the note says .env was ignored'); assert.match( note, @@ -124,7 +125,7 @@ test('ignoredSourceNotes names what Tug ignored: .env entries control lacks, and ); assert.match(note, /tug secret import \.env/, 'it points at the import command'); assert.ok(!note.includes('=x'), 'a value from .env is never echoed'); - const notes = await ignoredSourceNotes(file, new Set(), { COMPOSE_PROFILES: 'debug' }); + const notes = await ignoredSourceNotes(dir, file, new Set(), { COMPOSE_PROFILES: 'debug' }); assert.match( notes.join('\n'), /COMPOSE_PROFILES=debug.*--profile/, @@ -184,6 +185,7 @@ test('generateSecret is long, URL-safe and unique', () => { test('promptForValues generates by default and accepts an entered secret or variable', async () => { const answers = ['', 'e', 'hunter2', 'v', 'eu-west-1']; const values = await promptForValues( + testRuntime().rt, ['ONE', 'TWO', 'THREE'], async () => answers.shift() as string, ); diff --git a/src/cli/values.ts b/src/cli/values.ts index adf2644..4624dcf 100644 --- a/src/cli/values.ts +++ b/src/cli/values.ts @@ -9,7 +9,8 @@ import * as yaml from 'js-yaml'; import { parseDotenv } from '../compose/load.ts'; import { MAX_VAR_BYTES, RESERVED_VALUE_NAMES, VALUE_NAME, VALUE_NAME_MESSAGE } from '../values.ts'; import type { DeploymentValue } from '../values.ts'; -import { ask } from './prompt.ts'; +import { prompter } from './prompt.ts'; +import type { CliRuntime } from './runtime.ts'; import type { Prompter } from './prompt.ts'; /** `$$` is an escaped dollar; `${NAME}` is required only when it has no `:-`, `-`, `:+`, `+`, `:?` or `?` modifier. */ @@ -61,11 +62,12 @@ export function parseVarFlags(entries: readonly string[]): Record, ): Promise { // An unreadable file is reported by the Compose reader with its own message. - const source = await fs.readFile(file, 'utf8').catch(() => ''); + const source = await fs.readFile(path.resolve(cwd, file), 'utf8').catch(() => ''); return requiredVariables(source).filter((name) => !known.has(name)); } @@ -139,6 +141,7 @@ export function missingValuesMessage( * nothing (the default written in the file). Order follows the file. */ export async function describeValues( + cwd: string, file: string, sources: { secrets: ReadonlySet; @@ -146,7 +149,7 @@ export async function describeValues( flags: Readonly>; }, ): Promise { - const source = await fs.readFile(file, 'utf8').catch(() => ''); + const source = await fs.readFile(path.resolve(cwd, file), 'utf8').catch(() => ''); return referencedVariables(source).map((name): DeploymentValue => { if (name in sources.flags) return { name, source: '--var', value: sources.flags[name] }; if (sources.secrets.has(name)) return { name, source: 'secret' }; @@ -178,12 +181,13 @@ async function dotEnvNames(dir: string): Promise { * file (with the names control does not hold) and `COMPOSE_PROFILES` in the shell. */ export async function ignoredSourceNotes( + cwd: string, file: string, controlNames: ReadonlySet, - env: NodeJS.ProcessEnv = process.env, + env: NodeJS.ProcessEnv, ): Promise { const notes: string[] = []; - const names = await dotEnvNames(path.dirname(path.resolve(file))); + const names = await dotEnvNames(path.dirname(path.resolve(cwd, file))); if (names.length) { const unset = names.filter((name) => !controlNames.has(name)); notes.push( @@ -214,8 +218,9 @@ export interface NewValue { /** Resolve each missing name interactively; returns what to store, and as which kind. */ export async function promptForValues( + rt: CliRuntime, names: readonly string[], - prompt: Prompter = ask, + prompt: Prompter = prompter(rt), ): Promise> { const values: Record = {}; for (const name of names) { diff --git a/src/cli/wait-progress.test.ts b/src/cli/wait-progress.test.ts index 7056c91..ea902a4 100644 --- a/src/cli/wait-progress.test.ts +++ b/src/cli/wait-progress.test.ts @@ -3,14 +3,15 @@ import assert from 'node:assert/strict'; import fs from 'node:fs/promises'; import https from 'node:https'; import os from 'node:os'; -import { Readable } from 'node:stream'; import path from 'node:path'; import type { AddressInfo } from 'node:net'; import { Command } from 'commander'; import { writeStubDocker } from '../../tests/helpers.ts'; import { Pki, identityUri, serverNames } from '../pki.ts'; import { serverTlsOptions } from '../control/tls-server.ts'; -import { resetVersionChecks, setResolvedConfig, waitForCommand } from './commands/context.ts'; +import { waitForCommand } from './commands/context.ts'; +import { testRuntime } from '../../tests/cli-runtime.ts'; +import type { ResolvedCliConfig } from './config.ts'; import { packageVersion } from '../images/image.ts'; import { registerBackup } from './commands/backup.ts'; import { registerRestore } from './commands/restore.ts'; @@ -62,7 +63,7 @@ test('long-wait commands report progress on stderr and retain their results and }); }); await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)); - setResolvedConfig({ + const config = { file: path.join(dir, 'tug.yml'), localFile: path.join(dir, 'tug.local.yml'), fileExists: false, @@ -72,31 +73,37 @@ test('long-wait commands report progress on stderr and retain their results and commandDefaults: {}, nodeDefaults: {}, nodes: {}, - }); + } as unknown as ResolvedCliConfig; + // What a run sees of its process: change these between runs instead of patching this process. + const session = { env: { ...process.env } as NodeJS.ProcessEnv, cwd: process.cwd(), input: '' }; + const newRun = () => { + const made = testRuntime({ env: session.env, cwd: session.cwd, input: session.input }); + made.rt.state.config = config; + return made; + }; + let last = newRun(); const out: string[] = []; const err: string[] = []; - t.mock.method(console, 'log', (line: string) => out.push(line)); - t.mock.method(console, 'error', (line: string) => err.push(line)); - t.mock.method(process.stderr, 'write', (line: string) => { - err.push(line); - return true; - }); const run = async (...args: string[]) => { out.length = 0; err.length = 0; requested.length = 0; urls.length = 0; - // One CLI process is one new module state: forget the remembered version agreement between runs. - resetVersionChecks(); + // One CLI process is one new runtime: it remembers nothing of the previous run. + last = newRun(); const program = new Command(); - registerBackup(program); - registerRestore(program); - registerDeploy(program); - registerControl(program); - registerNode(program); - await program.parseAsync(args, { from: 'user' }); + registerBackup(last.rt, program); + registerRestore(last.rt, program); + registerDeploy(last.rt, program); + registerControl(last.rt, program); + registerNode(last.rt, program); + try { + await program.parseAsync(args, { from: 'user' }); + } finally { + if (last.stdout()) out.push(last.stdout()); + if (last.stderr()) err.push(last.stderr()); + } }; - const originalExitCode = process.exitCode; try { await t.test('target selection validation completes before progress starts', async () => { await assert.rejects( @@ -189,13 +196,12 @@ test('long-wait commands report progress on stderr and retain their results and }); await t.test('backup timeout preserves nonzero exit and running-work explanation', async () => { await run('backup', 'run', '--timeout', '0'); - assert.equal(process.exitCode, 1, 'backup timeouts must exit nonzero'); + assert.equal(last.rt.exitCode, 1, 'backup timeouts must exit nonzero'); assert.match( err.join(''), /keep running on the node/, 'backup timeout must explain that remote work continues', ); - process.exitCode = originalExitCode; }); await t.test( 'restore reports queued and terminal state, and preview does not wait', @@ -259,8 +265,7 @@ test('long-wait commands report progress on stderr and retain their results and /Backups: service:db: running/, 'backup progress must report the observed state of pending targets', ); - assert.equal(process.exitCode, 1, 'failed backups must still exit nonzero'); - process.exitCode = originalExitCode; + assert.equal(last.rt.exitCode, 1, 'failed backups must still exit nonzero'); polls = 0; routes = { 'POST /api/v1/restores': { @@ -296,8 +301,7 @@ test('long-wait commands report progress on stderr and retain their results and /services stay stopped/, 'restore interruptions must retain the recovery instructions', ); - assert.equal(process.exitCode, 1, 'interrupted restores must still exit nonzero'); - process.exitCode = originalExitCode; + assert.equal(last.rt.exitCode, 1, 'interrupted restores must still exit nonzero'); }, ); await t.test('queued command waits report states and preserve failure results', async () => { @@ -305,7 +309,9 @@ test('long-wait commands report progress on stderr and retain their results and routes = { 'GET /api/v1/commands/c1': { state: 'failed', result_json: '{"error":"offline"}' }, }; - const result = await waitForCommand('c1'); + const direct = newRun(); + const result = await waitForCommand(direct.rt, 'c1'); + err.push(direct.stderr()); assert.equal( result.state, 'failed', @@ -318,7 +324,7 @@ test('long-wait commands report progress on stderr and retain their results and ); }); await t.test('node installs report stages and only wait when requested', async () => { - const previousPath = process.env.PATH; + const previousEnv = session.env; const bin = path.join(dir, 'bin'); await fs.mkdir(bin); await writeStubDocker(bin); @@ -329,7 +335,7 @@ test('long-wait commands report progress on stderr and retain their results and '\nif (process.argv.at(-1).includes("agent identity")) process.stdout.write("csr");\n', { mode: 0o755 }, ); - process.env.PATH = bin + path.delimiter + previousPath; + session.env = { ...session.env, PATH: bin + path.delimiter + session.env.PATH }; routes = { 'POST /api/v1/nodes/n1/identity': { node: { id: 'n1', name: 'n1' } }, 'GET /api/v1/nodes': { nodes: [{ name: 'n1', last_seen_at: '2099-01-01T00:00:00.000Z' }] }, @@ -357,8 +363,7 @@ test('long-wait commands report progress on stderr and retain their results and 'node installs must report preparation, identity, installation and reporting stages', ); } finally { - if (previousPath === undefined) delete process.env.PATH; - else process.env.PATH = previousPath; + session.env = previousEnv; } }); await t.test('control backup and restore keep JSON results on stdout', async () => { @@ -447,12 +452,12 @@ test('long-wait commands report progress on stderr and retain their results and [], 'a taken output name is refused before a backup is created on control', ); - const previous = process.cwd(); - process.chdir(dir); + const previousCwd = session.cwd; + session.cwd = dir; try { await run('control', 'backup', '--download'); } finally { - process.chdir(previous); + session.cwd = previousCwd; } assert.ok( await fs.stat(path.join(dir, 'tug-control-backup-cbak_x.tar.gz')), @@ -484,10 +489,14 @@ test('long-wait commands report progress on stderr and retain their results and /--env goes with --from-destination/, 'credential variables only make sense for a destination', ); - process.env.TUG_TEST_KEY = 'AKIA1'; - process.env.TUG_TEST_SECRET = 'secret1'; - process.env.TUG_CONTROL_BACKUP_PASSWORD = - 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'; + const savedEnv = session.env; + session.env = { + ...session.env, + TUG_TEST_KEY: 'AKIA1', + TUG_TEST_SECRET: 'secret1', + TUG_CONTROL_BACKUP_PASSWORD: + 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', + }; try { await run( 'control', @@ -499,9 +508,7 @@ test('long-wait commands report progress on stderr and retain their results and '--confirm', ); } finally { - delete process.env.TUG_TEST_KEY; - delete process.env.TUG_TEST_SECRET; - delete process.env.TUG_CONTROL_BACKUP_PASSWORD; + session.env = savedEnv; } assert.deepEqual( bodies['POST /api/v1/control/restore'], @@ -711,14 +718,11 @@ test('long-wait commands report progress on stderr and retain their results and 'control restore --password-stdin reads only the password from stdin and the credentials from the environment', async () => { routes = { 'POST /api/v1/control/restore': { restartRequired: true } }; - const original = Object.getOwnPropertyDescriptor(process, 'stdin')!; - const feed = (text: string) => - Object.defineProperty(process, 'stdin', { - value: Readable.from([text]), - configurable: true, - }); - process.env.TUG_TEST_KEY = 'AKIA2'; - process.env.TUG_TEST_SECRET = 'secret2'; + const savedEnv = session.env; + const feed = (text: string) => { + session.input = text; + }; + session.env = { ...session.env, TUG_TEST_KEY: 'AKIA2', TUG_TEST_SECRET: 'secret2' }; try { feed('\n' + 'b'.repeat(64) + '\nignored\n'); await run( @@ -744,7 +748,7 @@ test('long-wait commands report progress on stderr and retain their results and }, 'the first non-empty stdin line is the password and the credentials come from the environment', ); - delete process.env.TUG_TEST_SECRET; + delete session.env.TUG_TEST_SECRET; feed('b'.repeat(64) + '\n'); await assert.rejects( run( @@ -779,14 +783,12 @@ test('long-wait commands report progress on stderr and retain their results and 'the flag only means something for a destination', ); } finally { - Object.defineProperty(process, 'stdin', original); - delete process.env.TUG_TEST_KEY; - delete process.env.TUG_TEST_SECRET; + session.env = savedEnv; + session.input = ''; } }, ); } finally { - process.exitCode = originalExitCode; await new Promise((resolve) => server.close(() => resolve())); await fs.rm(dir, { recursive: true, force: true }); } diff --git a/src/cli/watch-client.ts b/src/cli/watch-client.ts index 21f4bdd..715bf17 100644 --- a/src/cli/watch-client.ts +++ b/src/cli/watch-client.ts @@ -12,8 +12,10 @@ export interface WatchClientOptions { onFrame(frame: WatchFrame): void; /** True once control has said `watch.ready`, false when the socket is gone. */ onState(connected: boolean): void; + /** The version declared to control on the upgrade; the CLI passes its runtime's, the default is this package's. */ + clientVersion?: string; /** Substitutes the socket in tests. */ - createSocket?: (url: string, credential: Credential) => WebSocket; + createSocket?: (url: string, credential: Credential, clientVersion: string) => WebSocket; initialBackoffMs?: number; maxBackoffMs?: number; } @@ -103,6 +105,7 @@ export class WatchClient { socket = (this.options.createSocket ?? defaultSocket)( url.toString(), this.options.credential, + this.options.clientVersion ?? packageVersion(), ); } catch { this.retry(); @@ -145,10 +148,10 @@ export class WatchClient { } } -function defaultSocket(url: string, credential: Credential): WebSocket { +function defaultSocket(url: string, credential: Credential, clientVersion: string): WebSocket { return new WebSocket(url, { ...(clientTlsOptions(credential) as object), - headers: { [CLIENT_VERSION_HEADER]: packageVersion() }, + headers: { [CLIENT_VERSION_HEADER]: clientVersion }, followRedirects: false, maxPayload: LIVE_MAX_FRAME_BYTES, handshakeTimeout: LIVE_START_TIMEOUT_MS, diff --git a/src/compose/normalize.ts b/src/compose/normalize.ts index f5a2bb3..c014aaa 100644 --- a/src/compose/normalize.ts +++ b/src/compose/normalize.ts @@ -89,14 +89,14 @@ const PASSTHROUGH = /^(PATH|HOME|USER|USERPROFILE|SYSTEMROOT|TMPDIR|TEMP|TMP|DOC */ async function composeCliEnv( file: string, + hostEnv: NodeJS.ProcessEnv, values: NodeJS.ProcessEnv, profiles: readonly string[], ): Promise<{ env: NodeJS.ProcessEnv; emptyEnvFile: string; cleanup: () => Promise }> { const text = await fs.readFile(file, 'utf8').catch(() => ''); if (/^[^#\n]*\benv_file\s*:/m.test(text)) throw new Error(ENV_FILE_MESSAGE(file)); const env: NodeJS.ProcessEnv = {}; - for (const [key, value] of Object.entries(process.env)) - if (PASSTHROUGH.test(key)) env[key] = value; + for (const [key, value] of Object.entries(hostEnv)) if (PASSTHROUGH.test(key)) env[key] = value; Object.assign(env, values); if (profiles.length) env.COMPOSE_PROFILES = profiles.join(','); const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-compose-env-')); @@ -121,13 +121,16 @@ export async function normalizeCompose( vars?: Readonly>; /** Active profiles, in place of `COMPOSE_PROFILES`. */ profiles?: readonly string[]; + /** The environment of the machine running the CLI, of which only what Docker needs reaches `docker compose`; default `process.env`. */ + hostEnv?: NodeJS.ProcessEnv; } = {}, ): Promise { // Nothing here comes from the deploy machine: not its shell, not `.env`, not `env_file`. The names control holds // are the whole environment, so two machines that run the same deploy read the same values. const env: NodeJS.ProcessEnv = { ...options.vars }; for (const name of secretNames) env[name] = secretSentinel(name); - if (!(options.composeCli ?? process.env.TUG_COMPOSE_CLI === '1')) + const hostEnv = options.hostEnv ?? process.env; + if (!(options.composeCli ?? hostEnv.TUG_COMPOSE_CLI === '1')) return loadCompose(file, { project: options.project, env, @@ -136,7 +139,7 @@ export async function normalizeCompose( }); const runner = options.runner ?? ((cmd, args, opts) => run(cmd, args, opts)); let result: RunResult; - const cliEnv = await composeCliEnv(file, env, options.profiles ?? []); + const cliEnv = await composeCliEnv(file, hostEnv, env, options.profiles ?? []); try { result = await runner('docker', composeConfigArgs(file, options.project, cliEnv.emptyEnvFile), { env: cliEnv.env, diff --git a/src/docs.snippets.test.ts b/src/docs.snippets.test.ts index f0964eb..c6661ab 100644 --- a/src/docs.snippets.test.ts +++ b/src/docs.snippets.test.ts @@ -52,7 +52,7 @@ export async function undeclaredValues(snippet: Snippet): Promise { try { const file = path.join(dir, 'compose.yaml'); fs.writeFileSync(file, snippet.source); - return await findMissingValues(file, new Set(snippet.declared)); + return await findMissingValues(process.cwd(), file, new Set(snippet.declared)); } finally { fs.rmSync(dir, { recursive: true, force: true }); } @@ -197,7 +197,7 @@ test('every example Compose file takes only values its README tells the reader t (match) => match[1] ?? match[2], ), ); - const missing = await findMissingValues(compose, listed); + const missing = await findMissingValues(process.cwd(), compose, listed); if (missing.length) problems.push( `examples/${dir.name} needs ${missing.join(', ')} from control but its README does not list them: use $$ for container-shell variables or add the name to the README`, diff --git a/src/images/artifacts.ts b/src/images/artifacts.ts index 6e1e064..9f46547 100644 --- a/src/images/artifacts.ts +++ b/src/images/artifacts.ts @@ -51,8 +51,13 @@ export async function hashArchive(file: string): Promise<{ sha256: string; sizeB } return { sha256: hash.digest('hex'), sizeBytes }; } -export async function saveImageArchive(imageRef: string, file: string): Promise { - const child = spawn('docker', ['save', imageRef], { stdio: ['ignore', 'pipe', 'pipe'] }); +/** `env` is the environment `docker save` runs in; default this process's. */ +export async function saveImageArchive( + imageRef: string, + file: string, + env?: NodeJS.ProcessEnv, +): Promise { + const child = spawn('docker', ['save', imageRef], { env, stdio: ['ignore', 'pipe', 'pipe'] }); let error = ''; child.stderr.on('data', (chunk) => { error = (error + chunk).slice(-4000); diff --git a/src/images/build.ts b/src/images/build.ts index 00c5276..b48b12d 100644 --- a/src/images/build.ts +++ b/src/images/build.ts @@ -82,6 +82,8 @@ export interface BuildImageOptions { service: string; buildSpec: string | BuildSpec; imageRef: string; + /** The environment `docker build` runs in; default this process's. */ + env?: NodeJS.ProcessEnv; } export async function buildImage({ @@ -89,6 +91,7 @@ export async function buildImage({ service, buildSpec, imageRef, + env, }: BuildImageOptions): Promise { const buildPath = typeof buildSpec === 'string' ? buildSpec : buildSpec?.context || '.'; const dockerfilePath = @@ -106,5 +109,5 @@ export async function buildImage({ throw new Error(`build context escapes uploaded root for ${service}`); if (!(await exists(fullContext))) throw new Error(`build context not found for ${service}: ${buildPath}`); - await run('docker', ['build', ...dockerfile, '-t', imageRef, fullContext]); + await run('docker', ['build', ...dockerfile, '-t', imageRef, fullContext], { env }); } diff --git a/src/images/image.ts b/src/images/image.ts index 9db530c..3e13869 100644 --- a/src/images/image.ts +++ b/src/images/image.ts @@ -16,17 +16,8 @@ const packageJsonPath = path.join( 'package.json', ); -let pinnedVersion: string | undefined; -/** Test seam: pins the version every caller sees, so tests never depend on the package's real version. */ -export function pinPackageVersion(version: string | undefined): void { - pinnedVersion = version; -} - export function packageVersion(): string { - return ( - pinnedVersion ?? - (JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) as { version: string }).version - ); + return (JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) as { version: string }).version; } /** The published image matching this CLI's version, so the CLI and the agents it installs stay in step. */ diff --git a/src/main.test.ts b/src/main.process.test.ts similarity index 92% rename from src/main.test.ts rename to src/main.process.test.ts index 11a7dca..5bfcca1 100644 --- a/src/main.test.ts +++ b/src/main.process.test.ts @@ -9,13 +9,13 @@ import { promisify } from 'node:util'; import { agentIdentityCsr, installIdentity } from './agent/credential.ts'; import { NODE_LIFETIME_MS, Pki, identityUri } from './pki.ts'; import type { IdentityResponse } from './protocol.ts'; +import { mainEntry } from '../tests/cli-process.ts'; const exec = promisify(execFile); -const entry = path.resolve('src/main.ts'); test('--help prints usage for the runtime instead of starting a service', async () => { for (const args of [['control', '--help'], ['agent', '--help'], ['--help']]) { - const { stdout } = await exec(process.execPath, [entry, ...args], { timeout: 60_000 }); + const { stdout } = await exec(process.execPath, [mainEntry, ...args], { timeout: 60_000 }); assert.match(stdout, /Usage: tug-runtime/, `${args.join(' ')} should print usage and exit`); } }); @@ -33,7 +33,7 @@ test('agent identity --current refuses an agent enrolled as another node with a }); const env = { ...process.env, TUG_STATE_DIR: dir }; const run = (...args: string[]) => - exec(process.execPath, [entry, 'agent', 'identity', ...args], { env, timeout: 60_000 }); + exec(process.execPath, [mainEntry, 'agent', 'identity', ...args], { env, timeout: 60_000 }); await assert.rejects( run('--current', 'app9'), (error: { code: number; stderr: string }) => { @@ -68,7 +68,7 @@ test('the control refuses a database from a newer Tug with one plain line and a db.exec('PRAGMA user_version = 99'); db.close(); await assert.rejects( - exec(process.execPath, [entry, 'control'], { + exec(process.execPath, [mainEntry, 'control'], { env: { ...process.env, TUG_DATA_DIR: dir, TUG_CONTROL_URL: 'https://control.test:8443' }, timeout: 60_000, }), diff --git a/src/test-layout.test.ts b/src/test-layout.test.ts new file mode 100644 index 0000000..1895f22 --- /dev/null +++ b/src/test-layout.test.ts @@ -0,0 +1,85 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import test from 'node:test'; +import { fileURLToPath } from 'node:url'; + +// Keeps the fast and process test files honest (docs/testing.md#fast-and-process-test-files). A node process costs about half a second to start, so the +// suite stays fast only while tests that start real tug processes are few, named and easy to find. These checks make +// the cheap way the default: a test that needs the CLI calls execCli, and one that needs a real process says so in +// its file name. + +const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); +const SELF = 'src/test-layout.test.ts'; +const kindOf = (file: string) => (/\.process\.test\.[mc]?[jt]s$/.test(file) ? 'process' : 'fast'); + +function walk(dir: string): string[] { + return fs.readdirSync(path.join(root, dir), { withFileTypes: true }).flatMap((entry) => { + const rel = `${dir}/${entry.name}`; + if (entry.isDirectory()) return walk(rel); + return /\.test\.[mc]?[jt]s$/.test(entry.name) ? [rel] : []; + }); +} +const files = [...walk('src'), ...walk('tools/scripts')].sort(); +const read = (file: string) => fs.readFileSync(path.join(root, file), 'utf8'); +const startsRealProcess = (text: string) => + /tests\/cli-process\.ts|process\.execPath|\bspawn\(|\bexecFile\(/.test(text); + +test('only *.process.test.* files import the real-process entry points', () => { + const offenders = files.filter( + (file) => file !== SELF && kindOf(file) === 'fast' && /tests\/cli-process\.ts/.test(read(file)), + ); + assert.deepEqual( + offenders, + [], + 'these fast files import tests/cli-process.ts: use execCli (tests/cli-inprocess.ts), or rename the file to *.process.test.ts if it needs a terminal, piped stdin, signals or the built entry', + ); +}); + +test('no test hard-codes the path of the CLI or runtime entry, so the process files stays findable', () => { + const offenders = files.filter( + (file) => + file !== SELF && + /['"`][^'"`\n]*(?:src\/(?:cli|main)\.ts|dist\/(?:cli|main)\.js)['"`]/.test(read(file)), + ); + assert.deepEqual( + offenders, + [], + 'import cliEntry or mainEntry from tests/cli-process.ts (in a *.process.test.ts file) instead of naming the entry file', + ); +}); + +test('a fast test file that starts processes does not name the CLI or runtime entry in any spelling', () => { + const offenders = files.filter((file) => { + if (file === SELF || kindOf(file) !== 'fast') return false; + const text = read(file); + return ( + /process\.execPath|\bspawn\(|\bexecFile\(|execFileSync|spawnSync/.test(text) && + /\b(?:cli|main)\.(?:ts|js)\b|CLI_ENTRY/.test(text) + ); + }); + assert.deepEqual( + offenders, + [], + 'a fast file that spawns a process and names cli.ts, main.ts or dist/*.js is starting the real CLI: use execCli, or move those tests to a *.process.test.ts file', + ); +}); + +test('a *.process.test.* file really starts processes, so the process files holds only slow tests', () => { + const idle = files.filter((file) => kindOf(file) === 'process' && !startsRealProcess(read(file))); + assert.deepEqual( + idle, + [], + 'these files are in the process files but start no process: rename them to *.test.ts so they run in the fast files', + ); +}); + +test('test files use only the documented suffixes', () => { + const odd = files.filter((file) => !/\.(?:process\.)?test\.[mc]?[jt]s$/.test(file)); + assert.deepEqual(odd, [], 'the kinds come from *.test.ts and *.process.test.ts, nothing else'); + assert.ok( + files.some((file) => kindOf(file) === 'process'), + 'the process files should not be empty', + ); + assert.ok(files.length > 100, `the walk should find the whole suite (found ${files.length})`); +}); diff --git a/src/transport.ts b/src/transport.ts index e82bcdf..e71b0ee 100644 --- a/src/transport.ts +++ b/src/transport.ts @@ -10,7 +10,12 @@ type HttpClient = (url: string, init?: RequestInit) => Promise; * A client pinned to the credential's CA that presents its certificate. `connectUrl` only changes where the TCP * connection goes; the server name is still verified against the credential's public host. Redirects are refused. */ -export function createTransport(credential: Credential, connectUrl?: string) { +/** `clientVersion` is what every request declares to the control; the CLI passes its runtime's, the default is this package's. */ +export function createTransport( + credential: Credential, + connectUrl?: string, + clientVersion: string = packageVersion(), +) { const dispatcher = new Agent({ connect: clientTlsOptions(credential) as never }); const base = new URL(connectUrl ?? credential.url).origin; const http: HttpClient = (url, init) => { @@ -20,7 +25,7 @@ export function createTransport(credential: Credential, connectUrl?: string) { // must not learn the Tug version. const headers = new Headers(init?.headers); if (!headers.has(CLIENT_VERSION_HEADER) && new URL(url).origin === base) - headers.set(CLIENT_VERSION_HEADER, packageVersion()); + headers.set(CLIENT_VERSION_HEADER, clientVersion); let request = { ...init, headers } as RequestInit; // The runtime's FormData is not the undici package's FormData, which would stringify it. Serialize it with the // runtime's own Response and stream the result. diff --git a/tests/cli-inprocess.ts b/tests/cli-inprocess.ts new file mode 100644 index 0000000..c1d23a4 --- /dev/null +++ b/tests/cli-inprocess.ts @@ -0,0 +1,69 @@ +import { runCli } from '../src/cli/program.ts'; +import { testRuntime } from './cli-runtime.ts'; +import type { TestRuntimeOptions } from './cli-runtime.ts'; + +/** What `promisify(execFile)` resolves with, so tests written against a child process keep their assertions. */ +export interface CliResult { + stdout: string; + stderr: string; +} +export interface CliFailure extends Error, CliResult { + code: number; +} +export interface CliOptions extends TestRuntimeOptions { + /** Milliseconds before the call is abandoned as hung; a leaked handle or a command waiting for input fails here. */ + timeout?: number; +} + +/** Rejects with `Error(message)` when `work` has not settled within `ms`. */ +export async function withDeadline(work: Promise, ms: number, message: string): Promise { + let timer: ReturnType | undefined; + const hung = new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error(message)), ms); + }); + try { + return await Promise.race([work, hung]); + } finally { + clearTimeout(timer); + } +} + +/** + * Runs `tug ` inside this test process instead of starting node for it, which costs about half a second per + * call. The command gets a runtime of its own (tests/cli-runtime.ts): its environment, working directory, streams and + * signals are plain objects, so nothing global is touched and calls may overlap. Resolves like a promisified + * `execFile` and rejects with `code`, `stdout` and `stderr` on a non-zero exit. Use a real child process (see + * tests/cli-process.ts) only for what in-process cannot show: signals, a terminal, a command that must exit while its + * stdin stays open, and the built `dist` entry. + */ +export async function execCli( + args: readonly string[], + options: CliOptions = {}, +): Promise { + const { rt, stdout, stderr } = testRuntime(options); + const limit = options.timeout ?? 60_000; + const code = await withDeadline( + runCli(args, rt), + limit, + `tug ${args.join(' ')} did not finish within ${limit / 1000} s`, + ); + const result = { stdout: stdout(), stderr: stderr() }; + if (code === 0) return result; + throw Object.assign(new Error(`tug ${args.join(' ')} exited ${code}\n${result.stderr}`), result, { + code, + }); +} + +/** The exit code and both streams of a command, whether or not it succeeded, for tests of failing invocations. */ +export async function cliOutcome( + args: readonly string[], + options: CliOptions = {}, +): Promise { + try { + return { ...(await execCli(args, options)), code: 0 }; + } catch (e) { + const failure = e as CliFailure; + if (typeof failure.code !== 'number') throw e; + return { stdout: failure.stdout, stderr: failure.stderr, code: failure.code }; + } +} diff --git a/tests/cli-process.ts b/tests/cli-process.ts new file mode 100644 index 0000000..81c83bf --- /dev/null +++ b/tests/cli-process.ts @@ -0,0 +1,13 @@ +import path from 'node:path'; + +// Entry points for the tests that must start a real tug process: a terminal, piped stdin, signals, a command that +// has to exit while its input stays open, the built `dist` output. Everything else runs the CLI in-process with +// `execCli` (tests/cli-inprocess.ts), which costs milliseconds instead of the half second a node start takes. +// +// Only files named `*.process.test.ts` may import this module (src/test-layout.test.ts enforces it), so the process +// files stay a list of files, not a habit that spreads by copying the neighbouring test. + +/** The operator CLI: `src/cli.ts`, or the built output with `CLI_ENTRY=dist/cli.js` (npm run test:smoke:dist). */ +export const cliEntry = path.resolve(process.env.CLI_ENTRY || 'src/cli.ts'); +/** The runtime (control and agent) entry. */ +export const mainEntry = path.resolve('src/main.ts'); diff --git a/tests/cli-runtime.ts b/tests/cli-runtime.ts new file mode 100644 index 0000000..f01a7b6 --- /dev/null +++ b/tests/cli-runtime.ts @@ -0,0 +1,59 @@ +import { EventEmitter } from 'node:events'; +import { Readable, Writable } from 'node:stream'; +import { packageVersion } from '../src/images/image.ts'; +import { freshState } from '../src/cli/runtime.ts'; +import type { CliInput, CliOutput, CliRuntime } from '../src/cli/runtime.ts'; + +export interface TestRuntimeOptions { + /** The whole environment of the run; defaults to a copy of this process's. */ + env?: NodeJS.ProcessEnv; + /** The working directory relative paths resolve against; defaults to this process's. */ + cwd?: string; + /** Piped to stdin; without it stdin is empty, as with `< /dev/null`. */ + input?: string; + /** The version the CLI reports; defaults to this package's. */ + version?: string; + /** Present stdin and stdout as terminals. */ + tty?: boolean; + columns?: number; +} + +const sink = (chunks: string[], tty: boolean, columns: number): CliOutput => { + const stream = new Writable({ + write(chunk, _encoding, callback) { + chunks.push(String(chunk)); + callback(); + }, + }) as CliOutput; + if (tty) { + stream.isTTY = true; + stream.columns = columns; + } + return stream; +}; + +/** + * A runtime made of plain objects, so a command runs in-process with its own environment, streams and signals and + * nothing global is touched. Read what it wrote with `stdout()` and `stderr()`, and the exit code it asked for from + * `rt.exitCode`. + */ +export function testRuntime(options: TestRuntimeOptions = {}) { + const out: string[] = []; + const err: string[] = []; + const env = options.env ?? { ...process.env }; + const stdin = Readable.from(options.input === undefined ? [] : [options.input]) as CliInput; + if (options.tty) stdin.isTTY = true; + const rt: CliRuntime = { + env, + cwd: options.cwd ?? process.cwd(), + stdin, + stdout: sink(out, Boolean(options.tty), options.columns ?? 100), + stderr: sink(err, false, 100), + inheritStdio: false, + version: options.version ?? packageVersion(), + signals: new EventEmitter(), + raise: () => {}, + state: freshState(env), + }; + return { rt, stdout: () => out.join(''), stderr: () => err.join('') }; +} diff --git a/tests/helpers.ts b/tests/helpers.ts index f0ed4c0..1745d30 100644 --- a/tests/helpers.ts +++ b/tests/helpers.ts @@ -150,17 +150,28 @@ export async function startMtlsControl( dir: string, options: { eventPruneIntervalMs?: number } = {}, ) { - process.env.TUG_DATA_DIR = dir; const { createApp, listen } = await import('../src/control/control.ts'); const { issueHostCredential } = await import('../src/control/credential-issue.ts'); const { createTransport } = await import('../src/transport.ts'); const controlUrl = 'https://localhost:8443'; - const app = await createApp({ images: { resolve: testImageResolver }, controlUrl, ...options }); - const server = await listen(app, 0); + // Control reads its data directory from the environment while it starts and while the root credential is issued; + // set it for exactly that, so no test leaves it behind for the next one. + const previousDataDir = process.env.TUG_DATA_DIR; + process.env.TUG_DATA_DIR = dir; + let app: Awaited>; + let server: Awaited>; + let root: ReturnType; + try { + app = await createApp({ images: { resolve: testImageResolver }, controlUrl, ...options }); + server = await listen(app, 0); + root = decodeCredential( + await issueHostCredential({ name: 'root', role: 'admin', replace: false, controlUrl }), + ); + } finally { + if (previousDataDir === undefined) delete process.env.TUG_DATA_DIR; + else process.env.TUG_DATA_DIR = previousDataDir; + } const url = `https://127.0.0.1:${(server.address() as { port: number }).port}`; - const root = decodeCredential( - await issueHostCredential({ name: 'root', role: 'admin', replace: false, controlUrl }), - ); const credentialFile = path.join(dir, 'root.credential.json'); await fs.writeFile(credentialFile, JSON.stringify(root), { mode: 0o600 }); /** Registers a node the way `tug node add` does and returns its credential. */ diff --git a/tests/tui-harness.ts b/tests/tui-harness.ts index daf30ac..280437d 100644 --- a/tests/tui-harness.ts +++ b/tests/tui-harness.ts @@ -26,7 +26,8 @@ export function fakeTerminal(columns = 100, rows = 30) { stdout.rows = rows; let output = ''; stdout.on('data', (chunk: Buffer) => (output += chunk.toString())); - return { stdin, stdout, rawModes, output: () => output }; + const stderr = new PassThrough(); + return { stdin, stdout, stderr, rawModes, output: () => output }; } export { until } from './wait.ts';