@enrichlayer/el-linear 1.41.1 → 1.42.0

package/dist/config/config.d.ts

@@ -36,6 +36,31 @@ export interface ElLinearConfig {
     };
     teamAliases: Record<string, string>;
     teams: Record<string, string>;
+    /**
+     * Optional identity-resolver hook (DEV-5628). `resolver` is an argv array —
+     * el-linear appends the identifier as the final element and reads a Linear
+     * user UUID off stdout:
+     *
+     *   "identity": { "resolver": ["el-identity", "resolve"] }
+     *
+     * Use it when your org has a people registry that knows things Linear does
+     * not (that `jd` is a person; that a GitLab handle and a Linear handle are one human).
+     *
+     * It is a COMMAND rather than a URL + credentials on purpose: el-linear is
+     * MIT and most installs are not ours, so it must not bake in anybody's auth
+     * scheme. The credential lives entirely inside whatever you point this at —
+     * Vault, Infisical, 1Password, a plain env var, SSO. Adding a backend is
+     * writing a different script, not patching this package.
+     *
+     * Entirely optional and fail-open: unconfigured, or on any failure,
+     * resolution falls through to Linear's own user lookup exactly as before.
+     * See `identity-resolver.ts` for the output contract.
+     */
+    identity?: {
+        resolver?: string[];
+        /** Milliseconds before the resolver is treated as a miss (default 8000). */
+        resolverTimeoutMs?: number;
+    };
     /**
      * Term-enforcement rules. Each rule has a canonical form and a list of
      * rejected forms; rejected forms in issue titles/descriptions are flagged

package/dist/config/config.js

@@ -139,6 +139,21 @@ export function loadConfig() {
         : {};
     // teamConfigPath inside a team config file would be circular; strip it.
     delete teamRaw.teamConfigPath;
+    // `identity.resolver` names a BINARY el-linear will spawn. The team layer is
+    // data, not code: it arrives from a different repository via `git pull` (or,
+    // for an OSS user, from whatever repo they pointed `teamConfigPath` at), and
+    // nobody reviews a config file expecting it to hand them a subprocess. Letting
+    // it choose the executable would turn "clone this repo and run el-linear" into
+    // arbitrary code execution on every `--assignee` resolution.
+    //
+    // So the resolver is honored ONLY from the personal config (or the env var) —
+    // files the operator owns. Same reasoning as teamConfigPath above, which is
+    // stripped for the same "the team layer doesn't get to decide this" reason.
+    //
+    // An organization that wants to ship a resolver to its developers writes it
+    // into their personal config at setup time; that keeps the decision with the
+    // machine's owner instead of with whoever can land a commit upstream.
+    delete teamRaw.identity;
     // Merge order: defaults → team config → personal config.
     // Arrays (terms, defaultLabels, etc.) are concatenated so personal entries
     // extend team entries rather than replace them.

package/dist/config/identity-resolver.d.ts

@@ -0,0 +1,40 @@
+import type { ElLinearConfig } from "./config.js";
+/** Test seam — the memo would otherwise leak between cases in one vitest process. */
+export declare function clearResolverMemoForTests(): void;
+/**
+ * The configured resolver argv, or `null` when the hook is off.
+ *
+ * Env wins over config so a single invocation can point at a different resolver
+ * (or disable one) without editing files: `EL_LINEAR_IDENTITY_RESOLVER=""` is an
+ * explicit off switch.
+ */
+export declare function resolverCommand(config: Pick<ElLinearConfig, "identity">, env?: NodeJS.ProcessEnv): string[] | null;
+/** True when an identity resolver is configured (env or config). */
+export declare function isResolverConfigured(config: Pick<ElLinearConfig, "identity">, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Pull a Linear user UUID out of whatever the resolver printed.
+ *
+ * Deliberately generous about the shape, because the point of this hook is that
+ * anyone can write the resolver — demanding one exact JSON envelope would make
+ * the "just shell out to your own script" promise a lie. Accepted:
+ *
+ *   - a bare UUID:                     `3f2a…`
+ *   - `{"linearId": "3f2a…"}`     (the el-identity record shape)
+ *   - `{"data": {"linearId": "…"}}`    (an el-* CLI `{data, meta}` envelope)
+ *   - `{"id": "3f2a…"}`           (the obvious alternative spelling)
+ *
+ * Anything else — including a *non*-UUID string, which is the shape a confused
+ * resolver most plausibly emits — is a miss. We would rather fall through to
+ * Linear's own lookup than hand a bogus id to the API and produce an opaque
+ * "Argument Validation Error" (the DEV-4312 failure, in a new costume).
+ */
+export declare function parseResolverOutput(stdout: string): string | null;
+/**
+ * Run the configured resolver for `identifier`. Returns the Linear user UUID, or
+ * `null` on any miss/failure. Never throws.
+ *
+ * Synchronous (`spawnSync`) on purpose: resolution sits on the critical path of
+ * `--assignee` for a short-lived CLI, the callers are already `async` so nothing
+ * is starved, and it keeps the failure modes to exactly one place.
+ */
+export declare function resolveViaCommand(identifier: string, config: Pick<ElLinearConfig, "identity">, env?: NodeJS.ProcessEnv): string | null;

package/dist/config/identity-resolver.js

@@ -0,0 +1,253 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Optional **identity resolver hook** (DEV-5628).
+ *
+ * Some organizations keep a people registry that knows things Linear does not:
+ * that `jd` is a person, that a GitLab handle and a Linear handle belong to the
+ * same human. el-linear can consult it — but it must never learn *how* to reach it.
+ *
+ * So the hook is a **command**, not an HTTP client:
+ *
+ *   identity.resolver = ["el-identity", "resolve"]
+ *
+ * el-linear appends the identifier as the final argv element, runs the command,
+ * and reads a Linear user UUID off stdout. That is the entire contract.
+ *
+ * Why a command rather than a URL + credentials (which is what
+ * `registry-resolve.ts` does, and why that path stayed dormant): el-linear is
+ * MIT and published on npm. Most installs are not Enrich Layer. Baking in an
+ * auth scheme means baking in *somebody's* auth scheme — and the moment we did,
+ * the next organization would need Infisical, or 1Password, or a plain env var,
+ * or SSO. A command has no such problem: the credential lives entirely inside
+ * whatever the operator points this at. Adding a new secret backend is writing a
+ * different script, not patching this package.
+ *
+ * The command is trusted (the operator configured it) but the *identifier* is
+ * not, so it is passed as an argv element with `shell: false` — a name like
+ * `"; rm -rf /"` is an argument, never a command.
+ *
+ * Fail-open by design: unconfigured, a miss, a non-zero exit, a timeout, an
+ * unparseable answer, or a missing binary all return `null`, and the caller
+ * falls through to Linear's own user lookup (which resolves names and emails
+ * perfectly well — see `LinearService.resolveUserId`). This hook is an
+ * *enhancement*, so a broken resolver must degrade to plain el-linear rather
+ * than break every command. It never throws.
+ */
+/** Env override — a whitespace-separated command, e.g. `el-identity resolve`. */
+const RESOLVER_ENV = "EL_LINEAR_IDENTITY_RESOLVER";
+/** A resolver that hasn't answered in this long is not going to. */
+const DEFAULT_TIMEOUT_MS = 8000;
+/**
+ * Per-process memo. A single command can resolve the same person several times —
+ * `--subscriber a,b,a`, or an assignee who is also a subscriber — and each miss
+ * costs a full subprocess round-trip (seconds, against a network-backed
+ * resolver). Nothing here is cached across processes: el-linear is short-lived,
+ * and a stale identity cache on disk is exactly the drift this hook exists to
+ * remove.
+ */
+const memo = new Map();
+/** Test seam — the memo would otherwise leak between cases in one vitest process. */
+export function clearResolverMemoForTests() {
+    memo.clear();
+}
+/**
+ * Resolve the effective timeout.
+ *
+ * `?? DEFAULT` is not enough: Node treats `timeout <= 0` as *no timeout*, and `0`
+ * is the most natural thing to type when you mean "off". That would turn the
+ * documented fail-open contract into an unkillable hang inside a synchronous
+ * call — the one failure mode the surrounding try/catch cannot save you from.
+ */
+function resolveTimeoutMs(config) {
+    const configured = config.identity?.resolverTimeoutMs;
+    return typeof configured === "number" && configured > 0
+        ? configured
+        : DEFAULT_TIMEOUT_MS;
+}
+/**
+ * The environment handed to the resolver.
+ *
+ * It inherits the ambient env on purpose — reaching its own secret backend
+ * (Vault, Infisical, 1Password, a plain env var) is the entire point, so
+ * scrubbing wholesale would defeat the design. But the resolver has no business
+ * with *Linear's* token: it resolves people, it never talks to Linear. Dropping
+ * it keeps the CLI's most sensitive secret out of the blast radius of a
+ * compromised — or merely over-logging — resolver.
+ */
+function resolverEnv(env) {
+    const { LINEAR_API_TOKEN: _dropped, ...rest } = env;
+    return rest;
+}
+/**
+ * Debug-gated diagnosis. Every failure here is a silent `null` by design, which
+ * is right for the user but miserable for the operator whose resolver is broken:
+ * all they see is an unexplained pause. `EL_LINEAR_DEBUG=1` is this repo's
+ * existing convention for "tell me what actually happened", and stderr never
+ * corrupts the JSON on stdout.
+ */
+function debugMiss(reason, env) {
+    if (!env.EL_LINEAR_DEBUG)
+        return;
+    process.stderr.write(`el-linear: identity resolver miss — ${reason}\n`);
+}
+/**
+ * The configured resolver argv, or `null` when the hook is off.
+ *
+ * Env wins over config so a single invocation can point at a different resolver
+ * (or disable one) without editing files: `EL_LINEAR_IDENTITY_RESOLVER=""` is an
+ * explicit off switch.
+ */
+export function resolverCommand(config, env = process.env) {
+    const fromEnv = env[RESOLVER_ENV];
+    if (fromEnv !== undefined) {
+        const argv = fromEnv.trim().split(/\s+/).filter(Boolean);
+        return argv.length > 0 ? argv : null;
+    }
+    const configured = config.identity?.resolver;
+    if (!configured || configured.length === 0) {
+        return null;
+    }
+    return configured;
+}
+/** True when an identity resolver is configured (env or config). */
+export function isResolverConfigured(config, env = process.env) {
+    return resolverCommand(config, env) !== null;
+}
+/**
+ * Pull a Linear user UUID out of whatever the resolver printed.
+ *
+ * Deliberately generous about the shape, because the point of this hook is that
+ * anyone can write the resolver — demanding one exact JSON envelope would make
+ * the "just shell out to your own script" promise a lie. Accepted:
+ *
+ *   - a bare UUID:                     `3f2a…`
+ *   - `{"linearId": "3f2a…"}`     (the el-identity record shape)
+ *   - `{"data": {"linearId": "…"}}`    (an el-* CLI `{data, meta}` envelope)
+ *   - `{"id": "3f2a…"}`           (the obvious alternative spelling)
+ *
+ * Anything else — including a *non*-UUID string, which is the shape a confused
+ * resolver most plausibly emits — is a miss. We would rather fall through to
+ * Linear's own lookup than hand a bogus id to the API and produce an opaque
+ * "Argument Validation Error" (the DEV-4312 failure, in a new costume).
+ */
+export function parseResolverOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (UUID_RE.test(trimmed)) {
+        return trimmed;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    const candidate = pickLinearId(parsed);
+    return candidate && UUID_RE.test(candidate) ? candidate : null;
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function pickLinearId(parsed) {
+    if (typeof parsed === "string") {
+        return parsed;
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return null;
+    }
+    const obj = parsed;
+    for (const key of ["linearId", "id"]) {
+        const value = obj[key];
+        if (typeof value === "string") {
+            return value;
+        }
+    }
+    // One level of `{data: …}` unwrapping — the el-* CLI envelope.
+    if (obj.data && typeof obj.data === "object") {
+        return pickLinearId(obj.data);
+    }
+    return null;
+}
+/**
+ * Run the configured resolver for `identifier`. Returns the Linear user UUID, or
+ * `null` on any miss/failure. Never throws.
+ *
+ * Synchronous (`spawnSync`) on purpose: resolution sits on the critical path of
+ * `--assignee` for a short-lived CLI, the callers are already `async` so nothing
+ * is starved, and it keeps the failure modes to exactly one place.
+ */
+export function resolveViaCommand(identifier, config, env = process.env) {
+    const argv = resolverCommand(config, env);
+    if (!argv) {
+        return null;
+    }
+    const [command, ...args] = argv;
+    if (!command) {
+        return null;
+    }
+    // A leading `-` is never a valid Linear identifier, but it IS a flag to the
+    // resolver's own option parser — `--assignee "--output=/tmp/x"` would be
+    // presented to it as one. There is no shell escape here (argv, not a shell),
+    // but el-linear is increasingly driven by agents over untrusted issue text, so
+    // close the class for free rather than trust every resolver to be careful.
+    if (identifier.startsWith("-")) {
+        debugMiss(`refusing flag-shaped identifier "${identifier}"`, env);
+        return null;
+    }
+    const cached = memo.get(identifier);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const resolved = spawnResolver(command, args, identifier, config, env);
+    memo.set(identifier, resolved);
+    return resolved;
+}
+function spawnResolver(command, args, identifier, config, env) {
+    try {
+        const result = spawnSync(command, [...args, identifier], {
+            encoding: "utf8",
+            timeout: resolveTimeoutMs(config),
+            // `spawnSync` waits for the child to fully exit after its timeout. Its
+            // default kill signal is SIGTERM, which a broken resolver can trap or
+            // ignore forever — defeating this hook's fail-open timeout. The resolver
+            // is an isolated lookup helper, so force it down when its time budget is
+            // exhausted rather than letting it wedge the whole CLI.
+            killSignal: "SIGKILL",
+            // The identifier is untrusted input; never hand it to a shell. This also
+            // means a Windows npm shim (`el-identity.cmd`) will NOT be found — see
+            // the Windows note in docs/configuration.md. Turning `shell: true` on to
+            // fix that would hand the untrusted identifier to cmd.exe, which is a
+            // far worse trade.
+            shell: false,
+            // stdin closed: a resolver that decides to prompt must not hang the CLI.
+            stdio: ["ignore", "pipe", "pipe"],
+            env: resolverEnv(env),
+        });
+        // BOTH conditions are load-bearing; do not "simplify" this to one.
+        //   - a plain timeout      → error ETIMEDOUT, status null
+        //   - a maxBuffer overflow → error ENOBUFS,   status null
+        //   - a child that leaves a grandchild holding the stdout pipe
+        //                          → error ETIMEDOUT, status **0**
+        // Checking only `status` would let that last case through as a success and
+        // parse whatever partial output happened to be buffered.
+        if (result.error) {
+            debugMiss(`${command}: ${result.error.message}`, env);
+            return null;
+        }
+        if (result.status !== 0) {
+            const stderr = (result.stderr ?? "").trim().split("\n")[0] ?? "";
+            debugMiss(`${command} exited ${result.status}${stderr ? `: ${stderr}` : ""}`, env);
+            return null;
+        }
+        const parsed = parseResolverOutput(result.stdout ?? "");
+        if (!parsed) {
+            debugMiss(`${command} printed no usable Linear UUID for "${identifier}"`, env);
+        }
+        return parsed;
+    }
+    catch (err) {
+        debugMiss(err instanceof Error ? err.message : String(err), env);
+        return null;
+    }
+}

package/dist/config/resolver.d.ts

@@ -14,14 +14,29 @@ export declare function resolveMember(input: string): string;
  */
 export declare function resolveAssignee(input: string, rootOpts: Record<string, unknown>): Promise<string>;
 /**
- * Resolve a member identifier (alias / handle / name) to a UUID, consulting the
- * opt-in identity registry first when configured, then the bundled config
- * (`resolveMember`). The shared async resolution path behind `--assignee` and
- * `--delegate` (DEV-4871 / DEV-4872).
+ * Resolve a member identifier (alias / handle / name) to a UUID. The shared
+ * async resolution path behind `--assignee` and `--delegate` (DEV-4871 /
+ * DEV-4872 / DEV-5628).
  *
- * EL-only and env-gated on `EL_IDENTITY_URL`; fail-open — when unconfigured, on
- * a miss, or on any failure it falls back to config, so a non-EL install and an
- * unreachable registry both behave exactly as before. Never throws.
+ * Order, most authoritative first:
+ *
+ *   1. **The identity-resolver hook** (`identity.resolver`, DEV-5628) — an
+ *      operator-supplied command. This is the one to reach for: it can answer
+ *      for aliases and cross-system handles Linear has never heard of, and it
+ *      owns its own credentials, so el-linear carries no auth scheme.
+ *   2. **The HTTP registry** (`EL_IDENTITY_URL`, DEV-4871) — the older,
+ *      env-gated path. Superseded by (1), which needs no URL or CF-Access
+ *      credentials in the environment. Kept because it ships and someone may
+ *      rely on it.
+ *   3. **The bundled config** (`resolveMember`) — a local lookup table.
+ *
+ * All three are optional. With none of them, `resolveMember` hands the raw input
+ * back and Linear's own user lookup resolves it (`LinearService.resolveUserId`
+ * matches email → displayName → name), which is why an install with no config at
+ * all still works.
+ *
+ * Fail-open throughout: a miss or a failure at any layer falls through to the
+ * next. Never throws.
  */
 export declare function resolveMemberWithRegistry(input: string): Promise<string>;
 /**

package/dist/config/resolver.js

@@ -2,6 +2,7 @@ import { createGraphQLService } from "../utils/graphql-service.js";
 import { outputWarning } from "../utils/output.js";
 import { isUuid, isUuidPrefix } from "../utils/uuid.js";
 import { loadConfig } from "./config.js";
+import { resolveViaCommand } from "./identity-resolver.js";
 import { isRegistryConfigured, resolveViaRegistry, } from "./registry-resolve.js";
 /**
  * Resolve a team key/name/alias to its UUID.
@@ -102,16 +103,39 @@ export async function resolveAssignee(input, rootOpts) {
     return resolveMemberWithRegistry(input);
 }
 /**
- * Resolve a member identifier (alias / handle / name) to a UUID, consulting the
- * opt-in identity registry first when configured, then the bundled config
- * (`resolveMember`). The shared async resolution path behind `--assignee` and
- * `--delegate` (DEV-4871 / DEV-4872).
+ * Resolve a member identifier (alias / handle / name) to a UUID. The shared
+ * async resolution path behind `--assignee` and `--delegate` (DEV-4871 /
+ * DEV-4872 / DEV-5628).
  *
- * EL-only and env-gated on `EL_IDENTITY_URL`; fail-open — when unconfigured, on
- * a miss, or on any failure it falls back to config, so a non-EL install and an
- * unreachable registry both behave exactly as before. Never throws.
+ * Order, most authoritative first:
+ *
+ *   1. **The identity-resolver hook** (`identity.resolver`, DEV-5628) — an
+ *      operator-supplied command. This is the one to reach for: it can answer
+ *      for aliases and cross-system handles Linear has never heard of, and it
+ *      owns its own credentials, so el-linear carries no auth scheme.
+ *   2. **The HTTP registry** (`EL_IDENTITY_URL`, DEV-4871) — the older,
+ *      env-gated path. Superseded by (1), which needs no URL or CF-Access
+ *      credentials in the environment. Kept because it ships and someone may
+ *      rely on it.
+ *   3. **The bundled config** (`resolveMember`) — a local lookup table.
+ *
+ * All three are optional. With none of them, `resolveMember` hands the raw input
+ * back and Linear's own user lookup resolves it (`LinearService.resolveUserId`
+ * matches email → displayName → name), which is why an install with no config at
+ * all still works.
+ *
+ * Fail-open throughout: a miss or a failure at any layer falls through to the
+ * next. Never throws.
  */
 export async function resolveMemberWithRegistry(input) {
+    // UUIDs are already canonical — don't spend a subprocess on them.
+    if (isUuid(input)) {
+        return input;
+    }
+    const viaCommand = resolveViaCommand(input, loadConfig());
+    if (viaCommand) {
+        return viaCommand;
+    }
     if (isRegistryConfigured()) {
         const viaRegistry = await resolveViaRegistry(input);
         if (viaRegistry) {

package/dist/utils/graphql-issues-service.js

@@ -1,3 +1,5 @@
+import { loadConfig } from "../config/config.js";
+import { resolveViaCommand } from "../config/identity-resolver.js";
 import { isRegistryConfigured, resolveViaRegistry, } from "../config/registry-resolve.js";
 import { resolveUserDisplayName } from "../config/resolver.js";
 import { ARCHIVE_ISSUE_MUTATION, BATCH_GET_ISSUES_QUERY, BATCH_RESOLVE_FOR_CREATE_QUERY, BATCH_RESOLVE_FOR_SEARCH_QUERY, BATCH_RESOLVE_FOR_UPDATE_QUERY, buildResolveLabelsByNameQuery, CREATE_ISSUE_MUTATION, DELETE_ISSUE_MUTATION, FILTERED_SEARCH_ISSUES_QUERY, GET_ISSUE_BY_ID_QUERY, GET_ISSUE_BY_IDENTIFIER_QUERY, GET_ISSUE_CLAIM_CONTEXT_QUERY, GET_ISSUE_START_CONTEXT_QUERY, GET_ISSUE_TEAM_QUERY, GET_ISSUES_QUERY, SEARCH_ISSUES_QUERY, TEAM_SCOPED_FILTERED_ISSUES_QUERY, TEAM_STARTED_STATUSES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
@@ -1116,9 +1118,15 @@ export class GraphQLIssuesService {
         if (!assigneeId || isUuid(assigneeId)) {
             return assigneeId;
         }
-        // Opt-in registry resolution (DEV-4872): try the identity registry first,
-        // falling back to the Linear-API user lookup below on a miss. EL-only,
-        // env-gated, fail-open — a non-EL install never reaches the network here.
+        // Opt-in identity resolution, falling back to the Linear-API user lookup
+        // below on a miss. Both layers are optional and fail-open — an install
+        // with neither configured never reaches the network here.
+        //   1. The resolver-command hook (DEV-5628) — brings its own credentials.
+        //   2. The older env-gated HTTP registry (DEV-4872).
+        const viaCommand = resolveViaCommand(assigneeId, loadConfig());
+        if (viaCommand) {
+            return viaCommand;
+        }
         if (isRegistryConfigured()) {
             const viaRegistry = await resolveViaRegistry(assigneeId);
             if (viaRegistry) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.41.1",
+  "version": "1.42.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",