@enrichlayer/el-linear 1.18.0 → 1.18.1

package/README.md

@@ -247,6 +247,19 @@ A full reference with every key documented lives in [config.example.json](./conf
 UUIDs come from the Linear UI (URL bars, settings pages) or via el-linear
 itself: `el-linear teams list --raw | jq '.[] | {key, id}'`, etc.
 
+### Networking (IPv4 preference)
+
+el-linear talks only to `api.linear.app` (Cloudflare, dual-stack). On a network
+whose IPv6 route is broken or blackholed, Node's defaults (DNS result order
+`verbatim`, often IPv6-first, plus Happy Eyeballs) can make every call stall
+until it times out — surfacing as `GraphQL request failed: fetch failed`. To
+avoid that, el-linear prefers IPv4 by default (`ipv4first` DNS ordering with
+`autoSelectFamily` disabled).
+
+If you're on a **pure IPv6-only** network (no IPv4 route at all), set
+`EL_LINEAR_NETWORK_VERBATIM=1` to restore Node's native verbatim /
+Happy-Eyeballs behavior.
+
 ### Workspace URL key
 
 `refs wrap` and the auto-link paths build canonical issue URLs like

package/dist/main.js

@@ -28,9 +28,21 @@ import { setupTeamsCommands } from "./commands/teams.js";
 import { setupTemplatesCommands } from "./commands/templates.js";
 import { setupUsersCommands } from "./commands/users.js";
 import { setActiveProfileForSession } from "./config/paths.js";
+import { initCliSentry } from "./sentry.js";
+import { logger } from "./utils/logger.js";
+import { applyIpv4Preference } from "./utils/network-preference.js";
 import { setFieldsFilter, setJqFilter, setOutputFormat, setRawMode, } from "./utils/output.js";
 import { outputUsageInfo } from "./utils/usage.js";
 import { splitList } from "./utils/validators.js";
+// Prefer IPv4 for outbound API calls before any network I/O (Sentry init or a
+// command) runs — works around broken-IPv6 networks stalling Node's fetch.
+// Opt out with EL_LINEAR_NETWORK_VERBATIM=1. See DEV-4415 / network-preference.ts.
+const ipv4Preferred = applyIpv4Preference();
+if (process.env.EL_LINEAR_DEBUG ?? process.env.LINCTL_DEBUG) {
+    logger.error(ipv4Preferred
+        ? "[el-linear] network: preferring IPv4 (dns=ipv4first, autoSelectFamily=off)"
+        : "[el-linear] network: verbatim mode (EL_LINEAR_NETWORK_VERBATIM=1)");
+}
 // Read the version from package.json at startup so `--version` can never
 // drift from the published release (pre-fix: a stale 1.8.1 literal lived
 // here while package.json was at 1.10.0). `dist/main.js` lives one
@@ -38,6 +50,12 @@ import { splitList } from "./utils/validators.js";
 // correctly in both `pnpm dev` (tsx) and `node dist/main.js` invocations.
 const __dirname_main = dirname(fileURLToPath(import.meta.url));
 const packageJson = JSON.parse(readFileSync(join(__dirname_main, "..", "package.json"), "utf-8"));
+// Opt-in error reporting (DEV-4349): no-ops unless the namespaced SENTRY_DSN_CLI
+// env var is set AND the optional `@sentry/node` dependency is installed.
+// Fire-and-forget — the dynamic SDK import must never delay or break the CLI;
+// the global handlers it installs catch async failures once it resolves (a tick
+// later).
+void initCliSentry("el-linear", { version: packageJson.version });
 program
     .name("el-linear")
     .description("A pragmatic CLI for Linear.app — deterministic resolution, structured validation, GraphQL escape hatch.")

package/dist/sentry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Optional, opt-in Sentry error reporting for el-linear (DEV-4349, sub of DEV-4328).
+ *
+ * el-linear ships open-source, so Sentry is NEVER required:
+ *  - No dependency on the private `@enrichlayer/sentry` package — this is a
+ *    self-contained copy of its scrub + init (acceptable duplication: the repo
+ *    boundary makes sharing the tools-repo util impossible).
+ *  - `@sentry/node` is an OPTIONAL dependency, loaded via a dynamic
+ *    `import("@sentry/node")` ONLY when a DSN resolves. `npm i @enrichlayer/el-linear`
+ *    never forces Sentry, and a missing/uninstalled SDK is a clean no-op.
+ *  - The DSN comes from the environment only (`SENTRY_DSN_CLI`) — no Vault (that
+ *    is internal infra OSS users do not have), and NOT the conventional
+ *    `SENTRY_DSN` (which would collide with an OSS user's own app). Default OFF;
+ *    only active when we set our namespaced env var in our own environment.
+ *
+ * One line at the top of `main.ts`:
+ *
+ *   import { initCliSentry } from "./sentry.js";
+ *   void initCliSentry("el-linear", { version });
+ *   // ... program.parse()
+ *
+ * Set `EL_SENTRY_DISABLED=1` to force-disable even when a DSN is present.
+ *
+ * Safety: a mandatory `beforeSend` scrub redacts secret-shaped values (tokens,
+ * keys, auth headers). CLI argv/env routinely carry credentials (the Linear API
+ * token, GitHub PATs), and an unscrubbed report would leak them into Sentry.
+ */
+/** A Sentry event is deeply dynamic; we walk it structurally. */
+type Json = unknown;
+export declare const REDACTED = "[redacted]";
+/** Redact credential-shaped substrings from a string. Pure. */
+export declare function scrubString(input: string): string;
+/**
+ * Recursively scrub a JSON-ish value: redact whole values under secret-named
+ * keys, scrub credential-shaped substrings everywhere else, and cap depth so a
+ * cyclic / huge event can't hang the scrubber. Pure.
+ */
+export declare function scrubValue(value: Json, depth?: number): Json;
+/**
+ * Scrub a Sentry event (message, exceptions, breadcrumbs, extra, request — which
+ * carries headers + env — and contexts) by walking it structurally. Pure.
+ */
+export declare function scrubEvent(event: Json): Json;
+/**
+ * Resolve the CLI Sentry DSN from the environment. Returns null when reporting
+ * is disabled or no DSN is configured (→ init no-ops). No Vault: OSS users do
+ * not have it, so this path is intentionally env-only.
+ *
+ * Only the namespaced `SENTRY_DSN_CLI` is read — NOT the conventional
+ * `SENTRY_DSN`. el-linear ships open-source, and `SENTRY_DSN` is the var the
+ * `@sentry/node` SDK reads by default, so an OSS user running their own
+ * Sentry-instrumented app very likely has it set; falling back to it would make
+ * el-linear silently report into *their* project. Requiring our explicit,
+ * namespaced var keeps activation unambiguous and collision-free (DEV-4349
+ * cycle-1 review). The internal tools build uses `SENTRY_DSN_CLI` too, so we
+ * lose nothing.
+ */
+export declare function resolveDsn(): string | null;
+export interface InitCliSentryOptions {
+    /** Override the resolved DSN (mainly for tests). */
+    dsn?: string | null;
+    /** CLI version for the Sentry `release` (defaults to "0.0.0"). */
+    version?: string;
+}
+/**
+ * Initialize Sentry for el-linear. Async because `@sentry/node` is loaded via a
+ * dynamic import only when a DSN resolves — so a CLI run without a DSN (the
+ * default for OSS users) never even loads the SDK. Returns true when reporting
+ * is active, false when it no-ops (disabled / no DSN / SDK not installed).
+ *
+ * When active, installs global uncaughtException + unhandledRejection handlers
+ * that capture → flush → exit(1). Because the SDK loads via a dynamic import
+ * (resolving a tick after the caller's fire-and-forget `void`), a synchronous
+ * throw during the very first tick of CLI startup — before the handlers install
+ * — is out of scope; this is best-effort reporting, not a crash guarantee.
+ */
+export declare function initCliSentry(cliName: string, opts?: InitCliSentryOptions): Promise<boolean>;
+export {};

package/dist/sentry.js

@@ -0,0 +1,150 @@
+/**
+ * Optional, opt-in Sentry error reporting for el-linear (DEV-4349, sub of DEV-4328).
+ *
+ * el-linear ships open-source, so Sentry is NEVER required:
+ *  - No dependency on the private `@enrichlayer/sentry` package — this is a
+ *    self-contained copy of its scrub + init (acceptable duplication: the repo
+ *    boundary makes sharing the tools-repo util impossible).
+ *  - `@sentry/node` is an OPTIONAL dependency, loaded via a dynamic
+ *    `import("@sentry/node")` ONLY when a DSN resolves. `npm i @enrichlayer/el-linear`
+ *    never forces Sentry, and a missing/uninstalled SDK is a clean no-op.
+ *  - The DSN comes from the environment only (`SENTRY_DSN_CLI`) — no Vault (that
+ *    is internal infra OSS users do not have), and NOT the conventional
+ *    `SENTRY_DSN` (which would collide with an OSS user's own app). Default OFF;
+ *    only active when we set our namespaced env var in our own environment.
+ *
+ * One line at the top of `main.ts`:
+ *
+ *   import { initCliSentry } from "./sentry.js";
+ *   void initCliSentry("el-linear", { version });
+ *   // ... program.parse()
+ *
+ * Set `EL_SENTRY_DISABLED=1` to force-disable even when a DSN is present.
+ *
+ * Safety: a mandatory `beforeSend` scrub redacts secret-shaped values (tokens,
+ * keys, auth headers). CLI argv/env routinely carry credentials (the Linear API
+ * token, GitHub PATs), and an unscrubbed report would leak them into Sentry.
+ */
+/** Key names whose values are always redacted, regardless of content. */
+const SECRET_KEY_RE = /(token|secret|passwd|password|api[_-]?key|apikey|bearer|authorization|auth|dsn|cookie|session|credential|private[_-]?key)/i;
+/** Value patterns that look like a credential even under an innocent key. */
+const SECRET_VALUE_RES = [
+    /glpat-[A-Za-z0-9_-]{10,}/g, // GitLab PAT
+    /gh[pousr]_[A-Za-z0-9]{20,}/g, // GitHub classic token
+    /github_pat_[A-Za-z0-9_]{20,}/g, // GitHub fine-grained PAT (now the default)
+    /xox[baprs]-[A-Za-z0-9-]{10,}/g, // Slack bot/user token
+    /xapp-[A-Za-z0-9-]{10,}/g, // Slack app-level token
+    /lin_api_[A-Za-z0-9]{20,}/g, // Linear API key
+    /sk-[A-Za-z0-9]{16,}/g, // OpenAI-style key
+    /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, // JWT
+    /\b[Bb]earer\s+[A-Za-z0-9._-]{10,}/g, // bearer header
+    /https?:\/\/[^:@/\s]+:[^@/\s]+@/g, // creds in a URL (user:pass@host)
+];
+export const REDACTED = "[redacted]";
+const MAX_DEPTH = 8;
+/** Redact credential-shaped substrings from a string. Pure. */
+export function scrubString(input) {
+    let out = input;
+    for (const re of SECRET_VALUE_RES) {
+        out = out.replace(re, REDACTED);
+    }
+    return out;
+}
+/**
+ * Recursively scrub a JSON-ish value: redact whole values under secret-named
+ * keys, scrub credential-shaped substrings everywhere else, and cap depth so a
+ * cyclic / huge event can't hang the scrubber. Pure.
+ */
+export function scrubValue(value, depth = 0) {
+    if (depth > MAX_DEPTH) {
+        // Fail CLOSED: past the cap we can't recurse to check for secrets, so a
+        // primitive could be a credential — redact rather than leak it.
+        return REDACTED;
+    }
+    if (typeof value === "string") {
+        return scrubString(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => scrubValue(v, depth + 1));
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = SECRET_KEY_RE.test(k) ? REDACTED : scrubValue(v, depth + 1);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Scrub a Sentry event (message, exceptions, breadcrumbs, extra, request — which
+ * carries headers + env — and contexts) by walking it structurally. Pure.
+ */
+export function scrubEvent(event) {
+    return scrubValue(event);
+}
+/**
+ * Resolve the CLI Sentry DSN from the environment. Returns null when reporting
+ * is disabled or no DSN is configured (→ init no-ops). No Vault: OSS users do
+ * not have it, so this path is intentionally env-only.
+ *
+ * Only the namespaced `SENTRY_DSN_CLI` is read — NOT the conventional
+ * `SENTRY_DSN`. el-linear ships open-source, and `SENTRY_DSN` is the var the
+ * `@sentry/node` SDK reads by default, so an OSS user running their own
+ * Sentry-instrumented app very likely has it set; falling back to it would make
+ * el-linear silently report into *their* project. Requiring our explicit,
+ * namespaced var keeps activation unambiguous and collision-free (DEV-4349
+ * cycle-1 review). The internal tools build uses `SENTRY_DSN_CLI` too, so we
+ * lose nothing.
+ */
+export function resolveDsn() {
+    if (process.env.EL_SENTRY_DISABLED === "1") {
+        return null;
+    }
+    return process.env.SENTRY_DSN_CLI?.trim() || null;
+}
+/**
+ * Initialize Sentry for el-linear. Async because `@sentry/node` is loaded via a
+ * dynamic import only when a DSN resolves — so a CLI run without a DSN (the
+ * default for OSS users) never even loads the SDK. Returns true when reporting
+ * is active, false when it no-ops (disabled / no DSN / SDK not installed).
+ *
+ * When active, installs global uncaughtException + unhandledRejection handlers
+ * that capture → flush → exit(1). Because the SDK loads via a dynamic import
+ * (resolving a tick after the caller's fire-and-forget `void`), a synchronous
+ * throw during the very first tick of CLI startup — before the handlers install
+ * — is out of scope; this is best-effort reporting, not a crash guarantee.
+ */
+export async function initCliSentry(cliName, opts = {}) {
+    const dsn = opts.dsn === undefined ? resolveDsn() : opts.dsn;
+    if (!dsn) {
+        return false;
+    }
+    let Sentry;
+    try {
+        // Optional dependency: loaded only here, only when a DSN is set. A
+        // missing/uninstalled SDK is a clean no-op (we never ship Sentry to OSS
+        // users who have not opted in).
+        Sentry = (await import("@sentry/node"));
+    }
+    catch {
+        return false;
+    }
+    Sentry.init({
+        dsn,
+        release: `${cliName}@${opts.version ?? "0.0.0"}`,
+        environment: process.env.CI ? "ci" : "development",
+        tracesSampleRate: 0,
+        beforeSend: (event) => scrubEvent(event),
+    });
+    Sentry.setTag("cli", cliName);
+    const report = (err) => {
+        Sentry.captureException(err);
+        // Flush before exiting; the process is in an undefined state after an
+        // uncaught error, so report-then-die is the standard Sentry pattern.
+        Sentry.flush(2000).then(() => process.exit(1), () => process.exit(1));
+    };
+    process.on("uncaughtException", report);
+    process.on("unhandledRejection", (reason) => report(reason instanceof Error ? reason : new Error(String(reason))));
+    return true;
+}

package/dist/utils/network-preference.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Injectable seams for the two Node defaults we flip. Real callers use the
+ * `node:dns` / `node:net` implementations; tests pass spies.
+ */
+export interface NetworkPreferenceDeps {
+    setDefaultResultOrder: (order: "ipv4first" | "ipv6first" | "verbatim") => void;
+    setDefaultAutoSelectFamily: (value: boolean) => void;
+}
+/** Set this env var to `1` to keep Node's native behavior (see below). */
+export declare const VERBATIM_ENV = "EL_LINEAR_NETWORK_VERBATIM";
+/**
+ * Prefer IPv4 for el-linear's outbound API calls.
+ *
+ * el-linear talks only to `api.linear.app` (Cloudflare, dual-stack — it
+ * publishes AAAA records). On a network whose IPv6 route is broken or
+ * blackholed, Node 17+'s defaults — DNS result order `verbatim` (often
+ * IPv6-first) plus Happy Eyeballs (`autoSelectFamily`) — make `fetch`
+ * (undici) stall on the dead IPv6 path until it times out, surfacing as
+ * `GraphQL request failed: fetch failed`. Restoring `ipv4first` AND disabling
+ * `autoSelectFamily` makes el-linear use the working IPv4 path directly.
+ * (`ipv4first` alone is not enough — Happy Eyeballs still races the dead IPv6
+ * address; both levers are required.) `ipv4first` was Node's own default
+ * before v17, so this is a conservative choice.
+ *
+ * Opt out with `EL_LINEAR_NETWORK_VERBATIM=1` — required only on pure
+ * IPv6-only networks (no IPv4 route at all), where preferring IPv4 would pick
+ * an unreachable address. See DEV-4415.
+ *
+ * @returns `true` if the IPv4 preference was applied, `false` if opted out.
+ */
+export declare function applyIpv4Preference(env?: NodeJS.ProcessEnv, deps?: NetworkPreferenceDeps): boolean;

package/dist/utils/network-preference.js

@@ -0,0 +1,37 @@
+import dns from "node:dns";
+import net from "node:net";
+const defaultDeps = {
+    // Wrapped (not passed by reference) so the receiver keeps its module binding.
+    setDefaultResultOrder: (order) => dns.setDefaultResultOrder(order),
+    setDefaultAutoSelectFamily: (value) => net.setDefaultAutoSelectFamily(value),
+};
+/** Set this env var to `1` to keep Node's native behavior (see below). */
+export const VERBATIM_ENV = "EL_LINEAR_NETWORK_VERBATIM";
+/**
+ * Prefer IPv4 for el-linear's outbound API calls.
+ *
+ * el-linear talks only to `api.linear.app` (Cloudflare, dual-stack — it
+ * publishes AAAA records). On a network whose IPv6 route is broken or
+ * blackholed, Node 17+'s defaults — DNS result order `verbatim` (often
+ * IPv6-first) plus Happy Eyeballs (`autoSelectFamily`) — make `fetch`
+ * (undici) stall on the dead IPv6 path until it times out, surfacing as
+ * `GraphQL request failed: fetch failed`. Restoring `ipv4first` AND disabling
+ * `autoSelectFamily` makes el-linear use the working IPv4 path directly.
+ * (`ipv4first` alone is not enough — Happy Eyeballs still races the dead IPv6
+ * address; both levers are required.) `ipv4first` was Node's own default
+ * before v17, so this is a conservative choice.
+ *
+ * Opt out with `EL_LINEAR_NETWORK_VERBATIM=1` — required only on pure
+ * IPv6-only networks (no IPv4 route at all), where preferring IPv4 would pick
+ * an unreachable address. See DEV-4415.
+ *
+ * @returns `true` if the IPv4 preference was applied, `false` if opted out.
+ */
+export function applyIpv4Preference(env = process.env, deps = defaultDeps) {
+    if (env[VERBATIM_ENV] === "1") {
+        return false;
+    }
+    deps.setDefaultResultOrder("ipv4first");
+    deps.setDefaultAutoSelectFamily(false);
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -64,6 +64,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.0.18"
   },
+  "optionalDependencies": {
+    "@sentry/node": "^10.50.0"
+  },
   "scripts": {
     "build": "tsc && chmod +x dist/main.js",
     "clean": "rm -rf dist/",