@specific.dev/spectest 0.28.0 → 0.28.2

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.js

@@ -595,10 +595,9 @@ const ZOT_MIRRORS = [
 /**
  * Discover the host-side image cache gateway by reading the same
  * `registry-mirrors` entry the in-VM dockerd already uses (baked into
- * the local provider's golden `/etc/docker/daemon.json`). Returns the
+ * the golden rootfs's `/etc/docker/daemon.json`). Returns the
  * gateway host (`"10.42.0.1"`) when present, or `null` when there's no
- * host cache — e.g. on Freestyle, where the cluster then pulls every
- * image direct. Runs inside the daemon (VM) at `index.ts` load time, so
+ * host cache, in which case the cluster pulls every image direct. Runs inside the daemon (VM) at `index.ts` load time, so
  * the result is stable per host and never poisons the warm-template
  * cache.
  */
@@ -618,7 +617,7 @@ function detectHostMirrorGateway() {
  * to be seeded via `files` (a pre-start bind mount) rather than a
  * `setup` hook. Two jobs:
  *   1. Mirror the cluster's image pulls through the host `zot` cache
- *      (local provider only; omitted when there's no host cache).
+ *      (omitted when there's no host cache).
  *   2. Trust the in-cluster registry, addressed as `<key>.internal:5000`
  *      (the `{{SPECTEST_SERVICE}}` token is expanded to the cluster's
  *      service key when the file is written). Image *references* use
@@ -872,30 +871,18 @@ async function collectTraefikDiagnostics(helpers) {
  * the k3s container's IP (via systest-resolver), lands on Traefik,
  * and gets dispatched to the matching Ingress rule's backend pods.
  *
- * **Workarounds for Freestyle's kernel** (Linux 6.1.0-x-freestyle).
- * The stock kernel is missing the `xt_comment` netfilter match
- * extension. Two consequences, each handled below:
+ * **kube-proxy runs in `nftables` mode** (`--kube-proxy-arg=proxy-mode
+ * =nftables`), not the iptables default. This started as a workaround
+ * for a stock kernel with no `xt_comment` match — kube-proxy's iptables
+ * rules carry `-m comment`, and the kernel rejected every one of them,
+ * breaking pod→ClusterIP routing and any pod talking to the in-cluster
+ * API (helm-install Jobs, CoreDNS, …). We build the guest kernel
+ * ourselves now and it has the match, but nftables mode is the better
+ * path regardless, so it stays. It is GA in k8s 1.32, which is what
+ * pins `DEFAULT_K3S_VERSION`.
  *
- *   1. *kube-proxy* in default iptables mode generates rules with
- *      `-m comment --comment "..."`, which the kernel rejects —
- *      breaking pod→ClusterIP routing and every pod that talks to the
- *      in-cluster API (helm-install Jobs, CoreDNS, …). Fixed by
- *      `--kube-proxy-arg=proxy-mode=nftables`: kube-proxy emits
- *      native nftables rules where comments are a first-class
- *      construct, no xt_comment dependency. nftables proxy mode is
- *      GA in k8s 1.32, which is why we pin that.
- *
- *   2. *CNI portmap plugin* (used by klipper-lb's hostPort to expose
- *      LoadBalancer ports on the host) still uses iptables-nft and
- *      hits the same xt_comment failure — there's no equivalent
- *      flag to switch it to native nftables. Workaround: disable the
- *      bundled traefik + ServiceLB and run Traefik with
- *      `hostNetwork: true` ourselves. hostNetwork pods don't go
- *      through portmap at all (they share the node's netns directly),
- *      so the broken plugin is never invoked.
- *
- * Flannel uses the `host-gw` backend because Freestyle's stock kernel
- * lacks the VXLAN module — fine for single-node clusters.
+ * Flannel uses the `host-gw` backend: single-node clusters never route
+ * pod traffic off the node, so VXLAN encapsulation is pure overhead.
  */
 /**
  * Default k3s docker image tag.
@@ -912,8 +899,7 @@ async function collectTraefikDiagnostics(helpers) {
  *
  * **Why v1.32.x:** kube-proxy's `nftables` proxy mode is GA in k8s 1.32
  * (beta in 1.31, alpha-gated in 1.30). The component runs kube-proxy in
- * this mode to sidestep Freestyle's missing `xt_comment` netfilter
- * extension; dropping below 1.31 reintroduces the broken iptables path.
+ * that mode; dropping below 1.31 falls back to the iptables path.
  */
 const DEFAULT_K3S_VERSION = "v1.32.1-k3s1";
 export function k3s(opts = {}) {
@@ -960,7 +946,7 @@ export function k3s(opts = {}) {
         // 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
+        // match — absent from the stock kernel we used to run on, 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

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

@@ -68,6 +68,17 @@ const APP_DIR = process.env.SPECTEST_APP_DIR ?? "/opt/spectest/app";
 // referenced when we layer it into each image's system trust store.
 const CA_PATH = process.env.SPECTEST_CA_PATH ?? "/etc/spectest/ca.crt";
 const CA_KEY_PATH = process.env.SPECTEST_CA_KEY_PATH ?? "/etc/spectest/ca.key";
+// Public roots ⧺ the spectest CA, materialized by `ensureCaBundle` and
+// bind-mounted into every container. `SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`/
+// `AWS_CA_BUNDLE` REPLACE the trust store rather than adding to it, so
+// pointing them at the bare CA leaves a container able to verify our fakes
+// and nothing else — public HTTPS then fails to verify from anything using
+// OpenSSL, Python requests, or an AWS SDK. (`NODE_EXTRA_CA_CERTS` appends,
+// which is why Node services never saw this.)
+const CA_BUNDLE_PATH = process.env.SPECTEST_CA_BUNDLE_PATH ?? "/etc/spectest/ca-bundle.crt";
+// The guest's own trust store. BASE_SETUP_SH runs `update-ca-certificates`
+// after generating the CA, so this normally already carries both halves.
+const SYSTEM_CA_BUNDLE = process.env.SPECTEST_SYSTEM_CA_BUNDLE ?? "/etc/ssl/certs/ca-certificates.crt";
 let loaded = null;
 function casesMetadata(suite) {
     if (!suite)
@@ -902,6 +913,46 @@ RUN if command -v update-ca-certificates >/dev/null 2>&1; then \\
         console.warn(`[ca-trust] could not layer spectest CA into ${serviceName} (${tag}); env-var fallback only:\n${build.stderr.trim() || build.stdout.trim()}`);
     }
 }
+/** Memoized across containers — the CA never rotates within a VM's life. */
+let caBundlePromise = null;
+/**
+ * Materialize {@link CA_BUNDLE_PATH} (public roots ⧺ the spectest CA) and
+ * return its path, or null when there's no CA to trust (daemon running
+ * outside a base-snapshot VM).
+ *
+ * This is what the replace-semantics trust env vars must point at. Falling
+ * back to the bare CA when the guest bundle is unreadable keeps the old
+ * behaviour — fakes verify, public HTTPS doesn't — which is strictly better
+ * than dropping the CA and breaking the fakes everything else depends on.
+ */
+async function ensureCaBundle() {
+    caBundlePromise ??= (async () => {
+        if (!existsSync(CA_PATH))
+            return null;
+        const ca = await fs.readFile(CA_PATH, "utf8");
+        let system = "";
+        try {
+            system = await fs.readFile(SYSTEM_CA_BUNDLE, "utf8");
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[ca-trust] no system CA bundle at ${SYSTEM_CA_BUNDLE} (${err}); containers will trust the spectest CA only`);
+            return CA_PATH;
+        }
+        // update-ca-certificates already folds our CA into the system bundle;
+        // appending again is harmless but pointless.
+        const parts = system.includes(ca.trim()) ? [system] : [system, ca];
+        const bundle = parts.map((p) => p.trimEnd()).join("\n") + "\n";
+        await fs.writeFile(CA_BUNDLE_PATH, bundle);
+        await fs.chmod(CA_BUNDLE_PATH, 0o644);
+        return CA_BUNDLE_PATH;
+    })().catch((err) => {
+        // eslint-disable-next-line no-console
+        console.warn(`[ca-trust] could not write ${CA_BUNDLE_PATH} (${err}); falling back to ${CA_PATH}`);
+        return existsSync(CA_PATH) ? CA_PATH : null;
+    });
+    return caBundlePromise;
+}
 async function runContainer(svc, tag, volumeFlags, 
 // Extra `--network-alias`es beyond the lowered `aliasesByService`. Used by
 // runtime `startService` (whose service isn't in LOWERED) to give the new
@@ -970,10 +1021,18 @@ extraAliases = []) {
     // for images where the layer step couldn't run (no
     // update-ca-certificates).
     args.push(`--volume=${CA_PATH}:${CA_PATH}:ro`);
+    // Appends to the image's roots, so it takes the bare CA.
     args.push("-e", `NODE_EXTRA_CA_CERTS=${CA_PATH}`);
-    args.push("-e", `SSL_CERT_FILE=${CA_PATH}`);
-    args.push("-e", `REQUESTS_CA_BUNDLE=${CA_PATH}`);
-    args.push("-e", `AWS_CA_BUNDLE=${CA_PATH}`);
+    // These three REPLACE the roots — they must get the combined bundle or
+    // the container loses every public CA (see CA_BUNDLE_PATH).
+    const caBundle = await ensureCaBundle();
+    if (caBundle) {
+        if (caBundle !== CA_PATH)
+            args.push(`--volume=${caBundle}:${caBundle}:ro`);
+        args.push("-e", `SSL_CERT_FILE=${caBundle}`);
+        args.push("-e", `REQUESTS_CA_BUNDLE=${caBundle}`);
+        args.push("-e", `AWS_CA_BUNDLE=${caBundle}`);
+    }
     if (svc.env) {
         for (const [k, v] of Object.entries(svc.env)) {
             args.push("-e", `${k}=${v}`);

package/dist/index.d.ts

@@ -612,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. */
@@ -693,9 +693,9 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      * UI the same way a one-shot `terminal(...)` is.
      *
      * Terminals are NOT auto-closed when the test ends. A docker exec
-     * subprocess is cheap to keep alive and Freestyle captures it
-     * cleanly in the snapshot along with the rest of the container, so
-     * leaking the handle past test end is fine. Call `.close()`
+     * subprocess is cheap to keep alive and the VM snapshot captures it
+     * cleanly along with the rest of the container, so leaking the handle
+     * past test end is fine. Call `.close()`
      * explicitly if you want a `close` step in the timeline; otherwise
      * `await term.exited` (after the program self-terminates) is the
      * natural way to assert on the exit code.
@@ -747,7 +747,7 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
     readonly testName: string;
     /**
      * Value returned by the parent test. Carried across the fork in the
-     * daemon's own memory (Freestyle's snapshot is memory + filesystem), so
+     * daemon's own memory (a VM snapshot is memory + filesystem), so
      * any JS value works — including Maps, Sets, class instances, and live
      * connections that survive the fork. `undefined` for root tests or when
      * the parent returned nothing.

package/dist/terminal.js

@@ -24,7 +24,7 @@
 // a PTY for CMD; we set the slave's size with `stty rows R cols C` inside
 // the wrapped command so the container app sees the cols/rows the caller
 // asked for. `script(1)` ships in util-linux which is essential on Debian,
-// so it's present in the Freestyle base image without extra apt deps.
+// so it's present in the base image without extra apt deps.
 import { Terminal as XtermHeadless } from "@xterm/headless";
 import { recordTerminalStep, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";

package/package.json

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