@retasc/cli 1.35.0 → 1.35.1

package/CHANGELOG.md

@@ -6,6 +6,17 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.35.1 (2026-08-25)
+
+- **RTSC-478** — a network failure now names its own cause. Node reports every failed
+  `fetch` as the literal `fetch failed` and puts the diagnosis on `err.cause.code`, which
+  the CLI read past, so `retasc login` on a machine whose TLS trust store Node cannot read
+  died on `✗ fetch failed` and nothing else. It now prints
+  `✗ fetch failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)` — a searchable string naming the
+  real problem. `cli/README.md` gains a troubleshooting entry keyed on that code, covering
+  both causes: a corporate TLS-inspecting proxy, and a Homebrew `openssl@3` keg that lost
+  its CA symlink (the confusing one, since `curl` and `npm` keep working).
+
 ## 1.35.0 (2026-08-25)
 
 - **RTSC-709** — `retasc issue show` and `retasc issue list` read the queue from a

package/README.md

@@ -122,6 +122,34 @@ Two more are reachable but not as their own command, which is also deliberate:
 If you want any of the above from a terminal anyway, say so in an issue: the point of this
 list is that their absence is a choice we wrote down, not one nobody has noticed.
 
+## Troubleshooting
+
+### `fetch failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)` or `(SELF_SIGNED_CERT_IN_CHAIN)`
+
+Node cannot verify the TLS certificate, so every request the CLI makes dies before it is
+sent. It usually shows up on `retasc login`, because that is the first command that talks
+to the network. Two causes, and the code tells you which:
+
+- **A corporate TLS-inspecting proxy** (Zscaler and similar) re-signs traffic with a root
+  Node does not trust — normally `SELF_SIGNED_CERT_IN_CHAIN`. Point Node at your
+  organisation's CA bundle:
+
+  ```bash
+  export NODE_EXTRA_CA_CERTS=/path/to/your-company-ca.pem
+  ```
+
+- **A Homebrew Node whose OpenSSL keg lost its CA symlink** — normally
+  `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, and the confusing one, because `curl` and `npm`
+  keep working: they do not read the file Node reads. Relink it:
+
+  ```bash
+  brew postinstall openssl@3
+  ```
+
+Never set `NODE_TLS_REJECT_UNAUTHORIZED=0`. It turns off certificate verification for
+every connection the process makes, including the one carrying your session token.
+`NODE_EXTRA_CA_CERTS` fixes the same failures with verification left on.
+
 ## Links
 
 - Website — [retasc.com](https://retasc.com)

package/dist/api.js

@@ -3,6 +3,7 @@ import { makeFunctionReference } from "convex/server";
 import { loadConfig } from "./config.js";
 import { refreshSession, deviceLogin } from "./auth.js";
 import { selfCommand } from "./lib/launcher.js";
+import { clean as sanitize } from "./lib/text.js";
 import { VERSION } from "./version.js";
 // Typed-ish references to the public management functions in convex/manage.ts.
 // The CLI is a standalone package, so we reference functions by name rather than
@@ -100,6 +101,19 @@ export function formatError(e) {
         .split("\n")[0]
         .replace(/^.*?Uncaught Error:\s*/, "")
         .trim();
+    // RTSC-478: a failed `fetch` throws the literal `TypeError: fetch failed` and puts the
+    // actual diagnosis on `cause.code` — `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` when Node cannot
+    // read the machine's CA roots, `SELF_SIGNED_CERT_IN_CHAIN` behind a corporate
+    // TLS-inspecting proxy, `ECONNREFUSED`, `ENOTFOUND`. Reading `message` alone throws away
+    // the diagnosis Node already handed us, and leaves `retasc login` — the FIRST command a
+    // new user runs — dead-ended on a string that names nothing and searches for nothing:
+    //     ✗ fetch failed          →     ✗ fetch failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)
+    // Fallback branch only: a structured backend error (above) already carries its own `code`.
+    // Sanitized like every other string we print, because `cause` is not always ours.
+    const raw = e?.cause?.code;
+    const code = typeof raw === "string" ? sanitize(raw).trim() : "";
+    if (code && !message.includes(code))
+        return { message: `${message} (${code})` };
     return { message };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.35.0",
+  "version": "1.35.1",
   "description": "Retasc CLI — the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {