@enrichlayer/el-linear 1.44.2 → 1.46.0

package/dist/utils/output.js

@@ -1,14 +1,89 @@
 import { execFileSync } from "node:child_process";
 import { resolveActiveProfile } from "../config/paths.js";
 import { dispatch as dispatchSummary, drainSummaryFieldWarnings, formatLine, inferKindFromPayload, } from "./formatters/summary.js";
+import { readGraphQLErrorDetail } from "./linear-graphql-error.js";
 import { logger } from "./logger.js";
 import { sanitizeForLog } from "./sanitize-for-log.js";
 const warningBuffer = [];
+let rateLimitBuffer = null;
 let rawMode = false;
 let quietMode = false;
 let jqFilter = null;
 let fieldsFilter = null;
 let outputFormat = "json";
+function minimumDefined(left, right) {
+    if (left === undefined)
+        return right;
+    if (right === undefined)
+        return left;
+    return Math.min(left, right);
+}
+function mergeRateLimitInfo(current, next) {
+    const endpoints = { ...current.endpoints };
+    for (const [name, observation] of Object.entries(next.endpoints ?? {})) {
+        const previous = endpoints[name];
+        endpoints[name] = {
+            ...previous,
+            ...observation,
+            minimumRemaining: minimumDefined(previous?.minimumRemaining ?? previous?.remaining, observation.minimumRemaining ?? observation.remaining),
+            observedRequests: (previous?.observedRequests ?? 0) + (observation.observedRequests ?? 1),
+        };
+    }
+    const currentComplexity = current.complexity;
+    const nextComplexity = next.complexity;
+    const complexity = currentComplexity || nextComplexity
+        ? {
+            ...currentComplexity,
+            ...nextComplexity,
+            totalCost: (currentComplexity?.totalCost ?? currentComplexity?.cost ?? 0) +
+                (nextComplexity?.totalCost ?? nextComplexity?.cost ?? 0),
+            minimumRemaining: minimumDefined(currentComplexity?.minimumRemaining ?? currentComplexity?.remaining, nextComplexity?.minimumRemaining ?? nextComplexity?.remaining),
+        }
+        : undefined;
+    return {
+        ...current,
+        ...next,
+        observedRequests: (current.observedRequests ?? 1) + (next.observedRequests ?? 1),
+        minimumRemaining: minimumDefined(current.minimumRemaining ?? current.remaining, next.minimumRemaining ?? next.remaining),
+        ...(complexity ? { complexity } : {}),
+        ...(Object.keys(endpoints).length > 0 ? { endpoints } : {}),
+    };
+}
+/**
+ * Record a quota observation for the command's eventual output.
+ *
+ * The latest response remains authoritative for current remaining/reset
+ * values. Multi-request commands additionally retain their total observed
+ * request/complexity cost and the lowest headroom seen in every bucket.
+ */
+export function recordRateLimitInfo(info) {
+    const endpoints = Object.fromEntries(Object.entries(info.endpoints ?? {}).map(([name, endpoint]) => [
+        name,
+        {
+            ...endpoint,
+            minimumRemaining: endpoint.minimumRemaining ?? endpoint.remaining,
+            observedRequests: endpoint.observedRequests ?? 1,
+        },
+    ]));
+    const observation = {
+        ...info,
+        observedRequests: info.observedRequests ?? 1,
+        minimumRemaining: info.minimumRemaining ?? info.remaining,
+        ...(info.complexity
+            ? {
+                complexity: {
+                    ...info.complexity,
+                    totalCost: info.complexity.totalCost ?? info.complexity.cost,
+                    minimumRemaining: info.complexity.minimumRemaining ?? info.complexity.remaining,
+                },
+            }
+            : {}),
+        ...(Object.keys(endpoints).length > 0 ? { endpoints } : {}),
+    };
+    rateLimitBuffer = rateLimitBuffer
+        ? mergeRateLimitInfo(rateLimitBuffer, observation)
+        : observation;
+}
 export function setRawMode(enabled) {
     rawMode = enabled;
 }
@@ -211,6 +286,7 @@ export function outputSuccess(data) {
     if (quietMode) {
         logger.info(formatLine(output));
         drainWarnings();
+        drainRateLimitInfo();
         drainSummaryFieldWarnings();
         return;
     }
@@ -273,6 +349,10 @@ export function outputSuccess(data) {
     // the signal is visible without breaking the text contract.
     if (outputFormat === "summary") {
         emitSummary(output, inferredKind, fieldsFilter);
+        const rateLimit = drainRateLimitInfo();
+        if (rateLimit) {
+            logger.info(`_rateLimit: ${formatRateLimitInfo(rateLimit)}`);
+        }
         const summaryWarnings = [
             ...drainWarnings(),
             ...drainSummaryFieldWarnings(),
@@ -314,6 +394,22 @@ export function outputSuccess(data) {
             }
         }
     }
+    const rateLimit = drainRateLimitInfo();
+    if (rateLimit) {
+        if (output !== null &&
+            typeof output === "object" &&
+            !Array.isArray(output)) {
+            output = {
+                ...output,
+                _rateLimit: rateLimit,
+            };
+        }
+        else {
+            // A bare array/primitive cannot carry metadata without changing its
+            // contract. Keep stdout machine-readable and surface the quota on stderr.
+            logger.error(`_rateLimit: ${formatRateLimitInfo(rateLimit)}`);
+        }
+    }
     if (jqFilter) {
         const json = JSON.stringify(output);
         // Normalize common shell-escape artifacts (zsh history expansion)
@@ -373,8 +469,51 @@ function drainWarnings() {
     warningBuffer.length = 0;
     return warnings;
 }
+function drainRateLimitInfo() {
+    const rateLimit = rateLimitBuffer;
+    rateLimitBuffer = null;
+    return rateLimit;
+}
+function formatRateLimitInfo(info) {
+    const parts = [];
+    if (info.remaining !== undefined && info.limit !== undefined) {
+        parts.push(`${info.remaining}/${info.limit} requests remaining`);
+    }
+    else if (info.remaining !== undefined) {
+        parts.push(`${info.remaining} requests remaining`);
+    }
+    else if (info.limit !== undefined) {
+        parts.push(`${info.limit} request limit`);
+    }
+    if (info.resetAt) {
+        parts.push(`resets at ${info.resetAt}`);
+    }
+    if ((info.observedRequests ?? 0) > 1) {
+        parts.push(`${info.observedRequests} responses observed`);
+    }
+    if (info.minimumRemaining !== undefined &&
+        info.minimumRemaining !== info.remaining) {
+        parts.push(`minimum ${info.minimumRemaining} requests remaining`);
+    }
+    if (info.complexity?.totalCost !== undefined) {
+        parts.push(`${info.complexity.totalCost} total complexity`);
+    }
+    const endpointEntries = Object.entries(info.endpoints ?? {});
+    if (endpointEntries.length > 0) {
+        parts.push(endpointEntries
+            .map(([name, endpoint]) => {
+            const remaining = endpoint.minimumRemaining ?? endpoint.remaining;
+            return remaining === undefined
+                ? `${name} endpoint observed`
+                : `${name} endpoint minimum ${remaining} remaining`;
+        })
+            .join(", "));
+    }
+    return parts.join("; ");
+}
 export function resetWarnings() {
     warningBuffer.length = 0;
+    rateLimitBuffer = null;
 }
 function outputError(error) {
     // Run the message and stack through sanitizeForLog so a future SDK
@@ -400,7 +539,19 @@ function outputError(error) {
     catch {
         // leave activeProfile as "<unknown>"
     }
-    const payload = JSON.stringify({ error: sanitizeForLog(error.message), activeProfile }, null, 2);
+    // `errorDetail` (DEV-7987) is the classification block: present only
+    // when the failure came from a Linear GraphQL request or its quota admission, absent for
+    // every other error, so nothing about the existing two-key envelope
+    // changes for callers that never looked at it. See the "Error
+    // envelope" section of the README for the published contract.
+    const errorDetail = readGraphQLErrorDetail(error);
+    const rateLimit = drainRateLimitInfo();
+    const payload = JSON.stringify({
+        error: sanitizeForLog(error.message),
+        activeProfile,
+        ...(errorDetail ? { errorDetail } : {}),
+        ...(rateLimit ? { _rateLimit: rateLimit } : {}),
+    }, null, 2);
     // Write to stdout (same channel as success) so machine callers always
     // receive exactly one parseable JSON object regardless of stream capture.
     logger.info(payload);

package/dist/utils/rate-limit-admission.d.ts

@@ -0,0 +1,33 @@
+import type { LinearCredential } from "../auth/linear-credential.js";
+import { LinearGraphQLError } from "./linear-graphql-error.js";
+import type { RateLimitInfo } from "./output.js";
+export interface RateLimitAdmission {
+    readonly enabled: boolean;
+    admit(): Promise<void>;
+    observe(info: RateLimitInfo): Promise<void>;
+}
+/** A local/coordinator quota gate refused before any Linear request was sent. */
+export declare class RateLimitAdmissionRefusal extends LinearGraphQLError {
+    constructor(message: string, resetAt?: string);
+}
+export interface RateLimitAdmissionOptions {
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: CoordinatorFetchLike;
+    now?: () => number;
+    stateRoot?: string;
+}
+type CoordinatorFetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export declare function createRateLimitAdmission(auth: LinearCredential, options?: RateLimitAdmissionOptions): RateLimitAdmission;
+/** Keep local OAuth quota state stable when a profile refreshes its token. */
+export declare function createOAuthProfileRateLimitAdmission(auth: Extract<LinearCredential, {
+    oauthToken: string;
+}>, clientId: string, viewerId?: string): RateLimitAdmission;
+export {};

package/dist/utils/rate-limit-admission.js

@@ -0,0 +1,240 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { atomicWrite, withFileLock } from "../auth/oauth-fs.js";
+import { LinearGraphQLError } from "./linear-graphql-error.js";
+const STATE_VERSION = 1;
+const PROBE_LEASE_MS = 30_000;
+/** A local/coordinator quota gate refused before any Linear request was sent. */
+export class RateLimitAdmissionRefusal extends LinearGraphQLError {
+    constructor(message, resetAt) {
+        super(message, {
+            httpStatus: null,
+            code: "RATELIMITED",
+            retryable: true,
+            resetAt,
+        });
+        this.name = "RateLimitAdmissionRefusal";
+    }
+}
+function parseHeadroom(env) {
+    const raw = env.EL_LINEAR_RATE_LIMIT_HEADROOM?.trim();
+    if (!raw)
+        return 0;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error("EL_LINEAR_RATE_LIMIT_HEADROOM must be a non-negative integer.");
+    }
+    return value;
+}
+function quotaKey(auth, env) {
+    const explicit = env.EL_LINEAR_QUOTA_KEY?.trim();
+    const source = explicit || ("oauthToken" in auth ? auth.oauthToken : auth.apiKey);
+    return createHash("sha256").update(source).digest("hex");
+}
+function coordinatorUrl(env) {
+    const raw = env.EL_LINEAR_RATE_LIMIT_COORDINATOR_URL?.trim();
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error("EL_LINEAR_RATE_LIMIT_COORDINATOR_URL must be a valid URL.");
+    }
+    if (!/^https?:$/.test(parsed.protocol)) {
+        throw new Error("EL_LINEAR_RATE_LIMIT_COORDINATOR_URL must use HTTPS (HTTP is allowed only for loopback development).");
+    }
+    const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+    if (parsed.protocol === "http:" && !loopbackHosts.has(parsed.hostname)) {
+        throw new Error("EL_LINEAR_RATE_LIMIT_COORDINATOR_URL must use HTTPS; bearer credentials may use HTTP only with a loopback host.");
+    }
+    return parsed.toString().replace(/\/$/, "");
+}
+function createCoordinatorAdmission(key, headroom, baseUrl, token, fetchImpl) {
+    const post = async (action, body) => {
+        const response = await fetchImpl(`${baseUrl}/v1/quota/${encodeURIComponent(key)}/${action}`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        const payload = await response.json().catch(() => null);
+        if (!(response.ok || (action === "admit" && response.status === 429))) {
+            throw new Error(`Linear quota coordinator ${action} failed with HTTP ${response.status}.`);
+        }
+        return { status: response.status, payload };
+    };
+    return {
+        enabled: true,
+        async admit() {
+            const result = await post("admit", { headroom, cost: 1 });
+            if (result.status !== 429)
+                return;
+            const state = result.payload?.state;
+            const remaining = state?.remaining ?? 0;
+            const reset = state?.resetAt ? ` until ${state.resetAt}` : "";
+            throw new RateLimitAdmissionRefusal(`Linear rate limit exceeded before request; distributed admission refused: ${remaining} requests remain, preserving configured headroom ${headroom}${reset}.`, state?.resetAt);
+        },
+        async observe(info) {
+            if (info.remaining === undefined)
+                return;
+            await post("observe", {
+                limit: info.limit,
+                remaining: info.remaining,
+                resetAt: info.resetAt,
+            });
+        },
+    };
+}
+function defaultStateRoot(env) {
+    const stateHome = env.XDG_STATE_HOME?.trim() || path.join(os.homedir(), ".local", "state");
+    return path.join(stateHome, "el-linear", "rate-limit");
+}
+async function readState(statePath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(statePath, "utf8"));
+        if (parsed?.v !== STATE_VERSION ||
+            typeof parsed.remaining !== "number" ||
+            typeof parsed.observedAt !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeState(statePath, state) {
+    await fs.mkdir(path.dirname(statePath), { recursive: true, mode: 0o700 });
+    await atomicWrite(statePath, `${JSON.stringify(state)}\n`, 0o600);
+}
+export function createRateLimitAdmission(auth, options = {}) {
+    const env = options.env ?? process.env;
+    const headroom = parseHeadroom(env);
+    if (headroom === 0) {
+        return {
+            enabled: false,
+            admit: async () => { },
+            observe: async () => { },
+        };
+    }
+    const now = options.now ?? Date.now;
+    const key = quotaKey(auth, env);
+    const remote = coordinatorUrl(env);
+    if (remote) {
+        const token = env.EL_LINEAR_RATE_LIMIT_COORDINATOR_TOKEN?.trim();
+        if (!token) {
+            throw new Error("EL_LINEAR_RATE_LIMIT_COORDINATOR_TOKEN is required when the coordinator URL is configured.");
+        }
+        const fetchImpl = options.fetchImpl ??
+            (async (url, init) => {
+                const response = await globalThis.fetch(url, init);
+                return {
+                    ok: response.ok,
+                    status: response.status,
+                    json: () => response.json(),
+                };
+            });
+        return createCoordinatorAdmission(key, headroom, remote, token, fetchImpl);
+    }
+    const statePath = path.join(options.stateRoot ?? defaultStateRoot(env), `${key}.json`);
+    return {
+        enabled: true,
+        async admit() {
+            await fs.mkdir(path.dirname(statePath), { recursive: true, mode: 0o700 });
+            await withFileLock(statePath, async () => {
+                const state = await readState(statePath);
+                const currentTime = now();
+                if (!state) {
+                    await writeState(statePath, {
+                        v: STATE_VERSION,
+                        remaining: headroom,
+                        observedAt: currentTime,
+                        probeUntil: currentTime + PROBE_LEASE_MS,
+                    });
+                    return;
+                }
+                const resetAtMs = state.resetAt
+                    ? Date.parse(state.resetAt)
+                    : Number.NaN;
+                const leaseExpired = state.probeUntil !== undefined && currentTime >= state.probeUntil;
+                if ((Number.isFinite(resetAtMs) && currentTime >= resetAtMs) ||
+                    leaseExpired) {
+                    // Permit exactly one probe into the new window. Closing the local
+                    // gate before releasing the lock prevents every waiting process
+                    // from seeing the same expired state and stampeding the reset.
+                    // Its response headers reopen the gate with authoritative capacity;
+                    // a headerless failure remains pessimistic until the bounded lease
+                    // permits exactly one recovery probe.
+                    await writeState(statePath, {
+                        ...state,
+                        remaining: headroom,
+                        resetAt: undefined,
+                        observedAt: currentTime,
+                        probeUntil: currentTime + PROBE_LEASE_MS,
+                    });
+                    return;
+                }
+                if (state.probeUntil !== undefined) {
+                    throw new RateLimitAdmissionRefusal(`Linear rate limit probe is already in flight; admission refused while preserving configured headroom ${headroom}.`, typeof state.probeUntil === "number"
+                        ? (new Date(state.probeUntil).toJSON() ?? undefined)
+                        : undefined);
+                }
+                if (state.remaining <= headroom) {
+                    const reset = state.resetAt ? ` until ${state.resetAt}` : "";
+                    throw new RateLimitAdmissionRefusal(`Linear rate limit exceeded before request; admission refused: ${state.remaining} requests remain, preserving configured headroom ${headroom}${reset}.`, state.resetAt);
+                }
+                // Reserve one request while holding the process-shared lock. The
+                // response observation will replace this pessimistic estimate with
+                // Linear's authoritative remaining count.
+                await writeState(statePath, {
+                    ...state,
+                    remaining: state.remaining - 1,
+                    observedAt: currentTime,
+                });
+            });
+        },
+        async observe(info) {
+            if (info.remaining === undefined)
+                return;
+            await fs.mkdir(path.dirname(statePath), { recursive: true, mode: 0o700 });
+            await withFileLock(statePath, async () => {
+                const existing = await readState(statePath);
+                const sameWindow = existing?.resetAt !== undefined &&
+                    info.resetAt !== undefined &&
+                    existing.resetAt === info.resetAt;
+                // Concurrent responses can arrive out of order. Within one Linear
+                // window the remaining count only moves downward, so retaining the
+                // lower observation prevents a stale response from refunding quota.
+                const remaining = sameWindow
+                    ? Math.min(existing.remaining, info.remaining)
+                    : info.remaining;
+                await writeState(statePath, {
+                    v: STATE_VERSION,
+                    limit: info.limit,
+                    remaining,
+                    resetAt: info.resetAt,
+                    observedAt: now(),
+                    probeUntil: undefined,
+                });
+            });
+        },
+    };
+}
+/** Keep local OAuth quota state stable when a profile refreshes its token. */
+export function createOAuthProfileRateLimitAdmission(auth, clientId, viewerId) {
+    const quotaKey = viewerId
+        ? `oauth:${clientId}:${viewerId}`
+        : `oauth:${clientId}`;
+    return createRateLimitAdmission(auth, {
+        env: {
+            ...process.env,
+            EL_LINEAR_QUOTA_KEY: process.env.EL_LINEAR_QUOTA_KEY?.trim() || quotaKey,
+        },
+    });
+}

package/package.json

@@ -1,80 +1,80 @@
 {
-  "name": "@enrichlayer/el-linear",
-  "version": "1.44.2",
-  "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",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/main.d.ts",
-      "import": "./dist/main.js"
-    },
-    "./output": {
-      "types": "./dist/output.d.ts",
-      "import": "./dist/output.js",
-      "default": "./dist/output.js"
-    }
-  },
-  "sideEffects": false,
-  "bin": {
-    "el-linear": "dist/main.js"
-  },
-  "files": [
-    "dist/",
-    "claude-skills/",
-    "LICENSE",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/enrichlayer/el-linear.git"
-  },
-  "homepage": "https://enrichlayer.com/tools/el-linear",
-  "bugs": {
-    "url": "https://github.com/enrichlayer/el-linear/issues"
-  },
-  "keywords": [
-    "linear",
-    "linear.app",
-    "cli",
-    "issue-tracker",
-    "graphql",
-    "claude",
-    "claude-code"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@inquirer/prompts": "^8.4.2",
-    "@linear/sdk": "^88.0.0",
-    "commander": "^15.0.0",
-    "picocolors": "^1.1.1"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.14",
-    "@types/node": "^26.0.0",
-    "graphql": "^17.0.1",
-    "tsx": "^4.21.0",
-    "typescript": "^6.0.3",
-    "vitest": "^4.0.18"
-  },
-  "optionalDependencies": {
-    "@sentry/node": "^10.50.0"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json && chmod +x dist/main.js",
-    "clean": "rm -rf dist/",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check .",
-    "lint:fix": "biome check --fix .",
-    "start": "tsx src/main.ts",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  }
-}
+	"name": "@enrichlayer/el-linear",
+	"version": "1.46.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",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/main.d.ts",
+			"import": "./dist/main.js"
+		},
+		"./output": {
+			"types": "./dist/output.d.ts",
+			"import": "./dist/output.js",
+			"default": "./dist/output.js"
+		}
+	},
+	"sideEffects": false,
+	"bin": {
+		"el-linear": "dist/main.js"
+	},
+	"files": [
+		"dist/",
+		"claude-skills/",
+		"LICENSE",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json && chmod +x dist/main.js",
+		"clean": "rm -rf dist/",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"lint:fix": "biome check --fix .",
+		"start": "tsx src/main.ts",
+		"test": "vitest run",
+		"test:watch": "vitest"
+	},
+	"engines": {
+		"node": ">=22.0.0"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/enrichlayer/el-linear.git"
+	},
+	"homepage": "https://enrichlayer.com/tools/el-linear",
+	"bugs": {
+		"url": "https://github.com/enrichlayer/el-linear/issues"
+	},
+	"keywords": [
+		"linear",
+		"linear.app",
+		"cli",
+		"issue-tracker",
+		"graphql",
+		"claude",
+		"claude-code"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@inquirer/prompts": "^8.4.2",
+		"@linear/sdk": "^88.0.0",
+		"commander": "^15.0.0",
+		"graphql": "^17.0.1",
+		"picocolors": "^1.1.1"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.14",
+		"@types/node": "^26.0.0",
+		"tsx": "^4.21.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.0.18"
+	},
+	"optionalDependencies": {
+		"@sentry/node": "^10.50.0"
+	}
+}