@specific.dev/spectest 0.27.0 → 0.28.1

package/dist/browser.d.ts

@@ -154,8 +154,8 @@ export interface Browser {
     /**
      * Capture a PNG screenshot of the viewport and upload it as a downloadable
      * **artifact**. Resolves to the artifact's `art_…` id — fetch it locally
-     * with `spectest artifact download <id>`. Eval-only (`spectest_eval` /
-     * `spectest env eval`); throws with a clear message during test runs.
+     * with `spectest artifact download <id>`. Eval-only (`spectest env eval`);
+     * throws with a clear message during test runs.
      */
     screenshot(): Promise<string>;
     /**

package/dist/browser.js

@@ -1187,7 +1187,7 @@ function buildBackend(holder, recorder, buildOpts) {
                 const register = recorder?.registerArtifact;
                 if (!register) {
                     throw new Error("screenshot() uploads the capture as a downloadable artifact and is " +
-                        "currently only available inside an eval (spectest_eval / `spectest env eval`) — " +
+                        "currently only available inside an eval (`spectest env eval`) — " +
                         "it cannot be used in test runs.");
                 }
                 // Raw CDP rather than page.screenshot(): captures the viewport

package/dist/components/k3s.d.ts

@@ -7,8 +7,37 @@ export interface K3sOptions {
     /**
      * Extra arguments appended to `k3s server`. Useful for `--tls-san=...`,
      * additional `--disable=<addon>`, custom CIDRs, etc.
+     *
+     * Two values are **rejected** rather than silently ignored, because the
+     * component owns those decisions and passing them here has no effect:
+     * `--disable=traefik` (use `traefik: false`) and `--disable=servicelb`
+     * (use `loadBalancer: false`).
      */
     extraArgs?: string[];
+    /**
+     * Install the component's own Traefik ingress controller (hostNetwork,
+     * default IngressClass, wired to the in-VM CA when `ingressDomains` is
+     * set). Default `true`.
+     *
+     * Set `false` to run a cluster with no ingress controller at all — for
+     * a project that installs its own (via Helm, an operator, or a raw
+     * manifest) and wants the port to itself. The bundled k3s Traefik is
+     * disabled either way, so `false` really does mean none.
+     */
+    traefik?: boolean;
+    /**
+     * Run k3s's ServiceLB (klipper-lb) so `type: LoadBalancer` Services are
+     * assigned an address instead of sitting at `<pending>` forever.
+     * Default `true`.
+     *
+     * The assigned address is the **node IP** — the k3s container's own IP
+     * on `spectest-net` — so a LoadBalancer on port 8080 is reachable from
+     * a test or a peer service at `<cluster-key>.internal:8080`. Because
+     * klipper-lb binds the port on the node, a LoadBalancer that asks for
+     * port 80 or 443 collides with the component's hostNetwork Traefik;
+     * either pick another port or pass `traefik: false`.
+     */
+    loadBalancer?: boolean;
     /**
      * Readiness probe timeout in seconds. k3s on a warm image is ready in
      * a few seconds; the first cold start of an env (image pull + cluster

package/dist/components/k3s.js

@@ -10,6 +10,31 @@ import { readRaw, readTag, wrap } from "../inspect.js";
 import { recorderAnnotate, recorderRemove } from "../recorder.js";
 /** Port the in-cluster registry listens on (plain HTTP). */
 const K3S_REGISTRY_PORT = 5000;
+/**
+ * `extraArgs` entries the component overrides anyway. Passing one of
+ * these looks like it works — the flag really is appended to the k3s
+ * command line — but the component's own behaviour is what decides the
+ * outcome, so the cluster comes up contradicting the argument. Failing
+ * at load time costs a second; discovering it costs a boot cycle.
+ */
+const OVERRIDDEN_EXTRA_ARGS = {
+    traefik: "the component installs its own Traefik (hostNetwork) after the cluster is up — " +
+        "pass `traefik: false` to have no ingress controller at all",
+    servicelb: "ServiceLB is controlled by the `loadBalancer` option — pass `loadBalancer: false` to disable it",
+};
+function assertUsableExtraArgs(extra) {
+    for (const arg of extra) {
+        const m = /^--disable[=\s]+(.+)$/.exec(arg.trim());
+        const addon = m?.[1]?.trim();
+        if (!addon)
+            continue;
+        const why = OVERRIDDEN_EXTRA_ARGS[addon];
+        if (why) {
+            throw new Error(`k3s(): extraArgs cannot control "${addon}" — ${why}. ` +
+                `(Remove ${JSON.stringify(arg)} from extraArgs.)`);
+        }
+    }
+}
 function runProcess(cmd, args, timeoutMs = 30_000) {
     return new Promise((resolve, reject) => {
         const cp = nodeSpawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
@@ -723,7 +748,7 @@ async function waitForDeployment(clusterName, helpers, deployment, timeoutMs) {
  * reachable over HTTPS with a cert the test framework already trusts.
  */
 async function setupK3sCluster(name, helpers, opts) {
-    const tlsEnabled = opts.ingressDomains.length > 0 && caPresent();
+    const tlsEnabled = opts.traefik && opts.ingressDomains.length > 0 && caPresent();
     if (tlsEnabled) {
         const { cert, key } = await issueIngressCert(opts.ingressDomains.map((d) => `*.${d}`));
         // Apply the cert Secret + dynamic-config ConfigMap before the
@@ -748,12 +773,15 @@ async function setupK3sCluster(name, helpers, opts) {
             },
         });
     }
-    await helpers.apply(buildTraefikManifest(tlsEnabled));
+    if (opts.traefik)
+        await helpers.apply(buildTraefikManifest(tlsEnabled));
     if (opts.registry)
         await helpers.apply(REGISTRY_MANIFEST);
     // Both rollouts proceed independently inside the cluster — wait on them
     // concurrently (they used to serialize, wasting up to a rollout's tail).
-    const waits = [waitForDeployment(name, helpers, "traefik", 120_000)];
+    const waits = opts.traefik
+        ? [waitForDeployment(name, helpers, "traefik", 120_000)]
+        : [];
     if (opts.registry) {
         waits.push(waitForDeployment(name, helpers, "spectest-registry", 120_000));
     }
@@ -891,7 +919,10 @@ const DEFAULT_K3S_VERSION = "v1.32.1-k3s1";
 export function k3s(opts = {}) {
     const version = opts.version ?? DEFAULT_K3S_VERSION;
     const extra = opts.extraArgs ?? [];
+    assertUsableExtraArgs(extra);
     const registryEnabled = opts.registry !== false;
+    const traefikEnabled = opts.traefik !== false;
+    const loadBalancerEnabled = opts.loadBalancer !== false;
     // Wildcard ingress domains. Drives both the `provides(... dnsName)`
     // wiring below and (when non-empty) the CA-signed TLS default cert that
     // setupK3sCluster mints so these domains are reachable over HTTPS.
@@ -917,14 +948,26 @@ export function k3s(opts = {}) {
         "--resolv-conf=/run/spectest-resolv.conf",
         // metrics-server isn't useful in a test cluster.
         "--disable=metrics-server",
-        // traefik + servicelb disabled: their klipper-lb DaemonSet uses
-        // CNI portmap to bind host port 80, which still needs xt_comment
-        // (the iptables compat path that the kernel can't satisfy).
-        // We install Traefik with hostNetwork in setup() — same effect,
-        // no portmap involved. local-storage stays enabled: it's a
-        // controller pod that doesn't bind host ports.
+        // The bundled traefik is disabled because we install our own with
+        // hostNetwork (see setupK3sCluster) — ours is wired to the in-VM CA
+        // for `ingressDomains` TLS and to a fixed IngressClass. Opt out of
+        // ours entirely with `k3s({ traefik: false })`; passing
+        // `--disable=traefik` via `extraArgs` does NOT do that (it only
+        // re-disables the bundled one, which is already off) and is rejected
+        // below rather than silently ignored.
         "--disable=traefik",
-        "--disable=servicelb",
+        // ServiceLB (klipper-lb) stays ENABLED, so `type: LoadBalancer`
+        // Services get an address and work. It was disabled for years
+        // because klipper-lb binds its ports with a CNI portmap hostPort,
+        // and portmap's iptables-nft rules need the `xt_comment` netfilter
+        // match — absent from the hosted provider's stock kernel, which made
+        // every LoadBalancer hang at <pending> with no svclb DaemonSet. We
+        // build the guest kernel ourselves now and it carries
+        // CONFIG_NETFILTER_XT_MATCH_COMMENT (see
+        // scripts/local-vms-kernel-additions.config), so the constraint is
+        // gone. local-storage stays enabled too: a controller pod that binds
+        // no host ports.
+        ...(loadBalancerEnabled ? [] : ["--disable=servicelb"]),
         // Pod CIDR MUST avoid 10.42.0.0/16: that's the spectest-br0 host
         // bridge subnet, whose gateway 10.42.0.1 fronts the host image caches
         // (zot :5000-5007, buildkitd :1234). k3s's *default* pod CIDR is also
@@ -959,6 +1002,16 @@ export function k3s(opts = {}) {
         "printf 'nameserver %s\\noptions ndots:0\\n' \"$GW\" > /run/spectest-resolv.conf; " +
         "else echo 'spectest: no default gateway found; k3s pod DNS for peer services will not resolve' >&2; " +
         ": > /run/spectest-resolv.conf; fi; " +
+        // Make the root mount shared. A CSI node plugin bind-mounts volumes
+        // under /var/lib/kubelet and needs that propagation to reach the
+        // kubelet and the workload pod; docker gives a container a private
+        // root, so without this every CSI node plugin fails to publish and
+        // any snapshot/PVC-backed storage test is impossible. `kind` does the
+        // same in its entrypoint for the same reason. Best-effort: on a
+        // kernel/runtime that refuses it, the cluster still boots — only CSI
+        // is affected.
+        "mount --make-rshared / 2>/dev/null || " +
+        "echo 'spectest: could not make / rshared; CSI node plugins may fail to publish volumes' >&2; " +
         `exec ${serverArgs}`;
     // Plain /readyz probe. On a warm zot cache the cluster's images are
     // already local, so the first boot completes in seconds; the
@@ -972,10 +1025,13 @@ export function k3s(opts = {}) {
         tmpfs: ["/run", "/var/run"],
         cgroupns: "host",
         // 80/443 are advisory — peer services and host code reach them via
-        // the k3s container's IP. ServiceLB (klipper-lb) binds them inside
-        // the container's netns and forwards to the traefik pod. 5000 is the
+        // the k3s container's IP. The component's Traefik binds them directly
+        // (hostNetwork, so it shares the container's netns). 5000 is the
         // in-cluster registry (hostNetwork pod bound to the container netns),
         // reached by peers at the cluster's own `<key>.internal:5000` alias.
+        // A `type: LoadBalancer` Service's ports are bound by klipper-lb in
+        // the same netns and are reachable the same way, without appearing
+        // in this list (it's documentation, not a firewall).
         ports: registryEnabled ? [80, 443, 6443, K3S_REGISTRY_PORT] : [80, 443, 6443],
         // NOTE: do NOT mount /var/lib/rancher/k3s/agent/containerd as a cache
         // volume. It was tried (to spare a recreated cluster re-pulling its
@@ -1002,6 +1058,7 @@ export function k3s(opts = {}) {
             await setupK3sCluster(name, helpers, {
                 registry: registryEnabled,
                 ingressDomains,
+                traefik: traefikEnabled,
             });
         },
         helpers: async ({ name, exec }) => {

package/dist/components/replayFake.js

@@ -19,7 +19,7 @@
 //   - RECORD (MITM): the request is forwarded to the REAL host and the
 //     request/response pair is captured (decoded, redacted), and the real
 //     response is returned to the app so a manual session behaves like
-//     production. This runs under `spectest_eval` / a manual env.
+//     production. This runs under `spectest env eval` against a manual env.
 //
 // Because the fake's hostname IS the real host, the in-VM resolver points
 // that name at the daemon — so a naive `fetch("https://api.stripe.com")`
@@ -509,7 +509,7 @@ export function replayFake(opts) {
         if (missing.length > 0) {
             const refs = [...new Set(missing)];
             return new Response(`replayFake(${opts.name}): secret(s) ${JSON.stringify(refs)} were not supplied ` +
-                `(configure them on the project's Secrets page, and record via spectest_eval).\n`, { status: 599, headers: { "content-type": "text/plain" } });
+                `(configure them on the project's Secrets page, and record via \`spectest env eval\`).\n`, { status: 599, headers: { "content-type": "text/plain" } });
         }
         // Resolve the REAL host's IP via an external resolver so we don't loop
         // back into the daemon (the in-VM resolver answers our own gateway for

package/dist/daemon.js

@@ -293,6 +293,38 @@ function shxStream(file, args, timeoutMs, env, onLine) {
         }
     });
 }
+// ── Boot log ─────────────────────────────────────────────────────────────
+// Everything the daemon logs while bringing the environment up, including
+// `console.log` from service `setup` hooks and project `setup`. Those used
+// to reach only the VM's journal, so on a *successful* boot they were
+// invisible — the one case where a long bootstrap most needs explaining.
+// Kept in daemon memory (so it rides snapshots like everything else) and
+// served by GET /boot-log; capped so a chatty setup can't grow unbounded.
+const BOOT_LOG_MAX_BYTES = 512 * 1024;
+const BOOT_LOG = {
+    lines: [],
+    bytes: 0,
+    dropped: 0,
+};
+/** A {@link LineSink} that appends to the capped boot log. */
+const BOOT_LOG_SINK = {
+    push(line) {
+        BOOT_LOG.lines.push(line);
+        BOOT_LOG.bytes += line.length;
+        // Drop from the front: the tail is what explains where a boot is now.
+        while (BOOT_LOG.bytes > BOOT_LOG_MAX_BYTES && BOOT_LOG.lines.length > 1) {
+            const gone = BOOT_LOG.lines.shift();
+            BOOT_LOG.bytes -= gone.length;
+            BOOT_LOG.dropped += 1;
+        }
+    },
+};
+function bootLogText() {
+    const head = BOOT_LOG.dropped > 0
+        ? `[spectest: ${BOOT_LOG.dropped} earlier line(s) dropped — boot log capped at ${BOOT_LOG_MAX_BYTES} bytes]\n`
+        : "";
+    return head + BOOT_LOG.lines.join("");
+}
 let BOOTSTRAP_PROGRESS = null;
 function progressInit(services) {
     BOOTSTRAP_PROGRESS = {
@@ -517,6 +549,63 @@ async function ensureFiles(svc) {
     }
     return flags;
 }
+/**
+ * Mint each `svc.certificates` entry from the in-VM root CA and return
+ * `--volume` flags bind-mounting the PEMs into the container, using the
+ * same pre-entrypoint injection point as {@link ensureFiles}.
+ *
+ * This is what lets a service terminate TLS *itself* with a certificate
+ * the environment already trusts — the `tls` field can't help there,
+ * since it terminates in the daemon and proxies plain HTTP to the
+ * upstream. Anything that routes by SNI, verifies a client cert, or
+ * speaks a protocol with its own TLS handshake needs the key material.
+ *
+ * Minted fresh on every bootstrap rather than cached: certs are cheap
+ * (~50 ms), and a stale one outliving a CA rotation would fail in a way
+ * that reads as a code bug.
+ */
+async function ensureCertificates(svc) {
+    const flags = [];
+    const certs = svc.certificates ?? [];
+    if (certs.length === 0)
+        return flags;
+    if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
+        throw new Error(`service "${svc.name}": certificates require the in-VM root CA at ${CA_PATH}`);
+    }
+    const dir = path.join(WORKSPACE, ".spectest", "certs", svc.name);
+    await fs.mkdir(dir, { recursive: true });
+    for (const [i, c] of certs.entries()) {
+        for (const [label, p] of [
+            ["certPath", c.certPath],
+            ["keyPath", c.keyPath],
+            ...(c.caPath ? [["caPath", c.caPath]] : []),
+        ]) {
+            if (!p.startsWith("/")) {
+                throw new Error(`service "${svc.name}": certificate ${label} ${JSON.stringify(p)} must be absolute`);
+            }
+        }
+        const hostnames = c.hostnames.map((h) => h.replaceAll("{{SPECTEST_SERVICE}}", svc.name));
+        if (hostnames.length === 0) {
+            throw new Error(`service "${svc.name}": certificate entry ${i} lists no hostnames`);
+        }
+        const { cert, key } = await generateHostCert(`${svc.name}-${i}`, hostnames);
+        const certHost = path.join(dir, `${i}.crt`);
+        const keyHost = path.join(dir, `${i}.key`);
+        await fs.writeFile(certHost, cert);
+        await fs.writeFile(keyHost, key);
+        // The key's mode has to be set on the staged file: a bind mount
+        // carries the host inode's permissions straight through, and a
+        // server that checks (postgres, ssh) refuses a lax one.
+        if (c.mode)
+            await fs.chmod(keyHost, parseInt(c.mode, 8));
+        flags.push(`--volume=${certHost}:${c.certPath}:ro`);
+        flags.push(`--volume=${keyHost}:${c.keyPath}:ro`);
+        if (c.caPath)
+            flags.push(`--volume=${CA_PATH}:${c.caPath}:ro`);
+        console.log(`[bootstrap] ${svc.name}: minted certificate for ${hostnames.join(", ")}`);
+    }
+    return flags;
+}
 function imageTag(name) {
     return `spectest/${name}:latest`;
 }
@@ -537,6 +626,54 @@ const DEFAULT_DOCKERIGNORE = [
     ".turbo",
     ".DS_Store",
 ];
+/** First line of the `.dockerignore` we generate ourselves, so a later
+ *  bootstrap can tell our file apart from one the project ships and never
+ *  mistakes its own output for user intent. */
+const GENERATED_DOCKERIGNORE_HEADER = "# spectest-generated — do not edit (your own .dockerignore is honoured verbatim)";
+/**
+ * The project's own `/workspace/.dockerignore`, read once per bootstrap
+ * before we write anything, or `null` when it ships none.
+ *
+ * This file is the project's statement about what belongs in a build
+ * context, and it is frequently the difference between a 30-second and a
+ * 30-minute build (the `**` + negations idiom keeps a monorepo's context
+ * down to the handful of files a Go build actually reads). We used to
+ * ignore it entirely *and* overwrite it — so a carefully minimised
+ * context silently became the whole repo, and the checked-out file was
+ * clobbered for any in-env tooling that read it too.
+ */
+let PROJECT_DOCKERIGNORE = null;
+async function readProjectDockerignore() {
+    try {
+        const text = await fs.readFile(path.join(WORKSPACE, ".dockerignore"), "utf8");
+        // Ours, from a previous bootstrap of this workspace — not the project's.
+        if (text.startsWith(GENERATED_DOCKERIGNORE_HEADER))
+            return null;
+        return text;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ignore rules for one dockerfile build, in precedence order: our
+ * defaults, then the project's own `.dockerignore` verbatim, then that
+ * service's `exclude`.
+ *
+ * Order is load-bearing for the `**` + negations idiom — the project's
+ * `**` subsumes our defaults, its `!` lines re-include exactly what the
+ * build needs, and the per-service `exclude` still gets the last word.
+ */
+function serviceDockerignore(exclude) {
+    const parts = [DEFAULT_DOCKERIGNORE.join("\n")];
+    if (PROJECT_DOCKERIGNORE !== null) {
+        parts.push(`# --- from the project's .dockerignore ---\n${PROJECT_DOCKERIGNORE.trimEnd()}`);
+    }
+    if (exclude && exclude.length > 0) {
+        parts.push(`# --- from this service's exclude ---\n${exclude.join("\n")}`);
+    }
+    return parts.join("\n") + "\n";
+}
 function unionDockerignore(services) {
     const seen = new Set(DEFAULT_DOCKERIGNORE);
     const extras = [];
@@ -550,7 +687,7 @@ function unionDockerignore(services) {
             }
         }
     }
-    return [...DEFAULT_DOCKERIGNORE, ...extras].join("\n") + "\n";
+    return ([GENERATED_DOCKERIGNORE_HEADER, ...DEFAULT_DOCKERIGNORE, ...extras].join("\n") + "\n");
 }
 /// In-flight/finished dockerfile builds of this bootstrap, keyed by
 /// sha256(dockerfile content + exclude list). Services that share an
@@ -650,14 +787,15 @@ async function buildServiceImage(name, image, tag) {
         await fs.writeFile(dfPath, image.content);
         // Per-service ignore: BuildKit resolves `<Dockerfile>.dockerignore`
         // (next to the Dockerfile) in preference to the context root's
-        // `.dockerignore`, so this build sees the defaults plus ITS OWN
-        // `exclude` only — one service excluding `handhelds/**` no longer
-        // empties a sibling's build context. Verified on both the remote-buildx
-        // and DOCKER_BUILDKIT paths (client-side context filtering). The root
-        // union `.dockerignore` written at bootstrap stays as the fallback for
-        // the legacy non-BuildKit builder, which predates per-Dockerfile
-        // ignores.
-        await fs.writeFile(`${dfPath}.dockerignore`, [...DEFAULT_DOCKERIGNORE, ...(image.exclude ?? [])].join("\n") + "\n");
+        // `.dockerignore`, so this build sees the defaults, the project's own
+        // `.dockerignore`, and ITS OWN `exclude` — one service excluding
+        // `handhelds/**` no longer empties a sibling's build context. Verified
+        // on both the remote-buildx and DOCKER_BUILDKIT paths (client-side
+        // context filtering). The root `.dockerignore` written at bootstrap
+        // stays as the fallback for the legacy non-BuildKit builder, which
+        // predates per-Dockerfile ignores — and is written ONLY when the
+        // project ships none of its own (see readProjectDockerignore).
+        await fs.writeFile(`${dfPath}.dockerignore`, serviceDockerignore(image.exclude));
         const useRemote = await ensureRemoteBuilder();
         // Both the remote builder and a local buildx are BuildKit, so both emit
         // per-step timing on stderr under `--progress=plain` (parsed below). Only
@@ -1966,6 +2104,32 @@ async function registerDnsName(hostname, target) {
     await writeRegistry();
     recordEnv({ op: "dnsName", hostname: decl.hostname, ip, durationMs: 0 }, resv);
 }
+/**
+ * Mint a leaf certificate from the in-VM root CA and hand back the PEMs
+ * — the implementation behind `ctx.certificate`.
+ *
+ * The value-returning counterpart to the `certificates` service field:
+ * use that to hand a cert to a container at boot, use this when a *test*
+ * needs the material as data — loading it into a Kubernetes Secret,
+ * posting it to a control-plane API, driving a client-cert handshake.
+ * The returned `ca` is the same root every service and `ctx.fetch` /
+ * `ctx.browser()` already trust, so a server configured with these PEMs
+ * verifies cleanly with no `rejectUnauthorized: false`.
+ */
+async function mintCertificate(hostnames) {
+    const resv = reserveEvent();
+    const t = Date.now();
+    if (!Array.isArray(hostnames) || hostnames.length === 0) {
+        throw new Error("ctx.certificate(hostnames): at least one hostname is required");
+    }
+    if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
+        throw new Error(`ctx.certificate(): the in-VM root CA is missing at ${CA_PATH}`);
+    }
+    const { cert, key } = await generateHostCert("ctx", hostnames);
+    const ca = await fs.readFile(CA_PATH, "utf8");
+    recordEnv({ op: "certificate", hostnames, durationMs: Date.now() - t }, resv);
+    return { cert, key, ca };
+}
 // ────────────────────────────────────────────────────────────────────────
 // Runtime services — containers started after bootstrap (from a test, an
 // eval, project setup, or a fake handler reacting to the app under test).
@@ -2005,7 +2169,11 @@ async function startRuntimeService(spec) {
     const imageRef = svc.image.type === "registry" ? svc.image.reference : "(dockerfile)";
     try {
         const { tag } = await prepareServiceImage(svc);
-        const flags = [...(await ensureVolumes(svc)), ...(await ensureFiles(svc))];
+        const flags = [
+            ...(await ensureVolumes(svc)),
+            ...(await ensureFiles(svc)),
+            ...(await ensureCertificates(svc)),
+        ];
         await runContainer(svc, tag, flags, aliases);
         await waitForReady(svc);
         const ip = (await serviceContainerIp(svc.name)) ?? "";
@@ -2054,6 +2222,7 @@ const FAKE_CTX = {
     startService: startRuntimeService,
     stopService: stopRuntimeService,
     dnsName: registerDnsName,
+    certificate: mintCertificate,
 };
 /** Build (or fetch from cache) the helpers record for a fake — the
  * value that ends up at `ctx.fakes.<name>`. Defaults to `{}` (a fake
@@ -2184,6 +2353,18 @@ function logBootstrapTimings(t) {
     console.log(`[bootstrap] total ${t.totalMs}ms across ${t.services.length} service(s)`);
 }
 async function bootstrap() {
+    // Tee everything this bootstrap logs — ours and every service `setup`
+    // hook's — into the boot log, so GET /boot-log can explain a slow or
+    // finished boot. Restored in the finally at the end.
+    const restoreBootLog = captureConsole(BOOT_LOG_SINK);
+    try {
+        return await bootstrapInner();
+    }
+    finally {
+        restoreBootLog();
+    }
+}
+async function bootstrapInner() {
     const bootStart = Date.now();
     const cfg = requireLoaded().project.environment;
     const services = namedServices(cfg);
@@ -2201,6 +2382,18 @@ async function bootstrap() {
         ensureNetwork(),
         (async () => {
             await fs.mkdir(WORKSPACE, { recursive: true });
+            // Read the project's own .dockerignore BEFORE we consider writing
+            // one — every per-service ignore composes on top of it.
+            PROJECT_DOCKERIGNORE = await readProjectDockerignore();
+            if (PROJECT_DOCKERIGNORE !== null) {
+                console.log("[bootstrap] using the project's .dockerignore for every build context");
+                // Never overwrite it. BuildKit reads the per-service
+                // `<Dockerfile>.dockerignore` (which already folds this file in),
+                // and the legacy builder reads the project's file directly —
+                // which is what the project asked for. Clobbering it also broke
+                // any in-env tooling that reads it.
+                return;
+            }
             await fs.writeFile(path.join(WORKSPACE, ".dockerignore"), unionDockerignore(services));
         })(),
     ]);
@@ -2283,7 +2476,11 @@ async function bootstrap() {
         // deps; this adds the image edge. The two compose: we run the moment
         // both are satisfied, with no whole-graph barrier between them.
         await prep.get(svc.name);
-        const flags = [...(await ensureVolumes(svc)), ...(await ensureFiles(svc))];
+        const flags = [
+            ...(await ensureVolumes(svc)),
+            ...(await ensureFiles(svc)),
+            ...(await ensureCertificates(svc)),
+        ];
         const tag = tags.get(svc.name);
         if (!tag)
             throw new Error(`internal: no image tag for ${svc.name}`);
@@ -2351,6 +2548,17 @@ async function bootstrap() {
  * env bring-up; the control plane surfaces them as a start failure.
  */
 async function runProjectSetup() {
+    // Same tee as bootstrap: a project `setup` hook's console output is
+    // part of explaining the boot, not something to lose on success.
+    const restoreBootLog = captureConsole(BOOT_LOG_SINK);
+    try {
+        return await runProjectSetupInner();
+    }
+    finally {
+        restoreBootLog();
+    }
+}
+async function runProjectSetupInner() {
     const proj = requireLoaded().project;
     if (!proj.setup)
         return { ran: false, durationMs: 0 };
@@ -2370,6 +2578,7 @@ async function runProjectSetup() {
         svc,
         fakes,
         dnsName: registerDnsName,
+        certificate: mintCertificate,
         startService: startRuntimeService,
         stopService: stopRuntimeService,
     };
@@ -2717,6 +2926,7 @@ const EXEC_FRAME_CAP_BYTES = 1024 * 1024;
  * `opts.env`.
  */
 async function openInstrumentedTerminal(service, opts, testStart, sessions, recordEvents, idScope) {
+    assertKnownOpts("ctx.terminal", opts, TERMINAL_OPT_KEYS);
     const cols = opts?.cols ?? 80;
     const rows = opts?.rows ?? 24;
     const session = newTerminalSession(testStart, service, opts?.command ?? "(interactive)", cols, rows, idScope);
@@ -2750,6 +2960,7 @@ const COMPONENT_EXEC_DEFAULT_TIMEOUT_MS = 120_000;
  * `exitCode`, never thrown. Unlike `execInService` this records nothing —
  * setup/helpers-factory time has no test timeline. */
 function componentExec(service, command, opts) {
+    assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
     const argv = ["exec", "-i"];
     if (opts?.cwd)
         argv.push("-w", opts.cwd);
@@ -2767,21 +2978,30 @@ function componentExec(service, command, opts) {
         const err = [];
         child.stdout.on("data", (c) => out.push(c));
         child.stderr.on("data", (c) => err.push(c));
-        const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutMs);
         child.on("error", (e) => {
             clearTimeout(timer);
             reject(e);
         });
         child.on("close", (code) => {
             clearTimeout(timer);
+            // A SIGKILL'd child reports 137, which reads like an OOM kill.
+            // Report the `timeout(1)` convention plus a note instead, so a
+            // wedged command is diagnosable from the result alone.
+            const stderrText = Buffer.concat(err).toString("utf8");
             resolve({
                 stdout: Buffer.concat(out).toString("utf8"),
-                stderr: Buffer.concat(err).toString("utf8"),
-                exitCode: code ?? -1,
+                stderr: timedOut
+                    ? `${stderrText}\ntimeout after ${timeoutMs}ms`
+                    : stderrText,
+                exitCode: timedOut ? EXEC_TIMEOUT_EXIT_CODE : (code ?? -1),
             });
         });
-        if (opts?.stdin !== undefined)
-            child.stdin.end(opts.stdin);
+        feedStdin(child, opts?.stdin);
     });
 }
 function componentContext() {
@@ -2933,18 +3153,68 @@ function installFetchWrapper() {
 /** Build the `docker exec` argv for a service command. An optional `cwd`
  *  becomes `-w <cwd>` (the working-directory option of `ctx.exec`), so the
  *  command runs from that directory without it being baked into the command
- *  string. Used by both the buffered and streaming variants so they stay in
- *  lockstep. */
-function dockerExecArgs(service, command, cwd) {
+ *  string. `-i` is passed whenever stdin will be piped — without it docker
+ *  attaches no stdin and the payload is silently discarded. Used by both the
+ *  buffered and streaming variants so they stay in lockstep. */
+function dockerExecArgs(service, command, opts) {
     const args = ["exec"];
-    if (cwd)
-        args.push("-w", cwd);
+    if (opts?.stdin !== undefined)
+        args.push("-i");
+    if (opts?.cwd)
+        args.push("-w", opts.cwd);
     args.push(service, "sh", "-lc", command);
     return args;
 }
-function execInService(service, command, cwd) {
+/** Exit code reported when an exec is killed by its own `timeoutMs`
+ *  (the `timeout(1)` convention, matching `shx`). */
+const EXEC_TIMEOUT_EXIT_CODE = 124;
+/**
+ * Reject option objects carrying properties we don't implement, instead
+ * of ignoring them. TypeScript's excess-property check already flags
+ * these on an object literal, but `spectest test`'s typecheck is
+ * advisory and never gates a run — so a typo'd or unsupported option
+ * (`{ stdin }` before it was supported, `{ timeout }` for `timeoutMs`)
+ * would otherwise vanish without a trace and surface much later as
+ * "the command got no input".
+ */
+function assertKnownOpts(fnLabel, opts, allowed) {
+    if (!opts || typeof opts !== "object")
+        return;
+    const unknown = Object.keys(opts).filter((k) => !allowed.includes(k));
+    if (unknown.length === 0)
+        return;
+    throw new Error(`${fnLabel}: unsupported option${unknown.length > 1 ? "s" : ""} ` +
+        `${unknown.map((k) => JSON.stringify(k)).join(", ")} — supported: ` +
+        `${allowed.map((k) => JSON.stringify(k)).join(", ")}`);
+}
+const EXEC_OPT_KEYS = ["cwd", "stdin", "timeoutMs"];
+const TERMINAL_OPT_KEYS = ["cols", "rows", "env", "command", "timeoutMs"];
+const POLL_OPT_KEYS = ["timeoutMs", "intervalMs"];
+/** Write `stdin` to the child and close the stream. A command that never
+ *  reads stdin makes the write fail with EPIPE — harmless, and it must not
+ *  take down the daemon as an unhandled 'error' event. */
+function feedStdin(child, stdin) {
+    if (stdin === undefined)
+        return;
+    const s = child.stdin;
+    if (!s)
+        return;
+    s.on("error", () => { });
+    s.end(stdin);
+}
+function execInService(service, command, opts) {
     return new Promise((resolve) => {
-        execFile("docker", dockerExecArgs(service, command, cwd), { maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const child = execFile("docker", dockerExecArgs(service, command, opts), { maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+            if (timer)
+                clearTimeout(timer);
+            if (timedOut) {
+                resolve({
+                    stdout: stdout.toString(),
+                    stderr: `${stderr.toString()}\ntimeout after ${opts.timeoutMs}ms`,
+                    exitCode: EXEC_TIMEOUT_EXIT_CODE,
+                });
+                return;
+            }
             const exitCode = err && typeof err.code === "number"
                 ? Number(err.code)
                 : err
@@ -2956,6 +3226,14 @@ function execInService(service, command, cwd) {
                 exitCode,
             });
         });
+        let timedOut = false;
+        const timer = opts?.timeoutMs && opts.timeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }, opts.timeoutMs)
+            : undefined;
+        feedStdin(child, opts?.stdin);
     });
 }
 /** `execInService` for the no-recorder contexts (`setup`/`eval`): wraps the
@@ -2963,7 +3241,8 @@ function execInService(service, command, cwd) {
  *  honest at runtime, but with no provenance (there's no event to link to).
  *  The recorded `ctx.exec` used during tests is `recordedExec` below. */
 async function execInServiceWrapped(service, command, opts) {
-    const res = await execInService(service, command, opts?.cwd);
+    assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
+    const res = await execInService(service, command, opts);
     return wrap(res, undefined);
 }
 /** Per-stream cap on the ExecResult strings the streaming variant
@@ -2984,10 +3263,10 @@ const EXEC_RESULT_CAP_BYTES = 16 * 1024 * 1024;
  * analogue of what a terminal would have shown — while the returned
  * `ExecResult` keeps them separate as before.
  */
-function execInServiceStreaming(service, command, onChunk, cwd) {
+function execInServiceStreaming(service, command, onChunk, opts) {
     return new Promise((resolve) => {
-        const child = spawn("docker", dockerExecArgs(service, command, cwd), {
-            stdio: ["ignore", "pipe", "pipe"],
+        const child = spawn("docker", dockerExecArgs(service, command, opts), {
+            stdio: [opts?.stdin !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
         });
         const acc = { stdout: "", stderr: "" };
         const decoders = {
@@ -3012,21 +3291,41 @@ function execInServiceStreaming(service, command, onChunk, cwd) {
         child.stdout?.on("data", (c) => drain("stdout", c));
         child.stderr?.on("data", (c) => drain("stderr", c));
         let settled = false;
+        let timedOut = false;
         const finish = (exitCode) => {
             if (settled)
                 return;
             settled = true;
+            if (timer)
+                clearTimeout(timer);
             // Flush any multi-byte tail the decoders are still holding.
             acc.stdout += decoders.stdout.decode();
             acc.stderr += decoders.stderr.decode();
-            resolve({ stdout: acc.stdout, stderr: acc.stderr, exitCode });
+            if (timedOut) {
+                const note = `\ntimeout after ${opts.timeoutMs}ms`;
+                acc.stderr += note;
+                onChunk("stderr", note);
+            }
+            resolve({
+                stdout: acc.stdout,
+                stderr: acc.stderr,
+                exitCode: timedOut ? EXEC_TIMEOUT_EXIT_CODE : exitCode,
+            });
         };
+        const timer = opts?.timeoutMs && opts.timeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }, opts.timeoutMs)
+            : undefined;
         // `close` (not `exit`) so both pipes are fully drained first.
         child.on("close", (code) => finish(code ?? 1));
         child.on("error", () => finish(1));
+        feedStdin(child, opts?.stdin);
     });
 }
 async function pollCall(description, fn, opts) {
+    assertKnownOpts("ctx.poll", opts, POLL_OPT_KEYS);
     const timeoutMs = opts?.timeoutMs ?? 30_000;
     const intervalMs = opts?.intervalMs ?? 1_000;
     const start = Date.now();
@@ -3096,14 +3395,6 @@ async function pollCall(description, fn, opts) {
     }
     throw new Error(`poll ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`);
 }
-/**
- * Tee `console.*` output into `chunks` for the duration of a test/eval.
- * Bun's console writes through its own native sink, NOT
- * `process.stdout.write`, so patching the streams alone misses every
- * `console.log` the test makes — the captured `log` came back empty.
- * The original method still runs, so the daemon journal keeps the line.
- * Returns a restore function for the caller's `finally`.
- */
 function captureConsole(chunks) {
     const methods = ["log", "info", "warn", "error", "debug"];
     const orig = new Map();
@@ -3161,6 +3452,7 @@ async function runOne(testCase) {
     // frames are presentation-only; the ExecResult (and any assertions on
     // it) still sees the plain separated stdout/stderr.
     const recordedExec = async (service, command, opts) => {
+        assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
         const t = Date.now();
         const cwd = opts?.cwd;
         const resv = reserveEvent();
@@ -3190,14 +3482,21 @@ async function runOne(testCase) {
             // `\r\n` too keeps a CR|LF split across chunk boundaries
             // harmless (`\r\r\n` renders identically).
             session.pushFrame((Date.now() - t) / 1000, data.replace(/\r?\n/g, "\r\n"));
-        }, cwd);
+        }, opts);
         session.markClosed();
         const stdout = truncateUtf8(res.stdout);
         const stderr = truncateUtf8(res.stderr);
+        // The piped payload is never echoed by the process, so the asciicast
+        // can't show it — carry it on the event instead (truncated like the
+        // output streams) so the timeline shows what the command was fed.
+        const stdin = opts?.stdin !== undefined ? truncateUtf8(opts.stdin) : undefined;
         const seq = recordExec({
             service,
             command,
             cwd,
+            ...(stdin
+                ? { stdin: stdin.value, stdinTruncated: stdin.truncated }
+                : {}),
             exitCode: res.exitCode,
             stdout: stdout.value,
             stdoutTruncated: stdout.truncated,
@@ -3380,6 +3679,7 @@ async function runOne(testCase) {
         fakes,
         poll: pollCall,
         dnsName: registerDnsName,
+        certificate: mintCertificate,
         startService: startRuntimeService,
         stopService: stopRuntimeService,
     };
@@ -3549,6 +3849,55 @@ async function ensureDeps(code) {
     });
     return missing;
 }
+/**
+ * Turn the bare parser error an `export default` misuse produces
+ * ("Unexpected export") into something actionable.
+ *
+ * An eval snippet is imported as a **real ESM module**, so `export
+ * default` is a module-level declaration: there can be exactly one, and
+ * it cannot sit inside an `if`/`try`/loop body. Early-return style —
+ * `if (!x) { out.y = z; export default out; }` — is therefore a syntax
+ * error, and the raw message says nothing about why or what to do.
+ *
+ * We only ever *augment* a message that already failed, and only when
+ * the snippet actually uses `export default`, so a genuine unrelated
+ * syntax error keeps its own text.
+ */
+function explainEvalExportError(code, message) {
+    if (!/unexpected export|export declarations?|'export'|"export"/i.test(message)) {
+        return message;
+    }
+    // Not line-anchored: the early-return idiom this exists to explain puts
+    // the offending export mid-line (`if (!x) { …; export default out; }`),
+    // which an `^`-anchored match would miss entirely.
+    const matches = [...code.matchAll(/\bexport\s+default\s/g)];
+    if (matches.length === 0)
+        return message;
+    // Anything but whitespace before it on its own line means it's nested in
+    // a block or statement rather than declared at the top level.
+    const nested = matches.some((m) => {
+        const lineStart = code.lastIndexOf("\n", m.index) + 1;
+        return code.slice(lineStart, m.index).trim().length > 0;
+    });
+    const counted = matches.length > 1
+        ? `this snippet has ${matches.length} \`export default\` statements, but a module may only have one`
+        : null;
+    const placed = nested
+        ? "`export default` appears inside a block (`if`/`try`/loop), where a module-level declaration isn't allowed"
+        : null;
+    const reason = counted && placed
+        ? `${counted}, and ${placed}`
+        : (counted ?? placed ?? "`export default` isn't at the module's top level");
+    return (`${message}\n\n` +
+        `spectest: an eval snippet is imported as a real ES module, and ${reason}. ` +
+        "For early-return style, compute the value in a function and export its result once:\n\n" +
+        "  export default await (async () => {\n" +
+        "    const out = {};\n" +
+        "    if (!x) return { ...out, y: z };   // early return, not early export\n" +
+        "    out.more = await ctx.exec(\"web\", \"…\");\n" +
+        "    return out;\n" +
+        "  })();\n");
+}
 async function evalCode(code, secrets) {
     const start = Date.now();
     // Eval-scoped secret channel for record-mode fakes — set before the
@@ -3688,6 +4037,7 @@ async function evalCode(code, secrets) {
         fakes,
         poll: pollCall,
         dnsName: registerDnsName,
+        certificate: mintCertificate,
         startService: startRuntimeService,
         stopService: stopRuntimeService,
     };
@@ -3715,9 +4065,10 @@ async function evalCode(code, secrets) {
     }
     catch (err) {
         const e = err;
+        const message = e.message ?? String(err);
         outcome = {
             ok: false,
-            error: { message: e.message ?? String(err), stack: e.stack },
+            error: { message: explainEvalExportError(code, message), stack: e.stack },
         };
     }
     finally {
@@ -3951,6 +4302,43 @@ async function handle(req, res, state) {
         jsonResponse(res, 200, BOOTSTRAP_PROGRESS ?? {});
         return;
     }
+    if (method === "GET" && url.startsWith("/env-logs")) {
+        // Live logs for a running environment: the daemon's own boot log
+        // (bootstrap + every `setup` hook's console output) plus each
+        // service's container logs. Unlike the per-case deltas this reads
+        // without touching LOG_MARKERS, so calling it never perturbs a run.
+        const q = new URL(url, "http://daemon").searchParams;
+        const only = q.get("service") ?? undefined;
+        const tail = Math.max(1, Math.min(10_000, Number(q.get("tail") ?? "200") || 200));
+        const l = loaded;
+        const byName = new Map();
+        if (l)
+            for (const s of namedServices(l.project.environment))
+                byName.set(s.name, s);
+        for (const [name, s] of RUNTIME_SERVICES)
+            byName.set(name, s);
+        const names = [...byName.keys()].filter((n) => !only || n === only);
+        if (only && names.length === 0) {
+            jsonResponse(res, 404, {
+                error: `unknown service ${JSON.stringify(only)}; known: ${[...byName.keys()].join(", ") || "(none)"}`,
+            });
+            return;
+        }
+        const services = await Promise.all(names.map(async (name) => {
+            const r = await docker(["logs", "--timestamps", `--tail=${tail}`, name], 30_000);
+            const out = capMiddle(r.stdout, LOG_DELTA_MAX_BYTES);
+            const err = capMiddle(r.code === 0 ? r.stderr : r.stderr || r.stdout, LOG_DELTA_MAX_BYTES);
+            return {
+                service: name,
+                stdout: out.value,
+                stdoutTruncated: out.truncated,
+                stderr: err.value,
+                stderrTruncated: err.truncated,
+            };
+        }));
+        jsonResponse(res, 200, { bootLog: bootLogText(), services });
+        return;
+    }
     if (method === "POST" && url === "/load") {
         // Env only — services/fakes/setup. For the legacy single-file layout the
         // entry also defines the tests, so `cases` is populated here; for the

package/dist/index.d.ts

@@ -104,6 +104,42 @@ export interface ServiceConfig {
      * `k3s server` starts.
      */
     files?: readonly FileMount[];
+    /**
+     * Leaf certificates minted from the in-VM root CA and written into the
+     * container **before it starts**, so the service can terminate TLS
+     * *itself* with a certificate the whole environment already trusts.
+     *
+     * This is the counterpart to {@link ServiceConfig.tls}. `tls` puts the
+     * daemon in front as a terminating reverse proxy and forwards plain
+     * HTTP to the service — right for an ordinary web app, wrong for
+     * anything that has to see the TLS handshake: a gateway that routes by
+     * SNI, a server that verifies client certificates, or a protocol with
+     * its own TLS layer. Those need key material, and the only alternative
+     * was a self-signed cert plus `rejectUnauthorized: false` — which
+     * tests a code path production never runs.
+     *
+     * ```ts
+     * services: {
+     *   gateway: {
+     *     image: { type: "registry", reference: "…" },
+     *     hostnames: ["sql.gateway.test"],
+     *     certificates: [{
+     *       hostnames: ["sql.gateway.test", "*.sql.gateway.test"],
+     *       certPath: "/tls/tls.crt",
+     *       keyPath: "/tls/tls.key",
+     *       mode: "0600",
+     *     }],
+     *   },
+     * }
+     * // a test then connects with full verification on:
+     * //   new Client({ connectionString, ssl: { rejectUnauthorized: true } })
+     * ```
+     *
+     * For a certificate a *test* needs as a value — to load into a
+     * Kubernetes Secret, say — use `ctx.certificate(hostnames)` instead,
+     * which returns the PEMs rather than mounting them.
+     */
+    certificates?: readonly CertificateMount[];
     /** Other services (keys in the services map) that must be ready first. */
     dependsOn?: readonly string[];
     readyCheck?: ReadyCheck;
@@ -159,15 +195,19 @@ export interface ComponentContext {
      */
     exec(service: string, command: string | string[], opts?: ComponentExecOpts): Promise<ExecResult>;
 }
-/** Options for {@link ComponentContext.exec}. */
-export interface ComponentExecOpts {
-    /** Piped to the command's stdin, then closed. */
-    stdin?: string;
-    /** Working directory inside the container (`docker exec -w`). */
-    cwd?: string;
-    /** Kill the exec after this long. Default 120_000. */
-    timeoutMs?: number;
-}
+/**
+ * Options for {@link ComponentContext.exec} — the same set
+ * {@link TestContext.exec} takes, deliberately aliased rather than
+ * redeclared: the two surfaces drifted once (the component one grew
+ * `stdin`/`timeoutMs`, the test one silently ignored them), and an alias
+ * makes that impossible to repeat.
+ *
+ * The one behavioural difference is the `timeoutMs` default: a component
+ * exec runs during boot, where nothing else bounds it, so it defaults to
+ * 120 s. A test-context exec has no default — the enclosing test's own
+ * timeout is the ceiling there.
+ */
+export type ComponentExecOpts = ExecOpts;
 /** What a service's `setup` hook receives. */
 export interface ServiceSetupContext<H extends Record<string, any> = Record<string, never>> extends ComponentContext {
     /** The service's key in the services map (container + DNS name). */
@@ -432,6 +472,38 @@ export interface FileMount {
      */
     mode?: string;
 }
+/** PEM material returned by `ctx.certificate(hostnames)`. */
+export interface CertificateMaterial {
+    /** PEM certificate, signed by the in-VM root CA. */
+    cert: string;
+    /** PEM private key for {@link cert}. */
+    key: string;
+    /** PEM root CA certificate — the one the environment already trusts. */
+    ca: string;
+}
+/** One leaf certificate materialized into a service container — see
+ *  {@link ServiceConfig.certificates}. */
+export interface CertificateMount {
+    /** SANs the leaf covers. Wildcards (`*.example.com`) are allowed. */
+    hostnames: readonly string[];
+    /** Absolute path inside the container for the PEM certificate. */
+    certPath: string;
+    /** Absolute path inside the container for the PEM private key. */
+    keyPath: string;
+    /**
+     * Optional absolute path for the root CA certificate. Every container
+     * already trusts the CA (`SSL_CERT_FILE` and friends are pre-set), so
+     * this is only for software that wants an explicit CA file — client
+     * certificate verification, a `sslrootcert=` connection parameter.
+     */
+    caPath?: string;
+    /**
+     * Optional octal mode (e.g. `"0600"`) applied to the staged key.
+     * Servers that refuse a group/world-readable key (postgres, ssh) need
+     * this; the default is the writer's umask.
+     */
+    mode?: string;
+}
 export type ReadyCheck = {
     type: "tcp";
     port: number;
@@ -524,6 +596,10 @@ export interface FakeContext {
     /** Map a DNS name onto a service IP (or the daemon ingress). See
      *  {@link TestContext.dnsName}. */
     dnsName(hostname: string, target: DnsTarget): Promise<void>;
+    /** Mint a CA-signed leaf certificate. See
+     *  {@link TestContext.certificate} — the primitive a fake standing in
+     *  for a TLS-provisioning provider hands back to the app under test. */
+    certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
 }
 /**
  * A single test step. Created via `test(...)` or `createTest(services)`.
@@ -536,7 +612,7 @@ export interface FakeContext {
  * is strongly typed.
  */
 export interface TestCase<T = unknown, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
-    /** Stable id (slug of name). Used in MCP responses and CLI flags. */
+    /** Stable id (slug of name). Used in run results and CLI flags. */
     readonly id: string;
     readonly name: string;
     /** Parent test, if any. Single-parent for now. */
@@ -750,6 +826,38 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      * ```
      */
     dnsName(hostname: string, target: DnsTarget): Promise<void>;
+    /**
+     * Mint a leaf certificate from the in-VM root CA and return the PEMs.
+     *
+     * The value-returning counterpart to the `certificates` service field
+     * (see {@link ServiceConfig.certificates}): that one hands a
+     * certificate to a container before it boots, this one hands it to
+     * *you* — for loading into a Kubernetes `kubernetes.io/tls` Secret,
+     * posting to a control-plane API that provisions TLS endpoints, or
+     * driving a client-certificate handshake.
+     *
+     * The returned `ca` is the same root the whole environment already
+     * trusts (`ctx.fetch`, `ctx.browser()`, every service container), so a
+     * server configured with these PEMs verifies cleanly — no
+     * `rejectUnauthorized: false`, no `sslmode=require` downgrade.
+     * Wildcards (`*.example.com`) are allowed in `hostnames`.
+     *
+     * ```ts
+     * const { cert, key } = await ctx.certificate(["*.apps.test"]);
+     * await ctx.svc.k8s.apply(`
+     * apiVersion: v1
+     * kind: Secret
+     * metadata: { name: apps-tls, namespace: default }
+     * type: kubernetes.io/tls
+     * stringData:
+     *   tls.crt: |
+     * ${cert.replace(/^/gm, "    ")}
+     *   tls.key: |
+     * ${key.replace(/^/gm, "    ")}
+     * `);
+     * ```
+     */
+    certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
     /**
      * Start a real container on `spectest-net` at runtime — a peer machine
      * with its own IP, reachable like any boot service. Returns once the
@@ -785,7 +893,11 @@ export interface ExecResult {
     stderr: string;
     exitCode: number;
 }
-/** Options for {@link TestContext.exec}. */
+/** Options for {@link TestContext.exec}.
+ *
+ * Unknown properties are rejected at runtime (`ctx.exec` throws), not
+ * silently ignored — the type-level excess-property check is advisory
+ * here, since `spectest test`'s typecheck never gates a run. */
 export interface ExecOpts {
     /**
      * Working directory inside the container to run the command from.
@@ -797,6 +909,32 @@ export interface ExecOpts {
      * -w <cwd>`, so a relative path resolves against the image's WORKDIR.
      */
     cwd?: string;
+    /**
+     * Piped to the command's stdin, then closed — the natural way to feed
+     * a manifest to `kubectl apply -f -` or a SQL file to `psql -f -`
+     * without staging a temp file in the container:
+     *
+     * ```ts
+     * await ctx.exec("k8s", "kubectl apply -f -", { stdin: manifestYaml });
+     * ```
+     *
+     * The payload is written after the process starts and the stream is
+     * closed immediately after, so a command that never reads stdin still
+     * exits normally (the write is allowed to fail with EPIPE).
+     */
+    stdin?: string;
+    /**
+     * Kill the command (SIGKILL) after this long and return `exitCode`
+     * 124 with a `timeout after <n>ms` note on stderr, rather than
+     * hanging until the enclosing test's own timeout fires.
+     *
+     * **There is no default** — an `exec` runs as long as it likes. In a
+     * test the enclosing `env.test(..., { timeoutMs })` (60 s by default)
+     * is the real ceiling; in `setup`/`eval`, where no test timeout
+     * applies, an unbounded command hangs the boot, so set this when the
+     * command can plausibly wedge.
+     */
+    timeoutMs?: number;
 }
 export interface TestSuite<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
     tests: TestCase<unknown, S, F>[];
@@ -983,6 +1121,13 @@ export interface ProjectSetupContext<S extends ServicesMap = ServicesMap, F exte
      * test inherits the route without re-registering.
      */
     dnsName(hostname: string, target: DnsTarget): Promise<void>;
+    /**
+     * Mint a leaf certificate from the in-VM root CA (see
+     * {@link TestContext.certificate}). Minted here it's captured into the
+     * warm-template snapshot, so every test inherits whatever you seeded it
+     * into — the fit for a cluster-wide TLS Secret applied once at setup.
+     */
+    certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
     /**
      * Start a runtime service (see {@link TestContext.startService}). Started
      * here, it's captured into the warm-template snapshot and inherited by

package/dist/recorder.d.ts

@@ -26,6 +26,15 @@ export interface ExecEvent extends BaseEvent {
      * detail view surfaces it. Absent when the call used no `cwd`.
      */
     cwd?: string;
+    /**
+     * The payload piped to the command's stdin (`ctx.exec(svc, cmd, {
+     * stdin })`), truncated to OUTPUT_SNIPPET_BYTES. Recorded because the
+     * asciicast only captures what the command *wrote* — without this, a
+     * `kubectl apply -f -` step shows its error but not the manifest that
+     * caused it. Absent when the call piped nothing.
+     */
+    stdin?: string;
+    stdinTruncated?: boolean;
     exitCode: number;
     /** stdout truncated to OUTPUT_SNIPPET_BYTES. */
     stdout: string;
@@ -316,7 +325,9 @@ export interface EmailEvent extends BaseEvent {
 export interface EnvEvent extends BaseEvent {
     kind: "env";
     /** Which environment primitive ran. */
-    op: "startService" | "stopService" | "dnsName";
+    op: "startService" | "stopService" | "dnsName" | "certificate";
+    /** SANs of a minted leaf (certificate). */
+    hostnames?: string[];
     /** Service name (startService / stopService). */
     service?: string;
     /** Image reference started (startService). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",