@enrichlayer/el-linear 1.18.0 → 1.19.0

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
@@ -343,6 +356,27 @@ preferences; those stay in personal config. Example team file:
 Run `el-linear config show` to see the resolved config and confirm which team
 config path is active (`teamConfig` field in the output).
 
+#### Migrating a personal-heavy config
+
+Before the team-config split, members typically carried full local copies of
+`members` / `teams` / `labels` / `statusDefaults` / `teamAliases` — and often
+a deprecated `brand: { name, reject }` key. Once a team config is in place
+those local copies just silently shadow the shared values (and silently
+*diverge* when they drift). To clean it up safely:
+
+```bash
+el-linear config migrate-from-personal           # dry-run — prints the plan per file
+el-linear config migrate-from-personal --apply   # write the slimmed files (with .bak-<ts> backups)
+```
+
+Targets the global personal config + every named profile's `config.json`. For
+each top-level shadowable key, the slim drops it **only** when the local copy
+is a strict subset of team (zero divergence, zero non-trivial personal-only
+entries); otherwise the key is left untouched and the divergence is reported
+in the plan so a human resolves it. The deprecated `brand` key is dropped
+when content-identical to a team `terms[]` entry, or converted to a personal
+`terms[]` entry when it differs (with a warning).
+
 ## Term enforcement (with brand-promotion examples)
 
 The `terms` rules let you keep a list of canonical names and the misspellings

package/dist/commands/config.js

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { getActiveTeamConfigInfo, getActiveTeamConfigPath, loadConfig, loadLocalConfig, } from "../config/config.js";
-import { resolveActiveProfile } from "../config/paths.js";
+import { planMigration, } from "../config/migrate-from-personal.js";
+import { CONFIG_PATH, isSafeProfileName, PROFILES_DIR, resolveActiveProfile, } from "../config/paths.js";
 import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
 import { updateConfig } from "./init/shared.js";
 /**
@@ -185,4 +186,166 @@ export function setupConfigCommands(program) {
         fs.writeFileSync(localPath, `${JSON.stringify(updated, null, 2)}\n`, "utf8");
         outputSuccess({ data: updated });
     }));
+    // ── config migrate-from-personal ──────────────────────────────────
+    //
+    // Slim personal/profile configs that duplicate keys the team config now
+    // provides (DEV-4458). The companion pure logic + tests live in
+    // `src/config/migrate-from-personal.ts`. This command just discovers
+    // the target files, reads the active team config, calls planMigration
+    // for each, and on --apply backs up + atomically rewrites them.
+    config
+        .command("migrate-from-personal")
+        .description("Slim personal/profile configs against the active team config — drops duplicated members/teams/labels/statusDefaults/teamAliases entries, and migrates the deprecated 'brand' key to a 'terms[]' entry. Dry-run by default; pass --apply to write.")
+        .option("--apply", "Write the slimmed files (with timestamped .bak-<ts> backups + atomic replace). Default is dry-run — only prints the plan.")
+        .option("--file <path>", "Scope to one file. Default: ~/.config/el-linear/config.json plus every <profiles>/<name>/config.json with a safe name.")
+        .addHelpText("after", `\nThe slim only drops a shadowable top-level key when the personal copy is a strict subset of team (zero divergence and zero non-trivial personal-only entries). Anything that would silently shadow a team value, or carry a personal-only entry team doesn't have, is left untouched and reported in the plan so a human can decide.\n\nThe active team config is never a target — passing --file <team-path> is rejected, and a profile config that happens to coincide with the team path is skipped silently with a warning. The first --apply may re-format JSON to 2-space indent + trailing newline; this is harmless but the .bak-<ts> backup preserves the original byte-for-byte.\n\nUses the currently-active team config for every target. If you have profiles pointing at different team configs, run --file <path> per profile with EL_LINEAR_TEAM_CONFIG set.\n\nExamples:\n  el-linear config migrate-from-personal\n  el-linear config migrate-from-personal --apply\n  el-linear config migrate-from-personal --file ~/.config/el-linear/profiles/foo/config.json --apply`)
+        .action(handleAsyncCommand(async (opts) => {
+        const teamPath = getActiveTeamConfigPath();
+        if (!teamPath) {
+            throw new Error("No active team config found. Set one with `el-linear config team set-path <path>` (or EL_LINEAR_TEAM_CONFIG) before running migrate-from-personal — without a team layer there's nothing to dedupe against.");
+        }
+        let team;
+        try {
+            team = JSON.parse(fs.readFileSync(teamPath, "utf8"));
+        }
+        catch (err) {
+            throw new Error(`Failed to read team config at ${teamPath}: ${err.message}`);
+        }
+        const apply = opts.apply ?? false;
+        const resolvedTeamPath = path.resolve(teamPath);
+        // Self-diff guard: refuse to migrate the team config against itself
+        // (cycle-1 nit). Without this, every shadowable key in team would
+        // classify as "drop" (a key is trivially a subset of itself) and
+        // --apply would gut the team config.
+        if (opts.file &&
+            path.resolve(expandHome(opts.file)) === resolvedTeamPath) {
+            throw new Error(`--file resolves to the active team config (${resolvedTeamPath}). Refusing to migrate the team config against itself.`);
+        }
+        const targetsBeforeFilter = opts.file
+            ? [path.resolve(expandHome(opts.file))]
+            : enumerateMigrationTargets();
+        const targets = [];
+        for (const t of targetsBeforeFilter) {
+            if (path.resolve(t) === resolvedTeamPath) {
+                outputWarning(`Skipping ${t} — it resolves to the active team config; migrating it against itself would erase team-shared keys.`);
+                continue;
+            }
+            targets.push(t);
+        }
+        const results = targets.map((file) => migrateOneFile(file, team, apply));
+        // Forward per-file plan warnings to the standard _warnings envelope
+        // (cycle-1 nit) so scripters reading the stable warning channel see
+        // them without having to inspect each target.
+        for (const r of results) {
+            for (const w of r.warnings)
+                outputWarning(`${r.file}: ${w}`);
+        }
+        // --file <single>: an unreadable / unparseable target is a hard
+        // failure (cycle-1 nit). Default enumeration stays soft so one bad
+        // profile doesn't crash the run for the rest.
+        if (opts.file && results.length === 1 && results[0].error) {
+            throw new Error(results[0].error);
+        }
+        outputSuccess({
+            data: {
+                teamConfigPath: teamPath,
+                applied: apply,
+                targetCount: results.length,
+                targets: results,
+            },
+        });
+    }));
+}
+/**
+ * Enumerate every personal/profile config file the migration tool should
+ * consider by default: the global personal config, plus each profile dir
+ * whose name passes `isSafeProfileName` and whose `config.json` exists.
+ */
+function enumerateMigrationTargets() {
+    const out = [];
+    if (fs.existsSync(CONFIG_PATH))
+        out.push(CONFIG_PATH);
+    if (fs.existsSync(PROFILES_DIR)) {
+        const entries = fs.readdirSync(PROFILES_DIR);
+        for (const name of entries.sort()) {
+            if (!isSafeProfileName(name))
+                continue;
+            const p = path.join(PROFILES_DIR, name, "config.json");
+            if (fs.existsSync(p))
+                out.push(p);
+        }
+    }
+    return out;
+}
+function migrateOneFile(file, team, apply) {
+    let rawText;
+    let personal;
+    try {
+        rawText = fs.readFileSync(file, "utf8");
+        personal = JSON.parse(rawText);
+    }
+    catch (err) {
+        return {
+            file,
+            changed: false,
+            before: { sizeBytes: 0, keys: [] },
+            after: { sizeBytes: 0, keys: [] },
+            keys: [],
+            brand: { status: "absent" },
+            warnings: [],
+            error: `Could not read/parse: ${err.message}`,
+        };
+    }
+    const { slimmed, plan } = planMigration(personal, team);
+    const slimmedText = `${JSON.stringify(slimmed, null, 2)}\n`;
+    const beforeBytes = Buffer.byteLength(rawText, "utf8");
+    const afterBytes = Buffer.byteLength(slimmedText, "utf8");
+    const changed = slimmedText !== rawText;
+    const result = {
+        file,
+        changed,
+        before: { sizeBytes: beforeBytes, keys: Object.keys(personal) },
+        after: { sizeBytes: afterBytes, keys: Object.keys(slimmed) },
+        keys: plan.keys,
+        brand: plan.brand,
+        warnings: plan.warnings,
+    };
+    if (apply && changed) {
+        // Backup names include milliseconds (sub-second collisions on rapid
+        // re-apply would otherwise overwrite the original backup) AND copy
+        // with COPYFILE_EXCL so a same-millisecond collision throws instead
+        // of clobbering. Same for the temp file via `wx` flag.
+        const { backup, tmp } = acquireBackupAndTempPaths(file);
+        fs.copyFileSync(file, backup, fs.constants.COPYFILE_EXCL);
+        fs.writeFileSync(tmp, slimmedText, { encoding: "utf8", flag: "wx" });
+        fs.renameSync(tmp, file);
+        result.backup = backup;
+    }
+    return result;
+}
+function backupTimestamp() {
+    const d = new Date();
+    const pad = (n) => n.toString().padStart(2, "0");
+    const pad3 = (n) => n.toString().padStart(3, "0");
+    return (`${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}` +
+        `-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}` +
+        `-${pad3(d.getMilliseconds())}`);
+}
+/**
+ * Pick a `.bak-<ts>` and `.tmp-<ts>` pair that don't collide with anything
+ * on disk. Millisecond resolution makes a collision extraordinarily rare,
+ * but a tight retry loop closes the remaining gap (and the `COPYFILE_EXCL`
+ * / `wx` flags at the call site fail loudly if the gap is ever crossed).
+ */
+function acquireBackupAndTempPaths(file) {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const ts = backupTimestamp();
+        const suffix = attempt === 0 ? ts : `${ts}-${attempt}`;
+        const backup = `${file}.bak-${suffix}`;
+        const tmp = `${file}.tmp-${suffix}`;
+        if (!fs.existsSync(backup) && !fs.existsSync(tmp)) {
+            return { backup, tmp };
+        }
+    }
+    throw new Error(`Could not pick a unique backup name for ${file} after 100 attempts; clean up old .bak-/.tmp- siblings and retry.`);
 }

package/dist/config/migrate-from-personal.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Plan + apply the personal-to-team-backed config slim.
+ *
+ * After the team-config split (DEV-4172 / ALL-964) members typically still
+ * carry full duplicates of the now-shared keys in their personal/profile
+ * configs. The duplicates are silent shadows when identical and silent
+ * divergences when they drift. This module computes a per-file plan:
+ *
+ *  - **Top-level shadowable keys** (`members`, `teams`, `labels`,
+ *    `statusDefaults`, `teamAliases`) are *dropped* only when the personal
+ *    copy is a strict subset of team (zero divergence and zero non-trivial
+ *    personal-only entries). Otherwise the key is left untouched and the
+ *    diff is reported, so a human resolves it.
+ *  - The deprecated `brand: { name, reject }` key is dropped when content-
+ *    identical to an existing team `terms[]` entry; otherwise it is
+ *    *converted* into a personal `terms[]` entry (no shadowing of team).
+ *  - Genuinely personal keys (`defaultTeam`, `defaultLabels`,
+ *    `teamConfigPath`, anything not in the shadowable set or `brand`) are
+ *    never touched.
+ *
+ * Pure: no fs / no process / no logging. The caller does I/O. DEV-4458.
+ */
+/** Top-level keys typically owned by the team config layer. */
+export declare const TEAM_SHADOWABLE_KEYS: readonly ["members", "teams", "labels", "statusDefaults", "teamAliases"];
+export type TeamShadowableKey = (typeof TEAM_SHADOWABLE_KEYS)[number];
+export type JsonValue = string | number | boolean | null | {
+    [k: string]: JsonValue;
+} | JsonValue[];
+export type JsonObject = {
+    [k: string]: JsonValue;
+};
+/** Per-key decision in the plan. */
+export interface KeyAction {
+    key: string;
+    action: "drop" | "keep-divergent" | "keep-additions" | "absent";
+    /** Leaves whose personal value matched team exactly. */
+    matchCount: number;
+    /** Leaves whose personal value differs from team (would be a silent shadow). */
+    divergentCount: number;
+    /** Non-trivial personal-only leaves (would be lost if dropped). */
+    additionCount: number;
+    /** First few divergent / addition paths, for human-readable context. */
+    sampleDivergent?: string[];
+    sampleAdditions?: string[];
+}
+/** What we did with the deprecated `brand` key. */
+export interface BrandAction {
+    status: "absent" | "drop-duplicate" | "convert-to-term" /** Couldn't convert safely (e.g. existing personal `terms` is malformed). */ | "keep-malformed";
+    /** When status === "convert-to-term", the new entry appended to terms[]. */
+    convertedTo?: {
+        canonical: string;
+        reject: string[];
+    };
+    reason?: string;
+}
+export interface MigrationPlan {
+    keys: KeyAction[];
+    brand: BrandAction;
+    warnings: string[];
+}
+export interface MigrationResult {
+    slimmed: JsonObject;
+    plan: MigrationPlan;
+}
+/** A canonical JSON-friendly deep equality. */
+export declare function deepEqual(a: JsonValue, b: JsonValue): boolean;
+/**
+ * Compute the slimmed config + the plan that explains it. Pure.
+ *
+ * @param personal The personal/profile config object as parsed from disk.
+ * @param team     The active team config object as parsed from disk. Pass
+ *                 `{}` if no team config is configured — every shadowable
+ *                 key becomes either `keep-additions` or `keep-divergent`,
+ *                 so nothing gets dropped (correct: without team there is
+ *                 nothing to fall back to).
+ */
+export declare function planMigration(personal: JsonObject, team: JsonObject): MigrationResult;

package/dist/config/migrate-from-personal.js

@@ -0,0 +1,236 @@
+/**
+ * Plan + apply the personal-to-team-backed config slim.
+ *
+ * After the team-config split (DEV-4172 / ALL-964) members typically still
+ * carry full duplicates of the now-shared keys in their personal/profile
+ * configs. The duplicates are silent shadows when identical and silent
+ * divergences when they drift. This module computes a per-file plan:
+ *
+ *  - **Top-level shadowable keys** (`members`, `teams`, `labels`,
+ *    `statusDefaults`, `teamAliases`) are *dropped* only when the personal
+ *    copy is a strict subset of team (zero divergence and zero non-trivial
+ *    personal-only entries). Otherwise the key is left untouched and the
+ *    diff is reported, so a human resolves it.
+ *  - The deprecated `brand: { name, reject }` key is dropped when content-
+ *    identical to an existing team `terms[]` entry; otherwise it is
+ *    *converted* into a personal `terms[]` entry (no shadowing of team).
+ *  - Genuinely personal keys (`defaultTeam`, `defaultLabels`,
+ *    `teamConfigPath`, anything not in the shadowable set or `brand`) are
+ *    never touched.
+ *
+ * Pure: no fs / no process / no logging. The caller does I/O. DEV-4458.
+ */
+/** Top-level keys typically owned by the team config layer. */
+export const TEAM_SHADOWABLE_KEYS = [
+    "members",
+    "teams",
+    "labels",
+    "statusDefaults",
+    "teamAliases",
+];
+/** A canonical JSON-friendly deep equality. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b))
+            return false;
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (typeof a === "object") {
+        const ak = Object.keys(a).sort();
+        const bk = Object.keys(b).sort();
+        if (ak.length !== bk.length)
+            return false;
+        if (ak.some((k, i) => k !== bk[i]))
+            return false;
+        return ak.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+function isTriviallyEmpty(v) {
+    if (v === undefined || v === null)
+        return true;
+    if (Array.isArray(v))
+        return v.length === 0;
+    if (typeof v === "object")
+        return Object.keys(v).length === 0;
+    return false;
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/**
+ * Walk personal and classify each LEAF against team at the same path:
+ *   match     — present in team with the same value
+ *   divergent — present in team with a different value (would silently shadow)
+ *   addition  — absent from team and non-trivially non-empty (would be lost)
+ *
+ * Trivially-empty containers (e.g. `members.handles.github = {}`) are not
+ * counted as additions — dropping them loses no information.
+ */
+function classifyDeep(personal, team, path, out) {
+    if (personal === undefined)
+        return;
+    // Both objects → recurse into keys.
+    if (isPlainObject(personal) && isPlainObject(team)) {
+        for (const k of Object.keys(personal)) {
+            classifyDeep(personal[k], team[k], path ? `${path}.${k}` : k, out);
+        }
+        return;
+    }
+    // Personal is a leaf (primitive / array / object without a matching team obj).
+    if (team === undefined) {
+        if (!isTriviallyEmpty(personal))
+            out.additions.push(path);
+        return;
+    }
+    if (deepEqual(personal, team)) {
+        out.matches += 1;
+    }
+    else {
+        out.divergent.push(path);
+    }
+}
+function planTopLevelKey(key, personal, team) {
+    if (personal === undefined) {
+        return {
+            key,
+            action: "absent",
+            matchCount: 0,
+            divergentCount: 0,
+            additionCount: 0,
+        };
+    }
+    const acc = { matches: 0, divergent: [], additions: [] };
+    classifyDeep(personal, team, key, acc);
+    const action = acc.divergent.length === 0 && acc.additions.length === 0
+        ? "drop"
+        : acc.divergent.length > 0
+            ? "keep-divergent"
+            : "keep-additions";
+    const ka = {
+        key,
+        action,
+        matchCount: acc.matches,
+        divergentCount: acc.divergent.length,
+        additionCount: acc.additions.length,
+    };
+    if (acc.divergent.length > 0)
+        ka.sampleDivergent = acc.divergent.slice(0, 5);
+    if (acc.additions.length > 0)
+        ka.sampleAdditions = acc.additions.slice(0, 5);
+    return ka;
+}
+function readBrand(personal) {
+    const raw = personal.brand;
+    if (!isPlainObject(raw))
+        return null;
+    const name = raw.name;
+    const reject = raw.reject;
+    if (typeof name !== "string")
+        return null;
+    if (!Array.isArray(reject) || !reject.every((r) => typeof r === "string")) {
+        return null;
+    }
+    return { name, reject: reject };
+}
+function readTeamTerms(team) {
+    const t = team.terms;
+    if (!Array.isArray(t))
+        return [];
+    const out = [];
+    for (const e of t) {
+        if (!isPlainObject(e))
+            continue;
+        const canonical = e.canonical;
+        const reject = e.reject;
+        if (typeof canonical !== "string")
+            continue;
+        if (!Array.isArray(reject) || !reject.every((r) => typeof r === "string")) {
+            continue;
+        }
+        out.push({ canonical, reject: reject });
+    }
+    return out;
+}
+function brandMatchesTerm(brand, term) {
+    return brand.name === term.canonical && deepEqual(brand.reject, term.reject);
+}
+/**
+ * Compute the slimmed config + the plan that explains it. Pure.
+ *
+ * @param personal The personal/profile config object as parsed from disk.
+ * @param team     The active team config object as parsed from disk. Pass
+ *                 `{}` if no team config is configured — every shadowable
+ *                 key becomes either `keep-additions` or `keep-divergent`,
+ *                 so nothing gets dropped (correct: without team there is
+ *                 nothing to fall back to).
+ */
+export function planMigration(personal, team) {
+    const warnings = [];
+    const slimmed = { ...personal };
+    const keyActions = TEAM_SHADOWABLE_KEYS.map((key) => planTopLevelKey(key, personal[key], team[key]));
+    for (const ka of keyActions) {
+        if (ka.action === "drop")
+            delete slimmed[ka.key];
+    }
+    // Brand → terms.
+    let brand;
+    const brandShape = readBrand(personal);
+    if (brandShape === null) {
+        brand = { status: "absent" };
+    }
+    else {
+        const teamTerms = readTeamTerms(team);
+        const dup = teamTerms.find((t) => brandMatchesTerm(brandShape, t));
+        if (dup !== undefined) {
+            delete slimmed.brand;
+            brand = {
+                status: "drop-duplicate",
+                reason: `brand is content-identical to team terms entry "${dup.canonical}"`,
+            };
+        }
+        else if (personal.terms !== undefined && !Array.isArray(personal.terms)) {
+            // Refuse to convert: an existing personal `terms` field is not an
+            // array (likely a hand-edit gone wrong). The strict-subset gate
+            // elsewhere never silently destroys info — neither should this
+            // path. Leave brand AND terms as-is; surface as a warning so a
+            // human can resolve.
+            brand = {
+                status: "keep-malformed",
+                reason: "existing personal 'terms' field is not an array; leaving 'brand' and 'terms' untouched for human review",
+            };
+            warnings.push(`Cannot convert deprecated 'brand': existing 'terms' field is not an array (got ${typeof personal.terms}). Left 'brand' and 'terms' as-is — fix 'terms' to a proper array of { canonical, reject } entries and re-run.`);
+        }
+        else {
+            // Convert: append a personal terms entry, drop brand.
+            delete slimmed.brand;
+            const existing = Array.isArray(slimmed.terms)
+                ? slimmed.terms
+                : [];
+            const converted = {
+                canonical: brandShape.name,
+                reject: brandShape.reject,
+            };
+            slimmed.terms = [...existing, { ...converted }];
+            brand = {
+                status: "convert-to-term",
+                convertedTo: converted,
+                reason: teamTerms.length === 0
+                    ? "team config has no terms; converted brand to a personal terms entry"
+                    : "brand does not match any team terms entry; converted to a personal terms entry",
+            };
+            if (teamTerms.length > 0) {
+                warnings.push(`brand on this file diverges from team terms — preserved as a personal terms entry. Review whether the team config should adopt it.`);
+            }
+        }
+    }
+    return { slimmed, plan: { keys: keyActions, brand, warnings } };
+}

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.19.0",
   "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/",