@drip-apex/apex-cli 0.12.0 → 0.12.1

package/README.md

@@ -352,5 +352,29 @@ config-fetch p50/p95 (milliseconds), and inline/cache/network/none counts.
 JSON output includes the API body in the standard envelope and assignment-ready
 percentiles. Fewer than five measured samples have null percentiles. Natural
 loads are shop-wide non-QA loads without forced IDs; a QA-session bucket can
-overlap forced loads. Analytics failures return errors. Preload and anti-flicker
-changes remain under evaluation pending the first report.
+overlap forced loads. Analytics failures return errors. The API position is
+`runtime_inline_no_change`.
+
+The runtime remains unchanged. Natural runtime decides within tens of milliseconds
+of SDK start when config ships inline with the snippet (measured p50 12 ms /
+p95 54 ms on a large storefront). QA previews, screenshot-mode previews and
+cookie-forced sessions take the QA config lane and fetch fresh config over the
+network (measured p50 1.3 s / p95 7 s); they are not representative of launch
+behaviour. URL-forced sessions without a `qa` parameter keep the inline or cached
+config, so these measurements do not describe them. No config preload or
+anti-flicker hold is planned.
+
+### Connection troubleshooting
+
+Connection errors retain the underlying failure. JSON output exposes
+`error.details.reason` and, when available, `error.details.code`; the numeric
+`error.code` remains the CLI exit code.
+
+| Reason | Meaning and usual fix |
+| --- | --- |
+| `dns` | The host could not be resolved. Check `APEX_BASE_URL` (or `DRIP_BASE_URL`), DNS, and whether your sandbox permits network access. |
+| `refused` | The host rejected the connection. Check the base URL, port, and whether the server is running. |
+| `reset` | The connection was interrupted. Check network stability and proxy settings before retrying. |
+| `tls` | Certificate or TLS validation failed. Check expired certificates and your corporate TLS proxy's trusted CA configuration. |
+| `timeout` | The request was aborted or exceeded its deadline. Check server availability and network access. |
+| `unknown` | Another network failure occurred. Use the included cause message to diagnose network or sandbox restrictions. |

package/dist/cli.js

@@ -7112,7 +7112,7 @@ var import_node_os3 = __toESM(require("node:os"));
 // package.json
 var package_default = {
   name: "@drip-apex/apex-cli",
-  version: "0.12.0",
+  version: "0.12.1",
   license: "MIT",
   description: "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   private: false,
@@ -7666,7 +7666,16 @@ function createHttpClient(creds, options) {
     try {
       response = await fetch(`${creds.baseUrl}${path24}`, { method, headers, body: form ? body5 : body5 ? JSON.stringify(body5) : void 0, signal: AbortSignal.timeout(timeoutMs) });
     } catch (error) {
-      return options.onNetworkError({ baseUrl: creds.baseUrl, timeoutMs, cause: error instanceof Error ? error.message : String(error) });
+      const outer = error && typeof error === "object" ? error : void 0;
+      const nested = outer?.cause && typeof outer.cause === "object" ? outer.cause : void 0;
+      return options.onNetworkError({
+        baseUrl: creds.baseUrl,
+        timeoutMs,
+        cause: error instanceof Error ? error.message : String(error),
+        code: typeof nested?.code === "string" ? nested.code : typeof outer?.code === "string" ? outer.code : void 0,
+        name: typeof outer?.name === "string" ? outer.name : void 0,
+        causeMessage: typeof nested?.message === "string" ? nested.message : void 0
+      });
     }
     inspectVersion(response.headers);
     const json = await response.json().catch(() => null);
@@ -7739,10 +7748,42 @@ function sharedClient(creds) {
       transport: testTransport,
       testTransportVersion: () => testTransport ? process.env[["APEX", "CLI", "MOCK", "API", "VERSION"].join("_")] : void 0,
       onNetworkError: (info) => {
+        let url;
+        try {
+          url = new URL(info.baseUrl);
+        } catch {
+        }
+        const host = url?.hostname ?? info.baseUrl;
+        const code = info.code;
+        let reason = "unknown";
+        let message = info.causeMessage ?? info.cause;
+        if (info.name === "TimeoutError" || info.name === "AbortError" || code === "UND_ERR_CONNECT_TIMEOUT") {
+          reason = "timeout";
+          message = `server did not respond within ${info.timeoutMs / 1e3}s`;
+        } else if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+          reason = "dns";
+          message = `could not resolve host ${host}`;
+        } else if (code === "ECONNREFUSED") {
+          reason = "refused";
+          message = `connection refused by ${host}:${url?.port || (url?.protocol === "https:" ? "443" : "80")}`;
+        } else if (code === "ECONNRESET" || code === "EPIPE") {
+          reason = "reset";
+          message = `connection reset by ${host}`;
+        } else if (code?.startsWith("CERT_") || code?.startsWith("ERR_TLS_") || [
+          "DEPTH_ZERO_SELF_SIGNED_CERT",
+          "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+          "SELF_SIGNED_CERT_IN_CHAIN",
+          "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+          "UNABLE_TO_GET_ISSUER_CERT",
+          "HOSTNAME_MISMATCH"
+        ].includes(code ?? "")) {
+          reason = "tls";
+          message = `TLS error (${code})`;
+        }
         throw new CliError(
-          `Could not reach ${info.baseUrl}: check APEX_BASE_URL (or DRIP_BASE_URL) / network; server did not respond within ${info.timeoutMs / 1e3}s.`,
+          `Could not reach ${info.baseUrl}: check APEX_BASE_URL (or DRIP_BASE_URL) / network; ${message}.`,
           EXIT_CODES.general,
-          { ...info }
+          { reason, code, name: info.name, baseUrl: info.baseUrl, timeoutMs: info.timeoutMs }
         );
       }
     });
@@ -13153,8 +13194,9 @@ trackingCommand.command("latency").description("Measure forced-preview versus na
         ].join("/")
       ])
     );
+    console.log("Times in ms. Fewer than 5 measured samples: -.");
     console.log(
-      "Times in ms. Fewer than 5 measured samples: -. Preload/anti-flicker position: under evaluation."
+      "Position: runtime unchanged (inline config decides within tens of ms; forced previews fetch config over the network and are not representative)"
     );
   });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drip-apex/apex-cli",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "license": "MIT",
   "description": "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   "private": false,