@skyramp/mcp 0.5.0-rc.2 → 0.5.0-rc.3

package/build/services/FleetExecutionService.js

@@ -2,6 +2,7 @@ import Docker from "dockerode";
 import fs from "fs";
 import path from "path";
 import { Writable } from "stream";
+import { StringDecoder } from "string_decoder";
 import { stripVTControlCharacters } from "util";
 import { EXECUTOR_DOCKER_IMAGE } from "../utils/versions.js";
 import { logger } from "../utils/logger.js";
@@ -22,6 +23,8 @@ export const LAYOUT = {
         work: "/work",
         certs: "/certs",
         overrideDir: "/opt/skyramp-override",
+        nativeLib: "/opt/skyramp-libs/skyramp-linux-amd64.so",
+        npmOverride: "/tmp/skyramp-sdk",
         poolDir: "/pool",
         imageClasses: "/app/classes",
         imageLibDir: "/app/lib",
@@ -32,6 +35,8 @@ export const LAYOUT = {
         work: "C:\\work",
         certs: "C:\\certs",
         overrideDir: "C:\\opt\\skyramp-override",
+        nativeLib: "C:/opt/skyramp-libs/skyramp-windows-amd64.dll",
+        npmOverride: "C:/skyramp-sdk",
         poolDir: "C:\\pool",
         imageClasses: "C:/app/classes",
         imageLibDir: "C:/app/lib",
@@ -68,34 +73,137 @@ export async function resolvePlatform(docker, explicit) {
     }
     return os;
 }
-/** A simple (unqualified) Java class name. */
-export const JAVA_CLASS_NAME = /^[A-Za-z_$][\w$]*$/;
+/** How long an interrupted fleet gets to cancel its workers before it is killed. */
+export const CANCEL_GRACE_MS = 20_000;
+/** A pending partial line longer than this is passed on as it is. */
+const MAX_PENDING_LINE = 1024 * 1024;
+/** The most run output kept in memory; the rest is streamed to outputLog as it arrives. */
+const MAX_BUFFERED_OUTPUT = 64 * 1024;
 /**
- * The generated fleet manager: the one class in the directory that JUnit runs. The journey
- * and the load class travel with it because they sit beside it, and they are compiled but
- * never selected -- the journey is an input the fleet ships to the worker, and the load
- * class only supplies the scenario.
+ * A sink for one of the container's streams that passes on whole lines only. Docker
+ * interleaves stdout and stderr frames, so a line is only whole within its own stream:
+ * one shared sink could split a SKYRAMP_LIMIT line around a stderr frame.
+ */
+export function lineSink(emit) {
+    const decoder = new StringDecoder("utf8");
+    let pending = "";
+    const push = (text) => {
+        pending += text;
+        const lines = pending.split("\n");
+        pending = lines.pop() ?? "";
+        for (const line of lines)
+            emit(stripVTControlCharacters(line) + "\n");
+        if (pending.length > MAX_PENDING_LINE) {
+            emit(stripVTControlCharacters(pending));
+            pending = "";
+        }
+    };
+    return {
+        sink: new Writable({
+            write(chunk, _enc, cb) {
+                push(decoder.write(chunk));
+                cb();
+            },
+        }),
+        flush: () => {
+            push(decoder.end());
+            if (pending)
+                emit(stripVTControlCharacters(pending) + "\n");
+            pending = "";
+        },
+    };
+}
+/**
+ * Asks a running fleet to stop the way a user's Ctrl-C would, so an SDK that cancels on
+ * interrupt can tell its workers (DELETE) before it exits. The signal goes to the
+ * container's first process and, through exec, to every other one, because a multi-line
+ * `sh -c` script stays first and does not pass it on. Windows has no SIGINT for a
+ * container: `docker stop` is its graceful form, and it kills after the grace itself.
+ */
+async function interruptContainer(container, platform) {
+    if (platform === "windows") {
+        await container.stop({ t: Math.ceil(CANCEL_GRACE_MS / 1000) });
+        return;
+    }
+    await container.kill({ signal: "SIGINT" }).catch((e) => {
+        logger.warning(`could not interrupt the fleet container: ${e}`);
+    });
+    const exec = await container.exec({
+        Cmd: ["sh", "-c", "kill -INT -1"],
+        AttachStdout: false,
+        AttachStderr: false,
+    });
+    await exec.start({ Detach: true });
+}
+/**
+ * A simple Java class name, or a Python, TypeScript or JavaScript fleet script's file name.
+ *
+ * No `$`: the name is interpolated unquoted into the `sh`/PowerShell command built below, and
+ * `$` there is a variable sigil, not a literal character.
+ */
+export const FLEET_ENTRY_NAME = /^[A-Za-z_]\w*(\.(py|ts|js))?$/;
+/** The language a fleet entry is written in: a script by its extension, else a Java class. */
+export function fleetLanguage(entry) {
+    if (entry.endsWith(".py"))
+        return "python";
+    if (entry.endsWith(".ts"))
+        return "typescript";
+    if (entry.endsWith(".js"))
+        return "javascript";
+    return "java";
+}
+/**
+ * The SDK a branch-built package replaces: a pip sdist or wheel for Python, an npm tarball
+ * for TypeScript and JavaScript. Java takes a jar through libraryJar instead.
+ */
+export function packageLanguages(pkg) {
+    if (/\.(whl|tar\.gz)$/.test(pkg))
+        return ["python"];
+    if (/\.tgz$/.test(pkg))
+        return ["typescript", "javascript"];
+    return [];
+}
+/** The file an entry lives in, relative to the fleet directory. */
+export function fleetFileName(entry) {
+    return fleetLanguage(entry) === "java" ? `${entry}.java` : entry;
+}
+/**
+ * The generated fleet manager: the JUnit class (Java) or the script (Python, TypeScript)
+ * the run starts. The journey and the load file travel with it because they sit beside it
+ * -- the journey is an input the fleet ships to the worker, and the load file only supplies
+ * the scenario.
  */
 export function findEntryClass(directory, explicit) {
     if (explicit) {
-        // It reaches a shell script and a file path, so it must be a class name and nothing else.
-        if (!JAVA_CLASS_NAME.test(explicit)) {
-            throw new Error(`entryClass ${explicit} is not a Java class name`);
+        // It reaches a shell script and a file path, so it must be a plain name and nothing else.
+        if (!FLEET_ENTRY_NAME.test(explicit)) {
+            throw new Error(`entryClass ${explicit} is not a Java class name or a .py/.ts/.js fleet file name`);
         }
         return explicit;
     }
     const candidates = fs
         .readdirSync(directory)
-        .filter((f) => f.endsWith("FleetTest.java"))
-        .map((f) => f.replace(/\.java$/, ""))
+        .flatMap((f) => f.endsWith("FleetTest.java")
+        ? [f.replace(/\.java$/, "")]
+        : /_fleet\.(py|ts|js)$/.test(f)
+            ? [f]
+            : [])
         .sort();
     if (candidates.length === 0) {
-        throw new Error(`no *FleetTest.java in ${directory}: generate a ui-load trio there, or name the class with entryClass`);
+        throw new Error(`no *FleetTest.java, *_fleet.py, *_fleet.ts or *_fleet.js in ${directory}: generate a ui-load trio there, or name the entry with entryClass`);
     }
     if (candidates.length > 1) {
         throw new Error(`several fleet classes in ${directory} (${candidates.join(", ")}): name one with entryClass`);
     }
-    return candidates[0];
+    const entry = candidates[0];
+    // Discovered off disk, so it reaches the same unquoted shell/PowerShell interpolation as
+    // an explicit entryClass and needs the same guard.
+    if (!FLEET_ENTRY_NAME.test(entry)) {
+        throw new Error(`found fleet entry ${entry} in ${directory}, but its name is not a plain Java class ` +
+            "name or .py/.ts/.js file name safe to run in a shell command; rename it without " +
+            "$, spaces or other shell characters");
+    }
+    return entry;
 }
 /**
  * A fleet file that pins its worker image is refused.
@@ -106,27 +214,141 @@ export function findEntryClass(directory, explicit) {
  */
 export function assertNoPinnedImage(fleetFile) {
     const source = fs.readFileSync(fleetFile, "utf8");
-    // The builder call, not the word: a comment that mentions the option pins nothing.
-    const pinned = ["workerImage", "workerTag"].filter((k) => new RegExp(`\\.\\s*${k}\\s*\\(`).test(source));
+    const syntax = HOST_SYNTAX[fleetLanguage(path.basename(fleetFile))];
+    // The option as set, not the word: a comment that mentions the option pins nothing.
+    const pinned = ["workerImage", "workerTag"].filter((k) => syntax.option(k).test(source));
     if (pinned.length > 0) {
         throw new Error(`${path.basename(fleetFile)} pins ${pinned.join(" and ")}: the run would not exercise the ` +
             `library's own image choice. Regenerate with a plain host.`);
     }
 }
+/** The Docker daemon's socket, on the host and inside a Linux executor. */
+const DOCKER_SOCKET = "/var/run/docker.sock";
 /**
- * The fleet reaches the worker it deployed at an address derived from the Docker daemon:
- * the daemon's host for a remote engine, `localhost` for a local socket. Inside this
- * container `localhost` is the container, so a local-socket fleet cannot reach the worker it
- * just deployed and would hang until the timeout instead of failing.
+ * How each language spells a host and its options: the Java builder
+ * (`Host.builder("x").dockerHost("tcp://…")`), Python keywords
+ * (`skyramp.Host(docker_host="tcp://…")`) and TypeScript and JavaScript fields (`new Host({ dockerHost: "tcp://…" })`). Options are named in
+ * Java's camelCase.
+ */
+const HOST_SYNTAX = {
+    java: {
+        host: /Host\s*\.\s*builder\s*\(/,
+        option: (k) => new RegExp(`\\.\\s*${k}\\s*\\(\\s*`),
+    },
+    python: {
+        host: /\bHost\s*\(/,
+        option: (k) => new RegExp(`\\b${k.replace(/[A-Z]/g, (c) => "_" + c.toLowerCase())}\\s*=\\s*`),
+    },
+    typescript: {
+        host: /\bnew\s+Host\s*\(/,
+        option: (k) => new RegExp(`\\b${k}\\s*:\\s*`),
+    },
+    javascript: {
+        host: /\bnew\s+Host\s*\(/,
+        option: (k) => new RegExp(`\\b${k}\\s*:\\s*`),
+    },
+};
+/** Index of the `)` closing the call whose arguments start at `from`, skipping strings. */
+function closingParen(source, from) {
+    let depth = 1;
+    for (let i = from; i < source.length; i++) {
+        const c = source[i];
+        if (c === '"' || c === "'" || c === "`") {
+            for (i++; i < source.length && source[i] !== c; i++) {
+                if (source[i] === "\\")
+                    i++;
+            }
+        }
+        else if (c === "(")
+            depth++;
+        else if (c === ")" && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+/** Each host's own text: its Host(...) call, or for Java its builder chain up to .build(). */
+function hostSpans(source, language) {
+    const host = new RegExp(HOST_SYNTAX[language].host.source, "g");
+    const build = /\.\s*build\s*\(/g;
+    return [...source.matchAll(host)].map((m) => {
+        const from = m.index + m[0].length;
+        build.lastIndex = from;
+        const end = language === "java"
+            ? (build.exec(source)?.index ?? -1)
+            : closingParen(source, from);
+        if (end < 0) {
+            throw new Error("a host in the fleet file has no end this tool can find; regenerate it");
+        }
+        return source.slice(from, end);
+    });
+}
+/** A Docker Engine reached over the network, which is mTLS. */
+function remoteDockerHost(language) {
+    const prefix = HOST_SYNTAX[language].option("dockerHost").source;
+    return new RegExp(`${prefix}["'](tcp|https?):\\/\\/`);
+}
+/**
+ * A host whose options this tool cannot read at all -- built from a spread or passed in as a
+ * bare variable -- rather than written inline, so a hidden `dockerHost` would read as absent
+ * and the host would default to local. Java's builder chain has no equivalent spread syntax,
+ * so it is left to the existing per-option check.
+ */
+function opaqueHost(h, language) {
+    const trimmed = h.trim();
+    if (trimmed === "")
+        return false; // no options at all: genuinely local
+    switch (language) {
+        case "typescript":
+        case "javascript":
+            return /\.\.\.\s*[A-Za-z_$]/.test(trimmed) || !trimmed.startsWith("{");
+        case "python":
+            return /\*\*\s*[A-Za-z_]/.test(trimmed) || !/[:=]/.test(trimmed);
+        case "java":
+            return false;
+    }
+}
+/**
+ * Which Docker daemons the fleet deploys its workers through, read off its hosts.
+ *
+ * `remote`: a host names a tcp or http(s) engine. That connection is mTLS, so the run needs
+ * the client certificates.
+ *
+ * `local`: a host deploys with no remote engine, which is the daemon this tool runs the
+ * executor on. The fleet reaches it through the daemon's socket and needs no certificates:
+ * the way to try a fleet on one's own machine.
+ *
+ * A host that carries an address drives a worker that already runs and deploys nothing, so
+ * it counts as neither. Throws when no host, a non-literal dockerHost, or a host built from a
+ * spread or a bare variable leaves the engine unknown -- the last of those would otherwise
+ * read as local with no dockerHost found, mounting the daemon's socket for a host that may
+ * actually be remote.
  */
-export function assertRemoteDaemon(fleetFile) {
+export function fleetDaemons(fleetFile) {
     const source = fs.readFileSync(fleetFile, "utf8");
-    if (!/dockerHost\(\s*"(tcp|http|https):\/\//.test(source)) {
-        throw new Error(`${path.basename(fleetFile)} deploys through a local Docker socket, which this tool cannot ` +
-            `run: the fleet would look for its worker on localhost, which inside the executor ` +
-            `container is the container itself. Point the host at a remote engine ` +
-            `(dockerHost tcp://…:2376 with tls), or run this trio with gradle on the host.`);
+    const language = fleetLanguage(path.basename(fleetFile));
+    const syntax = HOST_SYNTAX[language];
+    const remoteHost = remoteDockerHost(language);
+    const all = hostSpans(source, language);
+    if (all.length === 0) {
+        throw new Error(`${path.basename(fleetFile)} has no host this tool can read, so it cannot tell which ` +
+            "Docker engine the fleet deploys on; regenerate it");
     }
+    // A host with an address deploys nothing, whichever engine it names.
+    const deploying = all.filter((h) => !syntax.option("address").test(h));
+    const dockerHost = syntax.option("dockerHost");
+    const literal = new RegExp(`${dockerHost.source}["']`);
+    if (deploying.some((h) => dockerHost.test(h) && !literal.test(h))) {
+        throw new Error(`${path.basename(fleetFile)} names a dockerHost that is not a string literal, so this ` +
+            'tool cannot tell whether it is remote; write it as a literal ("tcp://…:2376")');
+    }
+    if (deploying.some((h) => opaqueHost(h, language))) {
+        throw new Error(`${path.basename(fleetFile)} builds a host's options from a variable or a spread, so ` +
+            "this tool cannot tell whether it names a dockerHost; write the host's options " +
+            'inline, with dockerHost (if any) as a string literal ("tcp://…:2376")');
+    }
+    const remote = deploying.some((h) => remoteHost.test(h));
+    const local = deploying.some((h) => !remoteHost.test(h));
+    return { remote, local };
 }
 /**
  * The image the run happens in.
@@ -138,9 +360,45 @@ export function assertRemoteDaemon(fleetFile) {
 export function resolveExecutorImage(explicit) {
     return (explicit || process.env.SKYRAMP_EXECUTOR_IMAGE || EXECUTOR_DOCKER_IMAGE);
 }
-/** javac, then the JUnit console runner, both against the image's classpath. */
-export function buildCommand(entryClass, overrideJar, platform = "linux") {
+/**
+ * Java: javac, then the JUnit console runner, both against the image's classpath. Python,
+ * TypeScript and JavaScript: the fleet script, run from the work directory so its imports
+ * of the load file resolve beside it -- after installing a branch-built SDK package over
+ * the image's own, when one is mounted.
+ */
+export function buildCommand(entryClass, overrideJar, platform = "linux", overridePackage) {
     const l = LAYOUT[platform];
+    const language = fleetLanguage(entryClass);
+    if (language !== "java") {
+        const entry = workPath(l, entryClass);
+        if (platform === "windows") {
+            const run = {
+                python: "python.exe",
+                typescript: "tsx.cmd",
+                javascript: "node.exe",
+            }[language];
+            const script = [
+                "$ErrorActionPreference = 'Stop'",
+                ...(overridePackage
+                    ? installPackage(language, overridePackage, l, platform)
+                    : []),
+                `& ${run} ${entry}`,
+                "exit $LASTEXITCODE",
+            ].join("\n");
+            return {
+                argv: ["powershell", "-NoLogo", "-NonInteractive", "-Command", script],
+                script,
+            };
+        }
+        const run = { python: "python3", typescript: "tsx", javascript: "node" }[language];
+        const script = [
+            ...(overridePackage
+                ? ["set -e", ...installPackage(language, overridePackage, l, platform)]
+                : []),
+            `${run} ${entry}`,
+        ].join("\n");
+        return { argv: ["sh", "-c", script], script };
+    }
     const sep = l.classpathSep;
     const classes = workPath(l, "build", "classes");
     const junitRunnerGlob = `${l.imageLibDir}/junit-platform-console-standalone-*.jar`;
@@ -189,11 +447,88 @@ export function buildCommand(entryClass, overrideJar, platform = "linux") {
     ].join("\n");
     return { argv: ["sh", "-c", script], script };
 }
-/** The lines the fleet printed, which is what a reader wants out of the JUnit noise. */
+/**
+ * Installs a branch-built SDK in place of the image's own, keeping the image's native
+ * library. pip reinstalls over the image's package and leaves the library, which it did not
+ * install, in place. npm installs into a directory of its own put first on NODE_PATH: on a
+ * Windows container npm cannot replace a package directory that is part of the image.
+ */
+/** The image already carries @playwright/test, so its peer dependency is not fetched again. */
+const NPM_INSTALL_FLAGS = "--prefer-offline --no-audit --no-fund --legacy-peer-deps";
+/** Single-quotes a value for PowerShell, doubling any embedded quote. */
+function psQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Single-quotes a value for POSIX sh, closing and reopening the quote around any `'`. */
+function shQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function installPackage(language, pkg, l, platform) {
+    if (platform === "windows") {
+        const check = "if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }";
+        if (language === "python") {
+            return [
+                "& python.exe -m pip install -q --no-deps --force-reinstall " +
+                    `--disable-pip-version-check ${psQuote(pkg)}`,
+                check,
+            ];
+        }
+        const modules = `${l.npmOverride}/node_modules`;
+        const lib = `${modules}/@skyramp/skyramp/lib`;
+        return [
+            `& npm.cmd install --prefix ${psQuote(l.npmOverride)} ${NPM_INSTALL_FLAGS} ${psQuote(pkg)}`,
+            check,
+            `New-Item -ItemType Directory -Force ${psQuote(lib)} | Out-Null`,
+            `Copy-Item ${psQuote(l.nativeLib)} ${psQuote(`${lib}/`)} -Force`,
+            `$env:NODE_PATH = ${psQuote(`${modules};`)} + $env:NODE_PATH`,
+        ];
+    }
+    if (language === "python") {
+        return [
+            `python3 -m pip install -q --no-deps --force-reinstall ${shQuote(pkg)}`,
+        ];
+    }
+    const modules = `${l.npmOverride}/node_modules`;
+    return [
+        `npm install --prefix ${shQuote(l.npmOverride)} ${NPM_INSTALL_FLAGS} ${shQuote(pkg)}`,
+        `mkdir -p ${shQuote(`${modules}/@skyramp/skyramp/lib`)} && ` +
+            `ln -sf ${shQuote(l.nativeLib)} ${shQuote(`${modules}/@skyramp/skyramp/lib/`)}`,
+        `export NODE_PATH="${modules}:$NODE_PATH"`,
+    ];
+}
+/**
+ * The lines the fleet printed, which is what a reader wants out of the JUnit noise: the
+ * one-line digest, or the report blocks (name in column one, continuation lines indented).
+ */
 export function extractReport(output) {
-    const keep = /^\s*(verdict|counts|rate|latency|vitals|per-region|step|action|generator|host error|warning):/;
-    const lines = output.split("\n").filter((l) => keep.test(l));
-    return lines.map((l) => l.trim()).join("\n");
+    const digest = /^\s*(verdict|counts|rate|latency|vitals|per-region|step|action|generator|host error|warning):/;
+    const block = /^(RUN|VERDICT|LOAD|BACKEND|FRONTEND|SLOWEST|REQUESTS|STEPS|TREND|REGIONS|HOSTS|OVER TIME|HEALTH|LIMITS|WARNINGS)\s/;
+    const kept = [];
+    let inBlock = false;
+    for (const line of output.split("\n")) {
+        if (block.test(line) || (inBlock && /^ {10}\s*\S/.test(line))) {
+            inBlock = true;
+            kept.push(line.trimEnd());
+            continue;
+        }
+        inBlock = false;
+        if (digest.test(line))
+            kept.push(line.trim());
+    }
+    return kept.join("\n");
+}
+/**
+ * The report the library rendered itself, carried in the structured result as `report`.
+ * Preferred over the stdout filter: it is the complete text, not whatever survived the
+ * JUnit runner's console, and it is the same text every SDK prints.
+ */
+export function embeddedReport(result) {
+    if (result && typeof result === "object" && "report" in result) {
+        const report = result.report;
+        if (typeof report === "string" && report.trim() !== "")
+            return report.trimEnd();
+    }
+    return undefined;
 }
 /**
  * Where a path inside the container lands on the host.
@@ -231,6 +566,13 @@ function mount(source, target, readOnly = false) {
         ReadOnly: readOnly,
     };
 }
+/** The file's name goes into the executor's quoted shell command. */
+function assertCommandSafeName(file) {
+    if (/['"`$\r\n]/.test(path.basename(file))) {
+        throw new Error(`${path.basename(file)}: rename the file without quotes, $ or backticks; its name ` +
+            "goes into the executor's shell command");
+    }
+}
 /**
  * Mounts a host file by its directory, and returns where the file lands in the container.
  *
@@ -252,12 +594,16 @@ export async function executeFleet(options, docker = new Docker()) {
         throw new Error(`directory not found: ${directory}`);
     }
     const entryClass = findEntryClass(directory, options.entryClass);
-    const fleetFile = path.join(directory, `${entryClass}.java`);
+    const fleetFile = path.join(directory, fleetFileName(entryClass));
     if (!fs.existsSync(fleetFile)) {
         throw new Error(`entry class ${entryClass} has no file at ${fleetFile}`);
     }
     assertNoPinnedImage(fleetFile);
-    assertRemoteDaemon(fleetFile);
+    const daemons = fleetDaemons(fleetFile);
+    if (daemons.remote && !options.certsDir) {
+        throw new Error(`certsDir is required: ${path.basename(fleetFile)} deploys on a remote Docker engine, ` +
+            "which is mTLS. Pass the directory holding ca.pem, cert.pem and key.pem.");
+    }
     const credentials = options.credentials
         ? path.resolve(options.credentials)
         : path.join(directory, "credentials.csv");
@@ -267,6 +613,17 @@ export async function executeFleet(options, docker = new Docker()) {
     const executorImage = resolveExecutorImage(options.executorImage);
     const platform = await resolvePlatform(docker, options.platform);
     const l = LAYOUT[platform];
+    if (daemons.local && platform !== "linux") {
+        throw new Error(`${path.basename(fleetFile)} deploys on the local Docker daemon, which this tool ` +
+            `reaches through ${DOCKER_SOCKET}: a ${platform} daemon has no such socket. Point ` +
+            "the host at the engine (dockerHost tcp://…:2376 with tls).");
+    }
+    if (daemons.local && !options.localDocker) {
+        throw new Error(`${path.basename(fleetFile)} deploys on the local Docker daemon. The run would mount ` +
+            `${DOCKER_SOCKET} into the executor, which gives the fleet code root-level access ` +
+            "to this host. Pass localDocker: true to allow it, or point the hosts at a remote " +
+            "engine (dockerHost tcp://…:2376 with tls).");
+    }
     const mounts = [mount(directory, l.work)];
     const derived = {
         SKYRAMP_FLEET_REPORT_JSON: workPath(l, "build", "fleet-result.json"),
@@ -277,18 +634,45 @@ export async function executeFleet(options, docker = new Docker()) {
                 ? workPath(l, path.basename(credentials))
                 : mountFileDir(mounts, l, credentials, l.poolDir);
     }
-    const certs = path.resolve(options.certsDir);
-    if (!fs.existsSync(certs)) {
-        throw new Error(`certificate directory not found: ${certs}`);
+    if (options.certsDir) {
+        const certs = path.resolve(options.certsDir);
+        if (!fs.existsSync(certs)) {
+            throw new Error(`certificate directory not found: ${certs}`);
+        }
+        mounts.push(mount(certs, l.certs, true));
+        derived.SKYRAMP_DOCKER_CERTS = l.certs;
+    }
+    if (daemons.local) {
+        // The fleet deploys its worker through the daemon's own socket. The worker's port is
+        // then published on the Docker host, which from inside this container is
+        // host.docker.internal and not localhost: SKYRAMP_IN_DOCKER tells the library so.
+        mounts.push(mount(DOCKER_SOCKET, DOCKER_SOCKET));
+        derived.SKYRAMP_IN_DOCKER = "true";
     }
-    mounts.push(mount(certs, l.certs, true));
-    derived.SKYRAMP_DOCKER_CERTS = l.certs;
+    const language = fleetLanguage(entryClass);
     let overrideJar;
+    if (options.libraryJar && language !== "java") {
+        throw new Error(`libraryJar applies to a Java fleet; for ${entryClass} pass the SDK package as libraryPackage`);
+    }
+    let overridePackage;
+    if (options.libraryPackage) {
+        const pkg = path.resolve(options.libraryPackage);
+        if (!packageLanguages(pkg).includes(language)) {
+            throw new Error(`libraryPackage ${path.basename(pkg)} does not fit ${entryClass}: python takes a pip ` +
+                ".whl or .tar.gz, typescript and javascript an npm .tgz, java a jar through libraryJar");
+        }
+        if (!fs.existsSync(pkg)) {
+            throw new Error(`library package not found: ${pkg}`);
+        }
+        assertCommandSafeName(pkg);
+        overridePackage = mountFileDir(mounts, l, pkg, l.overrideDir);
+    }
     if (options.libraryJar) {
         const jar = path.resolve(options.libraryJar);
         if (!fs.existsSync(jar)) {
             throw new Error(`library jar not found: ${jar}`);
         }
+        assertCommandSafeName(jar);
         overrideJar = mountFileDir(mounts, l, jar, l.overrideDir);
     }
     // One rule for every variable the tool derives: the caller's env wins.
@@ -316,33 +700,80 @@ export async function executeFleet(options, docker = new Docker()) {
                 `set executorImage (or SKYRAMP_EXECUTOR_IMAGE) to one built for it.`, { cause: err });
         }
     }
+    if (options.signal?.aborted) {
+        throw new Error("fleet run cancelled before its container started");
+    }
     const container = await docker.createContainer({
         Image: executorImage,
-        Cmd: buildCommand(entryClass, overrideJar, platform).argv,
+        Cmd: buildCommand(entryClass, overrideJar, platform, overridePackage).argv,
         WorkingDir: l.work,
         Env: Object.entries(env).map(([k, v]) => `${k}=${v}`),
         Tty: false,
         platform: imagePlatform,
-        HostConfig: { Mounts: mounts, AutoRemove: false },
+        HostConfig: {
+            Mounts: mounts,
+            AutoRemove: false,
+            // Docker Desktop resolves the name by itself; a Linux engine needs it mapped.
+            ...(daemons.local
+                ? { ExtraHosts: ["host.docker.internal:host-gateway"] }
+                : {}),
+        },
     });
     let output = "";
     let exitCode = null;
     let timedOut = false;
+    let cancelled = false;
+    let escalate;
+    // Written to as the run streams, so a noisy multi-hour fleet never buffers its full
+    // output in memory; only a fixed-size tail is kept here, below.
+    let outputLog = path.join(directory, "build", "fleet-output.log");
+    let logStream;
     try {
-        const sink = new Writable({
-            write(chunk, _enc, cb) {
-                output += stripVTControlCharacters(chunk.toString());
-                cb();
-            },
+        fs.mkdirSync(path.dirname(outputLog), { recursive: true });
+        logStream = fs.createWriteStream(outputLog);
+    }
+    catch (e) {
+        logger.warning(`could not open the fleet output log at ${outputLog}: ${e}`);
+        outputLog = undefined;
+    }
+    logStream?.on("error", (e) => {
+        logger.warning(`could not write the fleet output to ${outputLog}: ${e}`);
+        outputLog = undefined;
+    });
+    const onAbort = () => {
+        if (cancelled)
+            return;
+        cancelled = true;
+        interruptContainer(container, platform).catch((e) => {
+            logger.warning(`could not interrupt the fleet run gracefully: ${e}`);
         });
+        escalate = setTimeout(() => {
+            container.kill().catch(() => {
+                // Already gone: it stopped within the grace.
+            });
+        }, CANCEL_GRACE_MS);
+    };
+    const emit = (line) => {
+        logStream?.write(line);
+        output += line;
+        if (output.length > MAX_BUFFERED_OUTPUT)
+            output = output.slice(-MAX_BUFFERED_OUTPUT);
+        options.onOutput?.(line);
+    };
+    const stdout = lineSink(emit);
+    const stderr = lineSink(emit);
+    try {
         const stream = await container.attach({
             stream: true,
             stdout: true,
             stderr: true,
         });
-        container.modem.demuxStream(stream, sink, sink);
+        container.modem.demuxStream(stream, stdout.sink, stderr.sink);
         const timeoutMs = (options.timeoutSec ?? 600) * 1000;
         await container.start();
+        if (options.signal?.aborted)
+            onAbort();
+        options.signal?.addEventListener("abort", onAbort, { once: true });
         const timer = setTimeout(() => {
             timedOut = true;
             container.kill().catch((e) => {
@@ -359,9 +790,15 @@ export async function executeFleet(options, docker = new Docker()) {
         }
     }
     finally {
+        options.signal?.removeEventListener("abort", onAbort);
+        clearTimeout(escalate);
+        stdout.flush();
+        stderr.flush();
         await container.remove({ force: true }).catch((e) => {
             logger.error(`could not remove the fleet container: ${e}`);
         });
+        if (logStream)
+            await new Promise((resolve) => logStream.end(() => resolve()));
     }
     let result;
     if (jsonPath === undefined) {
@@ -378,14 +815,16 @@ export async function executeFleet(options, docker = new Docker()) {
         }
     }
     return {
-        passed: exitCode === 0 && !timedOut,
+        passed: exitCode === 0 && !timedOut && !cancelled,
         executorImage,
         platform,
         entryClass,
         exitCode,
-        report: extractReport(output),
+        report: embeddedReport(result) ?? extractReport(output),
         output,
         result,
         timedOut: timedOut || undefined,
+        cancelled: cancelled || undefined,
+        outputLog,
     };
 }