@enrichlayer/el-linear 1.29.0 → 1.30.0

package/claude-skills/linear-operations/SKILL.md

@@ -352,6 +352,27 @@ el-linear comments create ENG-123 --body "cc @alice — Bob can you review?" 2>&
 
 Works in comments only (not descriptions).
 
+### Confirming a mention fired (the `mentions` output field)
+
+A real mention lives in the comment's structured `bodyData`, not in the markdown — so a comment whose body reads `@alice` may or may not have actually pinged anyone. **Don't guess: read the `mentions` field** that `comments create|update` attach to their output (the sibling of `autoLinked`):
+
+```jsonc
+{
+  "id": "…",
+  "mentions": {
+    "resolved":   [{ "label": "alice", "userId": "…" }],  // real notifications sent
+    "unresolved": ["bobby"],                                // explicit @names that matched nobody
+    "delivered":  true                                      // false ⇒ Linear rejected bodyData, fell back to plain text
+  }
+}
+```
+
+- An **unresolved** explicit `@name` (typo or unknown handle) is left as plain text — **no notification** — and el-linear prints a loud `⚠ @name did not resolve …` warning to **stderr**. Fix the name and re-comment; never assume the ping landed.
+- `delivered: false` means the structured body was rejected and the comment shipped as plain markdown, so the resolved mentions did **not** fire — also warned on stderr.
+- Under `--quiet`, the stdout stays the one-line `comment <id>`; the `mentions: resolved=[…] unresolved=[…]` confirmation is echoed to **stderr**.
+
+This makes "a real @mention" a verifiable, deterministic convention rather than a hope ([DEV-4987](https://linear.app/verticalint/issue/DEV-4987/)).
+
 ---
 
 ## CLI Syntax Rules

package/dist/commands/comments.js

@@ -7,8 +7,9 @@ import { createGraphQLService, } from "../utils/graphql-service.js";
 import { extractIssueReferences } from "../utils/issue-reference-extractor.js";
 import { wrapIssueReferencesAsLinks } from "../utils/issue-reference-wrapper.js";
 import { createLinearService, } from "../utils/linear-service.js";
-import { resolveMentions } from "../utils/mention-resolver.js";
-import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { logger } from "../utils/logger.js";
+import { resolveMentions, } from "../utils/mention-resolver.js";
+import { getQuietMode, handleAsyncCommand, outputSuccess, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { validateReferences } from "../utils/validate-references.js";
 import { parsePositiveInt } from "../utils/validators.js";
@@ -17,6 +18,54 @@ import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
 // tweak on their side doesn't silently regress the fallback path.
 const BODY_DATA_ERROR_RE = /prosemirror|bodydata|invalid.*body/i;
 const ISSUE_IDENTIFIER_REGEX = /^[A-Z][A-Z0-9]*-\d+$/;
+/**
+ * Turn a {@link MentionReport} into the `mentions` output field, or `undefined`
+ * when there is nothing to report. `delivered=false` records a bodyData→plain
+ * fallback so the JSON output never falsely claims a ping was sent.
+ */
+function buildMentionsOutput(report, delivered) {
+    if (!report) {
+        return undefined;
+    }
+    if (report.resolved.length === 0 && report.unresolvedExplicit.length === 0) {
+        return undefined;
+    }
+    return {
+        resolved: report.resolved.map((m) => ({
+            label: m.label,
+            userId: m.userId,
+        })),
+        unresolved: report.unresolvedExplicit,
+        delivered,
+    };
+}
+/**
+ * Emit the human-facing side of mention resolution to **stderr** (so it never
+ * pollutes the machine-stable stdout line, and survives `--quiet`):
+ *   - a loud warning for each explicit `@name` that resolved to nobody,
+ *   - a warning when a bodyData rejection dropped resolved mentions,
+ *   - under `--quiet`, a one-line confirmation of what resolved (since the
+ *     quiet stdout line can't carry the `mentions` field).
+ */
+function reportMentions(mentions) {
+    if (!mentions) {
+        return;
+    }
+    for (const name of mentions.unresolved) {
+        logger.error(`⚠ @${name} did not resolve to a team member — left as plain text (no notification sent)`);
+    }
+    if (!mentions.delivered && mentions.resolved.length > 0) {
+        logger.error(`⚠ Linear rejected the structured comment body; fell back to plain text — ${mentions.resolved.length} mention(s) were NOT delivered as notifications`);
+    }
+    // In quiet mode stdout is a single `comment <id>` line with no room for the
+    // `mentions` field, so echo a concise confirmation to stderr.
+    if (getQuietMode()) {
+        const resolved = mentions.delivered
+            ? mentions.resolved.map((m) => `${m.label}→${m.userId}`).join(", ")
+            : "(none delivered)";
+        logger.error(`mentions: resolved=[${resolved}] unresolved=[${mentions.unresolved.join(", ")}]`);
+    }
+}
 function readBody(options) {
     // --body and --body-file are two sources for the same field; accepting both
     // would silently drop one. Reject up front (DEV-4450) — the same mutual-
@@ -130,12 +179,15 @@ async function handleCreateComment(issueId, options, command) {
         selfUserId,
     });
     const input = { issueId: resolvedIssueId };
-    if (mentionResult) {
+    if (mentionResult?.bodyData) {
         input.bodyData = mentionResult.bodyData;
     }
     else {
         input.body = body;
     }
+    // Tracks whether resolved mentions actually shipped as structured nodes;
+    // flipped to false if the bodyData fallback below sends plain text instead.
+    let mentionsDelivered = true;
     let result;
     try {
         result = await graphQLService.rawRequest(CREATE_COMMENT_MUTATION, { input });
@@ -146,6 +198,7 @@ async function handleCreateComment(issueId, options, command) {
         // Linear handle the conversion server-side.
         const msg = err instanceof Error ? err.message : String(err);
         if (input.bodyData && BODY_DATA_ERROR_RE.test(msg)) {
+            mentionsDelivered = false;
             const fallbackInput = {
                 issueId: resolvedIssueId,
                 body,
@@ -179,7 +232,13 @@ async function handleCreateComment(issueId, options, command) {
         linearService,
     });
     const output = transformComment(mutation.comment);
-    outputSuccess(autoLinked ? { ...output, autoLinked } : output);
+    const mentions = buildMentionsOutput(mentionResult, mentionsDelivered);
+    reportMentions(mentions);
+    outputSuccess({
+        ...output,
+        ...(autoLinked ? { autoLinked } : {}),
+        ...(mentions ? { mentions } : {}),
+    });
 }
 async function handleUpdateComment(commentId, options, command) {
     const rootOpts = getRootOpts(command);
@@ -196,12 +255,13 @@ async function handleUpdateComment(commentId, options, command) {
         selfUserId,
     });
     const input = {};
-    if (mentionResult) {
+    if (mentionResult?.bodyData) {
         input.bodyData = mentionResult.bodyData;
     }
     else {
         input.body = body;
     }
+    let mentionsDelivered = true;
     let result;
     try {
         result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, { id: commentId, input });
@@ -217,6 +277,7 @@ async function handleUpdateComment(commentId, options, command) {
         // extraction; copy-then-refactor on the third per the repo convention.
         const msg = err instanceof Error ? err.message : String(err);
         if (input.bodyData && BODY_DATA_ERROR_RE.test(msg)) {
+            mentionsDelivered = false;
             const fallbackInput = { body };
             result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, { id: commentId, input: fallbackInput });
         }
@@ -243,7 +304,13 @@ async function handleUpdateComment(commentId, options, command) {
         });
     }
     const output = transformComment(comment);
-    outputSuccess(autoLinked ? { ...output, autoLinked } : output);
+    const mentions = buildMentionsOutput(mentionResult, mentionsDelivered);
+    reportMentions(mentions);
+    outputSuccess({
+        ...output,
+        ...(autoLinked ? { autoLinked } : {}),
+        ...(mentions ? { mentions } : {}),
+    });
 }
 async function handleListComments(issueId, options, command) {
     const rootOpts = getRootOpts(command);

package/dist/commands/issues/tree.js

@@ -18,6 +18,7 @@
  * connection has no top-level state filter).
  */
 import { buildIssueTreeQuery, DEFAULT_TREE_DEPTH, MAX_TREE_DEPTH, } from "../../queries/issue-tree.js";
+import { TERMINAL_STATE_TYPES } from "../../types/linear.js";
 import { formatTree } from "../../utils/format-tree.js";
 import { createIssuesService } from "../../utils/issues-service-bootstrap.js";
 import { handleAsyncCommand, outputSuccess } from "../../utils/output.js";
@@ -74,10 +75,11 @@ function parseDepth(raw) {
     return n;
 }
 /**
- * Walk the tree depth-first and drop any node whose `state.type` is
- * `completed` or `canceled`. Pure function — does not mutate the input.
- * A pruned child takes its entire subtree with it (consistent with how
- * `issues list --no-include-closed` excludes closed work entirely).
+ * Walk the tree depth-first and drop any node whose `state.type` is terminal
+ * (`completed` / `canceled` / `duplicate` — `TERMINAL_STATE_TYPES`, DEV-4879).
+ * Pure function — does not mutate the input. A pruned child takes its entire
+ * subtree with it (consistent with how `issues list --no-include-closed`
+ * excludes closed work entirely — same shared constant).
  *
  * Assumes Linear's parent → children graph stays single-parent (a tree,
  * not a DAG). If Linear ever ships multi-parent issues, this recursion
@@ -97,6 +99,5 @@ function pruneTerminalStates(root) {
     };
 }
 function isTerminalState(node) {
-    const t = node.state?.type;
-    return t === "completed" || t === "canceled";
+    return TERMINAL_STATE_TYPES.includes(node.state?.type ?? "");
 }

package/dist/types/linear.d.ts

@@ -35,6 +35,17 @@ interface StateRef {
      */
     type?: string;
 }
+/**
+ * Workflow-state types treated as terminal / closed for default filtering.
+ * `issues list` / `issues search` exclude these unless `--include-closed` (or
+ * an explicit `--status`) is passed (DEV-4478).
+ *
+ * `duplicate` is included (DEV-4879) because this workspace parks resolved
+ * duplicates in a `duplicate`-typed state — they carry a `duplicate-of`
+ * relation and are semantically closed, so they must not leak into the default
+ * open-issues view the way `completed` / `canceled` don't.
+ */
+export declare const TERMINAL_STATE_TYPES: readonly string[];
 interface ProjectRef {
     id: string;
     name: string;

package/dist/types/linear.js

@@ -3,4 +3,18 @@
  * These represent the public API surface — GraphQL responses are
  * transformed into these shapes at the service boundary.
  */
-export {};
+/**
+ * Workflow-state types treated as terminal / closed for default filtering.
+ * `issues list` / `issues search` exclude these unless `--include-closed` (or
+ * an explicit `--status`) is passed (DEV-4478).
+ *
+ * `duplicate` is included (DEV-4879) because this workspace parks resolved
+ * duplicates in a `duplicate`-typed state — they carry a `duplicate-of`
+ * relation and are semantically closed, so they must not leak into the default
+ * open-issues view the way `completed` / `canceled` don't.
+ */
+export const TERMINAL_STATE_TYPES = [
+    "completed",
+    "canceled",
+    "duplicate",
+];

package/dist/utils/format-tree.js

@@ -10,6 +10,7 @@
  * Pure rendering — does not fetch or filter. The depth bound and the
  * terminal-state exclusion are enforced by the caller before this runs.
  */
+import { TERMINAL_STATE_TYPES } from "../types/linear.js";
 const BRANCH_TEE = "├── ";
 const BRANCH_END = "└── ";
 const VERTICAL = "│   ";
@@ -40,7 +41,7 @@ function formatStateSuffix(state) {
     // Only annotate terminal-typed states; the renderer is otherwise
     // state-name-agnostic so workspace-custom workflow states (e.g. "In
     // Review") don't get a noisy suffix.
-    if (state.type === "completed" || state.type === "canceled") {
+    if (TERMINAL_STATE_TYPES.includes(state.type)) {
         return ` [${state.name}]`;
     }
     return "";

package/dist/utils/graphql-issues-service.d.ts

@@ -42,7 +42,8 @@ export interface SearchIssueArgs {
     /** Issue states to include (e.g. `["Todo", "In Progress"]`). */
     status?: string[];
     /**
-     * Exclude terminal states (workflow type `completed` or `canceled`).
+     * Exclude terminal states (workflow type `completed`, `canceled`, or
+     * `duplicate` — see `TERMINAL_STATE_TYPES`).
      * Default `false` for back-compat at the service layer; the CLI's
      * `issues list` / `issues search` flip this to `true` by default
      * (DEV-4478) and accept `--include-closed` to opt back in. When

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

@@ -2,6 +2,7 @@ import { isRegistryConfigured, resolveViaRegistry, } from "../config/registry-re
 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_STARTED_STATUSES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
 import { CREATE_LABEL_MUTATION } from "../queries/labels.js";
+import { TERMINAL_STATE_TYPES } from "../types/linear.js";
 import { toISOStringOrNow } from "./date-format.js";
 import { extractEmbeds } from "./embed-parser.js";
 import { multipleMatchesError, notFoundError } from "./error-messages.js";
@@ -981,7 +982,7 @@ export class GraphQLIssuesService {
         else if (filters.excludeTerminalStates) {
             // Implicit terminal-state exclusion (DEV-4478). Explicit `status`
             // always wins — the user already named the states they want.
-            filtered = filtered.filter((issue) => issue.state?.type !== "completed" && issue.state?.type !== "canceled");
+            filtered = filtered.filter((issue) => !TERMINAL_STATE_TYPES.includes(issue.state?.type ?? ""));
         }
         if (filters.labelNames && filters.labelNames.length > 0) {
             const lowerNames = filters.labelNames.map((n) => n.toLowerCase());
@@ -1024,7 +1025,7 @@ export class GraphQLIssuesService {
         else if (filters.excludeTerminalStates) {
             // Implicit terminal-state exclusion (DEV-4478). Explicit `status`
             // always wins — the user already named the states they want.
-            filter.state = { type: { nin: ["completed", "canceled"] } };
+            filter.state = { type: { nin: [...TERMINAL_STATE_TYPES] } };
         }
         if (filters.labelNames && filters.labelNames.length > 0) {
             if (filters.labelNames.length === 1) {

package/dist/utils/mention-resolver.d.ts

@@ -12,6 +12,27 @@ export interface ResolveMentionsOptions {
      */
     selfUserId?: string;
 }
+interface ResolvedMention {
+    label: string;
+    userId: string;
+}
+export interface MentionReport {
+    /**
+     * ProseMirror doc carrying `suggestion_userMentions` nodes — the structured
+     * body that makes Linear fire real notifications. `null` when nothing
+     * resolved (the caller should send the plain markdown `body` instead).
+     */
+    bodyData: ProseMirrorNode | null;
+    /** Mentions that resolved to a real user (explicit `@name` + bare names). */
+    resolved: ResolvedMention[];
+    /**
+     * Explicit `@name` tokens that did NOT resolve to any team member — almost
+     * always a typo or an unknown handle. Left as plain text (no notification),
+     * so the caller surfaces them as a warning. Bare-name non-matches are not
+     * tracked here: they were never an intended ping.
+     */
+    unresolvedExplicit: string[];
+}
 /**
  * Resolve mentions in markdown body text to Linear user IDs.
  *
@@ -23,9 +44,9 @@ export interface ResolveMentionsOptions {
  * are also converted to mentions — without requiring the `@` prefix. This
  * catches cases like "Bob owns the design" → "@bob owns the design".
  *
- * Returns a ProseMirror `bodyData` doc with `suggestion_userMentions` nodes,
- * or `null` if nothing was resolved.
+ * Returns a {@link MentionReport} describing which names resolved, which
+ * explicit `@names` did not, and the `bodyData` doc to send — or `null` when
+ * there was nothing to resolve and nothing to warn about.
  */
-export declare function resolveMentions(body: string, linearService: LinearService, options?: ResolveMentionsOptions): Promise<{
-    bodyData: ProseMirrorNode;
-} | null>;
+export declare function resolveMentions(body: string, linearService: LinearService, options?: ResolveMentionsOptions): Promise<MentionReport | null>;
+export {};

package/dist/utils/mention-resolver.js

@@ -21,20 +21,27 @@ const MARKDOWN_LINK_REGEX = /\[([^\]]+)\]\(([^)]+)\)/g;
  * are also converted to mentions — without requiring the `@` prefix. This
  * catches cases like "Bob owns the design" → "@bob owns the design".
  *
- * Returns a ProseMirror `bodyData` doc with `suggestion_userMentions` nodes,
- * or `null` if nothing was resolved.
+ * Returns a {@link MentionReport} describing which names resolved, which
+ * explicit `@names` did not, and the `bodyData` doc to send — or `null` when
+ * there was nothing to resolve and nothing to warn about.
  */
 export async function resolveMentions(body, linearService, options = {}) {
     const autoMention = options.autoMention !== false;
     const selfUserId = options.selfUserId;
     // 1. Resolve explicit @name mentions (existing behavior).
     const explicit = new Map();
+    const unresolvedExplicit = [];
     const explicitNames = [...body.matchAll(EXPLICIT_MENTION_REGEX)].map((m) => m[1]);
     for (const name of new Set(explicitNames)) {
         const userId = await resolveUserByName(name, linearService);
         if (userId) {
             explicit.set(name, { userId, label: name });
         }
+        else {
+            // An explicit `@name` the author clearly meant as a ping, but it
+            // matched no team member — surface it so the ping never dies silently.
+            unresolvedExplicit.push(name);
+        }
     }
     // 2. Bare-name mentions: scan for candidate names that actually appear as
     //    standalone words in the body (outside code / link contexts).
@@ -61,12 +68,33 @@ export async function resolveMentions(body, linearService, options = {}) {
             bare.set(candidate, { userId, label: candidate });
         }
     }
-    if (explicit.size === 0 && bare.size === 0) {
+    // Nothing resolved and no failed explicit ping → caller has nothing to do.
+    if (explicit.size === 0 &&
+        bare.size === 0 &&
+        unresolvedExplicit.length === 0) {
         return null;
     }
-    const doc = markdownToProseMirror(body);
-    const bodyData = injectMentions(doc, explicit, bare);
-    return { bodyData };
+    // De-dup by userId for the reported set: a capitalized explicit `@Bob` also
+    // matches the bare candidate "Bob" (the `@` isn't a word char, so the bare
+    // lookbehind passes), landing the same user in both maps. The injected
+    // bodyData is unaffected (the `@name` alternation consumes the span first,
+    // so only one mention node is emitted), but `resolved` would over-count and
+    // `--quiet` would print the user twice — which undercuts the whole point of
+    // a trustworthy mention report. Explicit-first so the label is the typed
+    // `@name`, not the capitalized bare candidate.
+    const resolvedByUser = new Map();
+    for (const m of [...explicit.values(), ...bare.values()]) {
+        if (!resolvedByUser.has(m.userId)) {
+            resolvedByUser.set(m.userId, m);
+        }
+    }
+    const resolved = [...resolvedByUser.values()];
+    // Only build the structured doc when something actually resolved; a body
+    // whose only mention was an unresolved `@typo` is sent as plain markdown.
+    const bodyData = explicit.size > 0 || bare.size > 0
+        ? injectMentions(markdownToProseMirror(body), explicit, bare)
+        : null;
+    return { bodyData, resolved, unresolvedExplicit };
 }
 async function resolveUserByName(name, linearService) {
     const configResult = resolveMember(name);

package/dist/utils/output.d.ts

@@ -6,6 +6,12 @@ export declare function setRawMode(enabled: boolean): void;
  * the summary block. Set in main.ts's preAction when the flag is present.
  */
 export declare function setQuietMode(enabled: boolean): void;
+/**
+ * Whether `--quiet` is active. Lets a command decide to route extra
+ * human-facing detail (e.g. a mention-resolution confirmation) to stderr,
+ * keeping the single machine-stable stdout line intact.
+ */
+export declare function getQuietMode(): boolean;
 export declare function setJqFilter(filter: string | null): void;
 export declare function setFieldsFilter(fields: string[] | null): void;
 export declare function setOutputFormat(format: OutputFormat): void;

package/dist/utils/output.js

@@ -19,6 +19,14 @@ export function setRawMode(enabled) {
 export function setQuietMode(enabled) {
     quietMode = enabled;
 }
+/**
+ * Whether `--quiet` is active. Lets a command decide to route extra
+ * human-facing detail (e.g. a mention-resolution confirmation) to stderr,
+ * keeping the single machine-stable stdout line intact.
+ */
+export function getQuietMode() {
+    return quietMode;
+}
 export function setJqFilter(filter) {
     jqFilter = filter;
 }

package/package.json

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