unitbob 0.5.0 → 0.6.0

package/dist/runner/bdd.js

@@ -1,12 +1,23 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { executable, runProcess } from "../proc.js";
-import { readReport } from "./types.js";
+import { executable } from "../proc.js";
+import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
+import { commandFileOnHost } from "./toolchain.js";
+import { clearReport, readFreshReport } from "./types.js";
 import { PYTEST_BDD_PLUGIN } from "./pytestBddPlugin.js";
 export const BDD_TIMEOUT_MS = 10 * 60 * 1000;
 // The behavioral suite lives under one root; the report is written inside it so
 // the app under test cannot pollute it and it travels with the suite.
+//
+// Spelled here rather than imported from `files/behavioral.ts`, which spells it
+// too: that module imports this one, and an import back would be a cycle whose
+// only symptom is a use-before-initialization at load time.
 const BEHAVIORAL_ROOT = '.unitbob/behavioral';
+// The sidecar Gemfile bundler is pointed at, in one place — the world probe
+// needs the same value and used to carry its own copy. A plain string rather
+// than `join`: this path is read where the run happens, whose separator is not
+// necessarily this machine's.
+export const BEHAVIORAL_GEMFILE = `${BEHAVIORAL_ROOT}/Gemfile`;
 const CUCUMBER_REPORT_NAME = 'cucumber_messages.ndjson';
 const PYTEST_BDD_REPORT_NAME = 'pytest_bdd_report.json';
 const PYTEST_BDD_PLUGIN_NAME = 'unitbob_pytest_bdd_plugin.py';
@@ -22,51 +33,112 @@ export const BDD_RUN_ARTIFACTS = [
     PYTEST_BDD_PLUGIN_NAME,
     PYTEST_INI_NAME,
 ];
+// One name for the directory every strategy points its loader at, so the
+// descriptors below and the commands below them cannot come to mean different
+// directories.
+const STEP_DEFINITIONS = 'step_definitions';
 const CUCUMBER_REPORT = join(BEHAVIORAL_ROOT, CUCUMBER_REPORT_NAME);
 const PYTEST_BDD_REPORT = join(BEHAVIORAL_ROOT, PYTEST_BDD_REPORT_NAME);
 const PYTEST_BDD_PLUGIN_FILE = join(BEHAVIORAL_ROOT, PYTEST_BDD_PLUGIN_NAME);
 const PYTEST_INI_FILE = join(BEHAVIORAL_ROOT, PYTEST_INI_NAME);
 const PYTEST_INI = '[pytest]\naddopts =\n';
+// Load order is a fact about both Cucumbers and about neither pytest — pytest
+// picks `conftest.py` up itself, so there is no trap to work around there.
+const CUCUMBER_LOAD_ORDER = 'Files load in filename order, and the shared file is not special to the runner — `account_access` ' +
+    'loads before `shared`. Open each capability file with an explicit require of the shared one rather ' +
+    'than trusting the alphabet.';
 // The connector-owned BDD strategy table (spec 32): the `runner` enum names one
 // of these; the connector never executes a host-provided command string. Each
 // strategy runs the whole behavioral bundle and returns the raw machine-readable
 // report verbatim — the connector does no marker join and no aggregation.
+//
+// A strategy is its command *and* its loading rule. They are one entry so that a
+// fourth runner cannot be added with only half of itself stated.
+const BDD_STRATEGIES = {
+    cucumber: {
+        run: (projectRoot) => runCucumberRuby(projectRoot),
+        loading: {
+            step_files: '*.rb',
+            requirements: [
+                'The connector points `--require` at `step_definitions/`, so every `.rb` file there is loaded. ' +
+                    'That explicit `--require` also switches off Cucumber\'s automatic loading of `features/support/`: ' +
+                    'a World or helper parked there is never evaluated, and every step then fails on a bare object.',
+                CUCUMBER_LOAD_ORDER,
+            ],
+        },
+    },
+    'cucumber-js': {
+        run: (projectRoot) => runCucumberJs(projectRoot),
+        loading: {
+            step_files: '*.js',
+            requirements: [
+                'Keep `step_definitions/` to CommonJS JavaScript and nothing else. The connector passes the whole ' +
+                    'directory to `--require`, and cucumber-js `require()`s every file it matches whatever the ' +
+                    'extension — a stray `.ts`, `.json` or `.md` left there is executed as JavaScript and aborts the ' +
+                    'entire run with a parse error, before a single scenario.',
+                'The connector registers no TypeScript loader, so a `.ts` file cannot compile itself. If you want ' +
+                    'one, register the compiler from the file that sorts first — and remember the file registering it ' +
+                    'is itself loaded as plain JavaScript.',
+                CUCUMBER_LOAD_ORDER,
+            ],
+        },
+    },
+    'pytest-bdd': {
+        run: (projectRoot, mainPath) => runPytestBdd(projectRoot, mainPath),
+        loading: {
+            step_files: 'test_*.py',
+            requirements: [
+                'pytest collects `step_definitions/` under its own default, which is `test_*.py` and `*_test.py`. ' +
+                    'The connector writes no `python_files` setting and will not: a file named outside those two — ' +
+                    '`<capability>_steps.py`, say — is simply not collected. No error, no scenarios, a green run ' +
+                    'over nothing.',
+                '`conftest.py` is picked up by pytest itself whatever else sits beside it, so shared fixtures ' +
+                    'belong there and there is no load-order trap to work around.',
+            ],
+        },
+    },
+};
 export function runBddSuite(projectRoot, runner, mainPath) {
-    switch (runner) {
-        case 'cucumber':
-            return runCucumberRuby(projectRoot);
-        case 'cucumber-js':
-            return runCucumberJs(projectRoot);
-        case 'pytest-bdd':
-            return runPytestBdd(projectRoot, mainPath);
-        default:
-            return Promise.reject(new Error(`Unsupported BDD runner "${runner}" — rebuild the behavioral suite.`));
+    const strategy = strategyFor(runner);
+    if (!strategy) {
+        return Promise.reject(new Error(`Unsupported BDD runner "${runner}" — rebuild the behavioral suite.`));
     }
+    return strategy.run(projectRoot, mainPath);
+}
+// How this runner loads step files, for whoever has to write one. Null for a
+// runner this connector does not run, which is the same answer `runBddSuite`
+// gives it.
+export function bddStepLoading(runner) {
+    return strategyFor(runner)?.loading ?? null;
+}
+// `Object.hasOwn` rather than a bare index: the runner name arrives over the
+// wire, and `constructor` would otherwise come back as a truthy strategy with no
+// `run` on it.
+function strategyFor(runner) {
+    return Object.hasOwn(BDD_STRATEGIES, runner) ? BDD_STRATEGIES[runner] : null;
 }
 // Ruby: `cucumber` with the built-in message formatter. The features and step
 // definitions both live under the behavioral root; --require points at the step
 // definitions so only the Unitbob bundle loads.
 async function runCucumberRuby(projectRoot) {
     const features = join(BEHAVIORAL_ROOT, 'features');
-    const steps = join(BEHAVIORAL_ROOT, 'step_definitions');
-    const sidecarGemfile = join(projectRoot, BEHAVIORAL_ROOT, 'Gemfile');
+    const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS);
+    const sidecarGemfile = join(projectRoot, BEHAVIORAL_GEMFILE);
     if (!existsSync(sidecarGemfile)) {
         throw missingRunner('Cucumber');
     }
     const command = 'bundle';
     const args = ['exec', 'cucumber', features, '--require', steps, '--format', 'message', '--out', CUCUMBER_REPORT];
-    const env = {
-        ...process.env,
-        RAILS_ENV: 'test',
-        UNITBOB_REPO_ROOT: projectRoot,
-    };
-    env.BUNDLE_GEMFILE = join(BEHAVIORAL_ROOT, 'Gemfile');
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+    const survivor = clearReport(join(projectRoot, CUCUMBER_REPORT));
+    const run = await runInProject(projectRoot, command, args, {
         timeoutMs: BDD_TIMEOUT_MS,
-        env,
+        env: {
+            RAILS_ENV: 'test',
+            UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+            BUNDLE_GEMFILE: BEHAVIORAL_GEMFILE,
+        },
     });
-    return finalize(result, command, args, projectRoot, CUCUMBER_REPORT);
+    return finalize(run, projectRoot, CUCUMBER_REPORT, survivor);
 }
 function missingRunner(name) {
     return new Error(`Behavioral runner missing (${name}). Run suite-prepare to provision it under ${BEHAVIORAL_ROOT}/, then run the checks again.`);
@@ -75,12 +147,11 @@ function missingRunner(name) {
 // to a file.
 async function runCucumberJs(projectRoot) {
     const features = join(BEHAVIORAL_ROOT, 'features');
-    const steps = join(BEHAVIORAL_ROOT, 'step_definitions', '**', '*');
-    const sidecarBin = join(projectRoot, BEHAVIORAL_ROOT, 'node_modules', '.bin', 'cucumber-js');
-    if (!executable(sidecarBin)) {
+    const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS, '**', '*');
+    const command = `${BEHAVIORAL_ROOT}/node_modules/.bin/cucumber-js`;
+    if (!executable(commandFileOnHost(projectRoot, command))) {
         throw missingRunner('Cucumber JS');
     }
-    const command = sidecarBin;
     const args = [
         features,
         '--require',
@@ -88,12 +159,12 @@ async function runCucumberJs(projectRoot) {
         '--format',
         `message:${CUCUMBER_REPORT}`,
     ];
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+    const survivor = clearReport(join(projectRoot, CUCUMBER_REPORT));
+    const run = await runInProject(projectRoot, command, args, {
         timeoutMs: BDD_TIMEOUT_MS,
-        env: { ...process.env, NODE_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: { NODE_ENV: 'test', UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot) },
     });
-    return finalize(result, command, args, projectRoot, CUCUMBER_REPORT);
+    return finalize(run, projectRoot, CUCUMBER_REPORT, survivor);
 }
 // Python: pytest driving pytest-bdd, with the connector's reporter plugin. The
 // plugin writes the JSON report; `-c` isolates the run from the project's own
@@ -103,40 +174,47 @@ async function runPytestBdd(projectRoot, mainPath) {
     writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
     writeFileSync(join(projectRoot, PYTEST_BDD_PLUGIN_FILE), PYTEST_BDD_PLUGIN);
     const command = await pickPython(projectRoot);
-    const stepsDir = join(BEHAVIORAL_ROOT, 'step_definitions');
+    const stepsDir = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS);
     const isVenvPytest = command.endsWith('/pytest');
+    // `--rootdir .`, not the absolute root: the working directory is the project
+    // root in every place, and an absolute host path would name a directory that
+    // does not exist wherever the run actually happens.
     const args = isVenvPytest
-        ? ['-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', projectRoot]
-        : ['-m', 'pytest', '-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', projectRoot];
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+        ? ['-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', '.']
+        : ['-m', 'pytest', '-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', '.'];
+    const survivor = clearReport(join(projectRoot, PYTEST_BDD_REPORT));
+    const run = await runInProject(projectRoot, command, args, {
         timeoutMs: BDD_TIMEOUT_MS,
         env: {
-            ...process.env,
-            UNITBOB_REPO_ROOT: projectRoot,
-            UNITBOB_PYTEST_BDD_REPORT: join(projectRoot, PYTEST_BDD_REPORT),
-            PYTHONPATH: [join(projectRoot, BEHAVIORAL_ROOT), process.env.PYTHONPATH ?? ''].filter(Boolean).join(':'),
+            UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+            // Relative, and the plugin makes it absolute the moment it is imported —
+            // before any fixture has had a chance to change directory. Sent as a host
+            // path it would name a directory the run cannot see.
+            UNITBOB_PYTEST_BDD_REPORT: PYTEST_BDD_REPORT,
+            // The connector's own plugin directory, and only it. The host's own
+            // PYTHONPATH used to be appended here; it names host directories, which
+            // mean nothing where the run happens, and passing on the connector's
+            // environment is exactly what a place must not do.
+            PYTHONPATH: BEHAVIORAL_ROOT,
         },
     });
-    return finalize(result, command, args, projectRoot, PYTEST_BDD_REPORT);
+    return finalize(run, projectRoot, PYTEST_BDD_REPORT, survivor);
     // mainPath is accepted for symmetry with the structural runners; pytest-bdd
     // discovers scenarios from the step-definition modules, not the .feature path.
 }
 function pluginModule() {
     return 'unitbob_pytest_bdd_plugin';
 }
-function finalize(result, command, args, projectRoot, reportRel) {
+function finalize(run, projectRoot, reportRel, survivor) {
     return {
-        ...result,
-        command,
-        args,
+        ...run,
         resultPath: reportRel,
-        report: readReport(join(projectRoot, reportRel)),
+        report: readFreshReport(join(projectRoot, reportRel), survivor),
     };
 }
 async function pickPython(projectRoot) {
-    const sidecarVenvPytest = join(projectRoot, BEHAVIORAL_ROOT, '.venv', 'bin', 'pytest');
-    if (executable(sidecarVenvPytest)) {
+    const sidecarVenvPytest = `${BEHAVIORAL_ROOT}/.venv/bin/pytest`;
+    if (executable(commandFileOnHost(projectRoot, sidecarVenvPytest))) {
         return sidecarVenvPytest;
     }
     throw missingRunner('pytest-bdd');

package/dist/runner/bootcheck.js

@@ -1,16 +1,13 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { executable, runProcess } from "../proc.js";
-import { locateRunner } from "./toolchain.js";
+import { executable } from "../proc.js";
+import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
+import { commandFileOnHost, locateRunner } from "./toolchain.js";
 import { GUARDRAILS_DIR, HELPER_FILE } from "../files/guardrails.js";
 import { PYTEST_INI, PYTEST_INI_FILE } from "./pytest.js";
 import { PROVISION_TIMEOUT_MS } from "./provision.js";
 const defaultDeps = {
-    runCmd: (command, args, options) => runProcess(command, args, {
-        cwd: options.cwd,
-        timeoutMs: PROVISION_TIMEOUT_MS,
-        env: { ...process.env, ...options.env },
-    }),
+    runCmd: (command, args, options) => runInProject(options.cwd, command, args, { timeoutMs: PROVISION_TIMEOUT_MS, env: options.env }),
 };
 // How much of a runner's output rides along in `detail`. Enough to see the
 // stack that mattered, short enough that a stop message stays readable.
@@ -49,8 +46,8 @@ export async function bootCheck(projectRoot, runner, deps = defaultDeps) {
 // `spec/support` and the project's own configuration all come along for free,
 // without this module knowing anything about them.
 async function rubyBootCheck(projectRoot, deps) {
-    const helper = join(projectRoot, GUARDRAILS_DIR, HELPER_FILE);
-    if (!existsSync(helper))
+    const helper = `${GUARDRAILS_DIR}/${HELPER_FILE}`;
+    if (!existsSync(join(projectRoot, helper)))
         return { status: 'not_checked', reason: 'nothing_to_load' };
     const first = await loadRubyHelper(projectRoot, helper, deps);
     if (first.status !== 'broken')
@@ -85,16 +82,25 @@ async function loadRubyHelper(projectRoot, helper, deps) {
     // someone whose bundler is installed and working. That is the mistake
     // `runner_too_old` and `runner_could_not_answer` were added to stop making,
     // and the global `bundle` was standing right there the whole time.
-    const localBundle = join(projectRoot, 'bin', 'bundle');
-    const command = executable(localBundle) ? localBundle : 'bundle';
+    const command = executable(join(projectRoot, 'bin', 'bundle')) ? 'bin/bundle' : 'bundle';
     // When Unitbob installed rspec-rails for itself, the gems this helper needs
     // are resolved by the sidecar Gemfile, not the project's. Asking bundler
     // without that variable would load a different set of gems than the run does,
     // which is exactly the way a check ends up predicting the wrong thing.
     const located = locateRunner(projectRoot, 'rspec');
-    return classify(projectRoot, 'rspec', await attempt(deps, command, ['exec', 'ruby', '-e', `require ${JSON.stringify(helper)}`], {
+    // `require "./…"`, and the leading dot is not cosmetic: Ruby resolves a
+    // relative require against `$LOAD_PATH`, which does not hold the working
+    // directory, and only a path beginning with `.` is resolved against the
+    // working directory instead. The helper finds its own neighbours through
+    // `__dir__`, which is absolute however the file was reached, so nothing else
+    // about it changes.
+    return classify(projectRoot, 'rspec', await attempt(deps, command, ['exec', 'ruby', '-e', `require ${JSON.stringify(`./${helper}`)}`], {
         cwd: projectRoot,
-        env: { ...located?.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: {
+            ...located?.env,
+            RAILS_ENV: 'test',
+            UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+        },
     }), 
     // A clean load says nothing on stdout and exits 0. Anything else is the
     // suite failing to start.
@@ -171,8 +177,7 @@ function pytestVerdict(code) {
 async function vitestBootCheck(projectRoot, deps) {
     // A sidecar vitest counts as installed: it is ours, it is on disk, and it is
     // the one the run will spawn. What stays out is `npx`, for the reason below.
-    const local = locateRunner(projectRoot, 'vitest')?.command
-        ?? join(projectRoot, 'node_modules', '.bin', 'vitest');
+    const local = locateRunner(projectRoot, 'vitest')?.command ?? 'node_modules/.bin/vitest';
     // Only a vitest already installed in the project is used. Reaching for `npx`
     // would install a package to answer a question, and installing into the
     // user's project is not this check's business.
@@ -182,7 +187,7 @@ async function vitestBootCheck(projectRoot, deps) {
     // "cannot be asked", and the answer came back `runner_too_old` — a positive
     // falsehood about a version nobody looked at. `no_runner` is the honest one
     // here: there is no vitest this check can invoke.
-    if (!executable(local))
+    if (!executable(commandFileOnHost(projectRoot, local)))
         return { status: 'not_checked', reason: 'no_runner' };
     // `list` is a subcommand only from Vitest 2.1. Older versions read it as a
     // *filename filter* and go on to run whatever it matches, which was measured
@@ -243,6 +248,14 @@ function classify(projectRoot, runner, result, verdict) {
     // nothing about the code, so it must not read as a defect.
     if (result.code === null)
         return { status: 'not_checked', reason: 'timed_out' };
+    // Before the exit code is read at all, and that order is the whole point. The
+    // codes docker returns for its own failures overlap with real runners' codes,
+    // and one step further down `causeOf` picks a cause by matching the output
+    // against a path pattern — so a container that stopped mid-run could come back
+    // as "found a defect that stops your test suite from starting". An accusation
+    // about somebody's code, for a failure of the daemon.
+    if (result.placeFailure)
+        return { status: 'not_checked', reason: 'place_failed', detail: result.placeFailure };
     const outcome = verdict(result);
     if (outcome === 'ok')
         return { status: 'ok' };
@@ -374,13 +387,12 @@ export function firstErrorLine(output) {
 async function prepareTestDatabase(projectRoot, deps) {
     if (!testDatabaseIsSeparate(projectRoot))
         return false;
-    const rails = join(projectRoot, 'bin', 'rails');
-    const useBinstub = executable(rails);
-    const command = useBinstub ? rails : 'bundle';
+    const useBinstub = executable(join(projectRoot, 'bin', 'rails'));
+    const command = useBinstub ? 'bin/rails' : 'bundle';
     const args = useBinstub ? ['db:test:prepare'] : ['exec', 'rails', 'db:test:prepare'];
     const result = await attempt(deps, command, args, {
         cwd: projectRoot,
-        env: { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot) },
     });
     return result !== null && result.code === 0;
 }

package/dist/runner/docker.js

@@ -0,0 +1,139 @@
+// Everything this connector knows about Docker, in one file (spec 36).
+//
+// It is deliberately not "a command prefix the user configures". A prefix would
+// be three lines and would make every message below impossible: with only a
+// string to run, nothing can say "that container is not running", "the project
+// is not mounted into it", or "here is the container that already has your
+// project". Those sentences are the point of the spec, so the connector knows
+// what a container is.
+import { spawnSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { posix, relative, sep } from 'node:path';
+const inspected = new Map();
+// Where this container sees the project root, or why it cannot.
+//
+// The path inside is never configured. It is derived from the container's own
+// mounts: the deepest mount whose source is the start of the path to the project
+// root, with the remainder appended to its destination. Exact equality (`.:/app`)
+// is the common case but not the only one — a monorepo mounts the parent
+// (`..:/workspace`) and the project sits inside it, and demanding equality would
+// report "your code is copied into the image" about a project that is plainly
+// mounted.
+//
+// This doubles as the bind-mount check the whole invariant rests on: no mount
+// covering the root means the code was copied into the image, which means files
+// written here are invisible there and reports written there are invisible here.
+export function containerProjectRoot(container, projectRoot) {
+    const found = inspected.get(container) ?? inspect(container);
+    inspected.set(container, found);
+    if ('failure' in found)
+        return found.failure;
+    if (found.container.State?.Running === false)
+        return { status: 'not_running' };
+    const mounted = mountedRoot(found.container.Mounts ?? [], projectRoot);
+    return mounted === null ? { status: 'not_mounted' } : { status: 'ok', projectRoot: mounted };
+}
+function inspect(container) {
+    const result = spawnSync('docker', ['container', 'inspect', container, '--format', '{{json .}}'], {
+        timeout: 30_000,
+        encoding: 'utf8',
+    });
+    // `docker` is not on this machine at all — a different sentence from any
+    // answer about the container, and the only one whose fix is "install Docker".
+    if (result.error && result.error.code === 'ENOENT')
+        return { failure: { status: 'no_docker' } };
+    if (result.error)
+        return { failure: { status: 'unreadable', detail: result.error.message } };
+    const stderr = (result.stderr ?? '').trim();
+    if (result.status !== 0) {
+        if (/no such (container|object)/i.test(stderr))
+            return { failure: { status: 'no_container' } };
+        if (/cannot connect to the docker daemon/i.test(stderr))
+            return { failure: { status: 'no_docker' } };
+        return { failure: { status: 'unreadable', detail: stderr || `docker inspect exited ${result.status}` } };
+    }
+    try {
+        return { container: JSON.parse(result.stdout) };
+    }
+    catch (err) {
+        return { failure: { status: 'unreadable', detail: `could not read what docker said (${err.message})` } };
+    }
+}
+// The deepest mount that holds this project, translated to the path inside.
+//
+// Both sides are resolved through their symlinks before they are compared. On
+// macOS `/tmp` is a link to `/private/tmp`, so a project checked out under one
+// and mounted as the other is the classic way to be told "there is no mount"
+// where there plainly is one.
+function mountedRoot(mounts, projectRoot) {
+    const root = resolved(projectRoot);
+    let best = null;
+    for (const mount of mounts) {
+        if (!mount.Source || !mount.Destination)
+            continue;
+        const inside = relative(resolved(mount.Source), root);
+        // Outside this mount, or on the far side of a `..`, or an absolute path
+        // (which `relative` returns when the two share no root at all).
+        if (inside.startsWith('..') || inside.startsWith('/'))
+            continue;
+        const depth = resolved(mount.Source).split(sep).length;
+        if (best && best.depth >= depth)
+            continue;
+        // The container's own filesystem, so its own separator: a Windows host
+        // still mounts into a Linux path.
+        best = { depth, path: inside === '' ? mount.Destination : posix.join(mount.Destination, inside.split(sep).join('/')) };
+    }
+    return best?.path ?? null;
+}
+function resolved(path) {
+    try {
+        return existsSync(path) ? realpathSync(path) : path;
+    }
+    catch {
+        return path;
+    }
+}
+// The command as it is actually executed. The wrapper is not hidden from
+// anybody: the "ran:" line a person reads and the command string that travels to
+// the brain on a failure both show this, because a line that quietly drops the
+// wrapper is a line that fails differently when somebody pastes it.
+export function dockerExec(container, workingDirectory, env, command, args) {
+    const variables = Object.entries(env).flatMap(([key, value]) => ['-e', `${key}=${value}`]);
+    return { command: 'docker', args: ['exec', '-w', workingDirectory, ...variables, container, command, ...args] };
+}
+// Docker's own failures, told apart from the project's.
+//
+// `docker exec` returns 125, 126 and 127 for reasons entirely its own — the
+// container stopped between the check and the spawn, the executable is not in
+// the image — and those codes collide with real runners' codes. Left
+// unmarked, a boot check reads the exit code as "broken", picks a cause by
+// matching the output against a path pattern, and can announce that it "found a
+// defect that stops your test suite from starting". That would be an accusation
+// about somebody's code for a failure of the daemon.
+//
+// So the code alone is never enough: the client has to have said something only
+// it says.
+const DOCKER_SPEAKING = /Error response from daemon|is not running|No such container|OCI runtime exec failed|executable file not found/i;
+export function dockerOwnFailure(result) {
+    if (result.code !== 125 && result.code !== 126 && result.code !== 127)
+        return null;
+    return DOCKER_SPEAKING.test(result.stderr) ? result.stderr.trim() : null;
+}
+// Every running container that already holds this project, for the message
+// somebody gets when their toolchain is nowhere to be found on this machine.
+//
+// Only ever called once a command has decided to fail. On the successful path
+// `docker` is not run at all, so a project with no Docker in sight pays nothing
+// and is asked nothing.
+export function containersHolding(projectRoot) {
+    const listed = spawnSync('docker', ['ps', '--format', '{{.Names}}'], { timeout: 30_000, encoding: 'utf8' });
+    if (listed.error || listed.status !== 0)
+        return [];
+    const found = [];
+    for (const name of listed.stdout.split('\n').map((line) => line.trim()).filter(Boolean)) {
+        const lookup = containerProjectRoot(name, projectRoot);
+        if (lookup.status === 'ok')
+            found.push({ name, projectRoot: lookup.projectRoot });
+    }
+    return found;
+}