@enrichlayer/el-linear 1.7.0 → 1.10.0

package/dist/commands/comments.js

@@ -11,6 +11,7 @@ import { resolveMentions } from "../utils/mention-resolver.js";
 import { 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";
 import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
 // Match Linear's bodyData validation error in multiple phrasings so a wording
 // tweak on their side doesn't silently regress the fallback path.
@@ -28,22 +29,20 @@ function readBody(options) {
 async function fetchSelfUserId(graphQLService) {
     try {
         const result = await graphQLService.rawRequest("{ viewer { id } }");
-        const viewer = result.viewer;
-        return viewer?.id;
+        return result.viewer?.id;
     }
     catch {
         return;
     }
 }
 function transformComment(comment) {
-    const user = comment.user;
     return {
         id: comment.id,
         body: comment.body,
         user: {
-            id: user.id,
-            name: resolveUserDisplayName(user.id, user.name),
-            url: user.url || undefined,
+            id: comment.user.id,
+            name: resolveUserDisplayName(comment.user.id, comment.user.name),
+            url: comment.user.url ?? undefined,
         },
         createdAt: comment.createdAt,
         updatedAt: comment.updatedAt,
@@ -133,9 +132,7 @@ async function handleCreateComment(issueId, options, command) {
     }
     let result;
     try {
-        result = await graphQLService.rawRequest(CREATE_COMMENT_MUTATION, {
-            input,
-        });
+        result = await graphQLService.rawRequest(CREATE_COMMENT_MUTATION, { input });
     }
     catch (err) {
         // If the bodyData ProseMirror document is rejected (invalid shape,
@@ -147,16 +144,14 @@ async function handleCreateComment(issueId, options, command) {
                 issueId: resolvedIssueId,
                 body,
             };
-            result = await graphQLService.rawRequest(CREATE_COMMENT_MUTATION, {
-                input: fallbackInput,
-            });
+            result = await graphQLService.rawRequest(CREATE_COMMENT_MUTATION, { input: fallbackInput });
         }
         else {
             throw err;
         }
     }
     const mutation = result.commentCreate;
-    if (!mutation.success) {
+    if (!mutation.success || !mutation.comment) {
         throw new Error("Failed to create comment");
     }
     // We don't have the parent issue's identifier from the create mutation response,
@@ -201,22 +196,18 @@ async function handleUpdateComment(commentId, options, command) {
     else {
         input.body = body;
     }
-    const result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, {
-        id: commentId,
-        input,
-    });
+    const result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, { id: commentId, input });
     const mutation = result.commentUpdate;
-    if (!mutation.success) {
+    if (!mutation.success || !mutation.comment) {
         throw new Error("Failed to update comment");
     }
     const comment = mutation.comment;
-    const issue = comment.issue;
     let autoLinked;
-    if (issue) {
+    if (comment.issue) {
         // rawBody (pre-wrap) — see note in handleCreateComment about keyword inference
         autoLinked = await autoLinkCommentReferences({
-            parentIssueUuid: issue.id,
-            parentIssueIdentifier: issue.identifier ?? "",
+            parentIssueUuid: comment.issue.id,
+            parentIssueIdentifier: comment.issue.identifier,
             body: rawBody,
             preResolved,
             options,
@@ -234,19 +225,17 @@ async function handleListComments(issueId, options, command) {
     const resolvedId = await linearService.resolveIssueId(issueId);
     const result = await graphQLService.rawRequest(LIST_COMMENTS_QUERY, {
         issueId: resolvedId,
-        first: Number.parseInt(options.limit, 10),
+        first: parsePositiveInt(options.limit, "--limit"),
     });
-    const issue = result.issue;
-    if (!issue) {
+    if (!result.issue) {
         throw new Error(`Issue "${issueId}" not found`);
     }
-    const commentsData = issue.comments;
-    const nodes = commentsData.nodes.map(transformComment);
+    const nodes = result.issue.comments.nodes.map(transformComment);
     outputSuccess({
         data: nodes,
         meta: {
             count: nodes.length,
-            issue: issue.identifier,
+            issue: result.issue.identifier,
         },
     });
 }

package/dist/commands/cycles.js

@@ -3,6 +3,7 @@ import { invalidParameterError, notFoundError, requiresParameterError, } from ".
 import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
+import { parsePositiveInt } from "../utils/validators.js";
 export function setupCyclesCommands(program) {
     const cycles = program
         .command("cycles")
@@ -23,7 +24,7 @@ export function setupCyclesCommands(program) {
         const rootOpts = getRootOpts(command);
         const teamFilter = options.team ? resolveTeam(options.team) : undefined;
         const linearService = await createLinearService(rootOpts);
-        const allCycles = await linearService.getCycles(teamFilter, options.active || undefined, Number.parseInt(options.limit, 10));
+        const allCycles = await linearService.getCycles(teamFilter, options.active || undefined, parsePositiveInt(options.limit, "--limit"));
         if (options.aroundActive) {
             const n = Number.parseInt(options.aroundActive, 10);
             if (Number.isNaN(n) || n < 0) {

package/dist/commands/documents.js

@@ -3,6 +3,7 @@ import { createGraphQLDocumentsService } from "../utils/graphql-documents-servic
 import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
+import { parsePositiveInt } from "../utils/validators.js";
 function extractDocumentIdFromUrl(url) {
     try {
         const parsed = new URL(url);
@@ -70,7 +71,7 @@ async function handleListDocuments(options, command) {
     const rootOpts = getRootOpts(command);
     const documentsService = await createGraphQLDocumentsService(rootOpts);
     const linearService = await createLinearService(rootOpts);
-    const limit = Number.parseInt(options.limit || "50", 10);
+    const limit = parsePositiveInt(options.limit || "50", "--limit");
     if (Number.isNaN(limit) || limit < 1) {
         throw new Error(`Invalid limit "${options.limit}": must be a positive number`);
     }

package/dist/commands/graphql.js

@@ -46,16 +46,14 @@ export function setupGraphQLCommands(program) {
         const graphQLService = await createGraphQLService(rootOpts);
         if (typeName) {
             const result = await graphQLService.rawRequest(INTROSPECT_TYPE_QUERY, { typeName });
-            const typeInfo = result.__type;
-            if (!typeInfo) {
+            if (!result.__type) {
                 throw new Error(`Type "${typeName}" not found in schema`);
             }
-            outputSuccess(typeInfo);
+            outputSuccess(result.__type);
         }
         else {
             const result = await graphQLService.rawRequest(INTROSPECT_ROOT_QUERY);
-            const queryType = result.__type;
-            let fields = queryType?.fields ?? [];
+            let fields = result.__type?.fields ?? [];
             if (options.filter) {
                 const pattern = options.filter.toLowerCase();
                 fields = fields.filter((f) => f.name.toLowerCase().includes(pattern));
@@ -63,7 +61,7 @@ export function setupGraphQLCommands(program) {
             const summary = fields.map((f) => ({
                 name: f.name,
                 description: f.description ?? null,
-                args: (f.args ?? []).map((a) => a.name),
+                args: f.args.map((a) => a.name),
             }));
             outputSuccess({ fields: summary, count: summary.length });
         }

package/dist/commands/init/index.js

@@ -63,6 +63,7 @@ export function setupInitCommands(program) {
         .option("--revoke", "revoke and remove the stored OAuth tokens")
         .option("--no-browser", "skip the browser-open + localhost listener; paste the code manually")
         .option("--port <port>", "localhost callback port (default 8765)", (value) => Number.parseInt(value, 10))
+        .option("--unsafe-bare-code", "allow pasting a bare authorization code in the headless flow (skips the OAuth `state` CSRF check; opt-in only)")
         .action(withCleanExit(async (options) => {
         printStep("oauth", "Linear OAuth (PKCE)");
         if (options.revoke) {
@@ -75,6 +76,7 @@ export function setupInitCommands(program) {
             // commander's `--no-browser` produces `browser: false`.
             noBrowser: options.browser === false,
             port: options.port,
+            unsafeBareCode: options.unsafeBareCode === true,
         });
     }));
     init

package/dist/commands/init/oauth.d.ts

@@ -39,6 +39,12 @@ export interface OAuthStepOptions {
     noBrowser?: boolean;
     /** Override the localhost port. Default 8765. */
     port?: number;
+    /**
+     * Allow pasting a bare authorization code (no surrounding URL) in
+     * the headless flow. Bypasses the OAuth `state` CSRF check, so
+     * opt-in only — see `oauth-headless.ts` for the rationale.
+     */
+    unsafeBareCode?: boolean;
     /** Test seam for the OAuth token endpoint. */
     fetchImpl?: FetchLike;
     /**

package/dist/commands/init/oauth.js

@@ -270,11 +270,17 @@ export async function runOAuthStep(options = {}) {
         catch (err) {
             const raw = err instanceof Error ? err.message : String(err);
             logLine(TS(`Localhost listener failed (${sanitizeForLog(raw)}). Falling back to manual paste.`));
-            callback = await promptForPastedCode({ expectedState: state });
+            callback = await promptForPastedCode({
+                expectedState: state,
+                unsafeBareCode: options.unsafeBareCode,
+            });
         }
     }
     else {
-        callback = await promptForPastedCode({ expectedState: state });
+        callback = await promptForPastedCode({
+            expectedState: state,
+            unsafeBareCode: options.unsafeBareCode,
+        });
     }
     logLine(TS("Exchanging authorization code for tokens…"));
     const exchanged = await exchangeCodeForTokens({

package/dist/commands/init/token.d.ts

@@ -21,14 +21,6 @@ export interface TokenStepResult {
     token: string;
     viewer: ViewerResponse["viewer"];
 }
-/**
- * Strip anything that looks like a Linear API token from a string. Defense in
- * depth: today the @linear/sdk error message embeds {query, variables} but not
- * the Authorization header. A future SDK upgrade that includes headers (which
- * upstream graphql-request has done historically) would otherwise silently
- * write `Bearer lin_api_…` into stdout / shell history / CI logs. The regex
- * also catches token shapes that may show up in custom error wrappers.
- */
 export declare function sanitizeForLog(text: string): string;
 /**
  * Validate a Linear API token by fetching the viewer. Throws with a

package/dist/commands/init/token.js

@@ -31,8 +31,20 @@ const VIEWER_QUERY = /* GraphQL */ `
  * write `Bearer lin_api_…` into stdout / shell history / CI logs. The regex
  * also catches token shapes that may show up in custom error wrappers.
  */
+// Personal-API tokens (`lin_api_…`) and OAuth access/refresh tokens
+// (`lin_oauth_…`). Pre-fix the regex only matched personal tokens.
+const TOKEN_PREFIX_RE = /lin_(api|oauth)_[A-Za-z0-9_-]{16,}/g;
+// High-entropy bearer payload fallback: catches generic Bearer-style
+// strings adjacent to Authorization / Bearer keywords. Useful for
+// future SDK error wrappers that might leak headers without the
+// `lin_` prefix.
+const BEARER_PAYLOAD_RE = /(\b(?:Authorization|Bearer)\b[:\s]*)([A-Za-z0-9_\-/+=]{40,})/gi;
 export function sanitizeForLog(text) {
-    return text.replace(/lin_api_[A-Za-z0-9_-]{16,}/g, "lin_api_***REDACTED***");
+    return text
+        .replace(TOKEN_PREFIX_RE, (m) => m.startsWith("lin_oauth_")
+        ? "lin_oauth_***REDACTED***"
+        : "lin_api_***REDACTED***")
+        .replace(BEARER_PAYLOAD_RE, "$1***REDACTED***");
 }
 /**
  * Strict shape check on the viewer response. Treats whitespace-only fields as

package/dist/commands/issue-id.js

@@ -75,9 +75,7 @@ export function setupIssueIdCommand(program) {
         const service = await createGraphQLService({
             apiToken: rootOpts.apiToken,
         });
-        const result = (await service.rawRequest(ISSUE_QUERY, {
-            id: parsed.issueId,
-        }));
+        const result = await service.rawRequest(ISSUE_QUERY, { id: parsed.issueId });
         outputSuccess({ ...parsed, issue: result.issue ?? null });
     }));
 }

package/dist/commands/issues/branch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Git branch helpers used by `issues create --branch` and the
+ * `issues retrolink` flow.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) to keep that file
+ * focused on commander wiring + handlers.
+ */
+/**
+ * Transform Linear's branchName (e.g. "dev-3549-slug") into our convention:
+ * "feature/DEV-3549-slug" — uppercase team key with a configurable prefix.
+ */
+export declare function toBranchName(linearBranchName: string, prefix?: string): string;
+/**
+ * Check out a new git branch. Warns and skips if not in a git repo.
+ * Throws if the branch already exists.
+ */
+export declare function gitCheckoutBranch(branchName: string): void;

package/dist/commands/issues/branch.js

@@ -0,0 +1,40 @@
+/**
+ * Git branch helpers used by `issues create --branch` and the
+ * `issues retrolink` flow.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) to keep that file
+ * focused on commander wiring + handlers.
+ */
+import { execFileSync } from "node:child_process";
+import { outputWarning } from "../../utils/output.js";
+const LINEAR_BRANCH_REGEX = /^([a-zA-Z]+)-(\d+)-(.+)$/;
+/**
+ * Transform Linear's branchName (e.g. "dev-3549-slug") into our convention:
+ * "feature/DEV-3549-slug" — uppercase team key with a configurable prefix.
+ */
+export function toBranchName(linearBranchName, prefix = "feature/") {
+    // Linear branch names look like "dev-123-some-slug"
+    // We need to uppercase the team key: "DEV-123-some-slug"
+    const match = linearBranchName.match(LINEAR_BRANCH_REGEX);
+    if (!match) {
+        return `${prefix}${linearBranchName}`;
+    }
+    const [, teamKey, number, slug] = match;
+    return `${prefix}${teamKey.toUpperCase()}-${number}-${slug}`;
+}
+/**
+ * Check out a new git branch. Warns and skips if not in a git repo.
+ * Throws if the branch already exists.
+ */
+export function gitCheckoutBranch(branchName) {
+    try {
+        execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            stdio: "pipe",
+        });
+    }
+    catch {
+        outputWarning("Not inside a git repository — skipping branch checkout.");
+        return;
+    }
+    execFileSync("git", ["checkout", "-b", branchName], { stdio: "pipe" });
+}

package/dist/commands/issues/description.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Description-handling helpers for issues create/update and the
+ * `issues link-references --rewrite-description` flow.
+ *
+ * Three concerns live here:
+ *
+ *  1. Resolving the description value from `--description`,
+ *     `--description-file`, or `--template`.
+ *  2. The shared wrap-and-resolve pipeline (`wrapAndResolveRefs`)
+ *     used by the create/update path and the rewrite-description
+ *     path. Both wrap valid identifiers as markdown links and
+ *     return the resolved id→uuid map for downstream auto-link.
+ *  3. The post-create/update `maybeAutoLink` hook that creates
+ *     sidebar relations for refs in the description.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) so that file can
+ * focus on commander wiring + handlers.
+ */
+import type { OptionValues } from "commander";
+import { type AutoLinkResult } from "../../utils/auto-link-references.js";
+import type { GraphQLService } from "../../utils/graphql-service.js";
+import type { LinearService } from "../../utils/linear-service.js";
+/**
+ * Read description from a file path or stdin ("-").
+ * Avoids shell escaping issues when descriptions contain special characters.
+ */
+export declare function readDescriptionFile(filePath: string): string;
+/**
+ * Resolve the description from --description, --description-file, or
+ * --template (looked up in `config.descriptionTemplates`).
+ *
+ * Precedence: --description-file > --description > --template
+ *
+ * Passing --template alongside --description / --description-file is
+ * a usage error — the explicit body and a template both producing
+ * content would silently drop one. We throw so the user picks one.
+ */
+export declare function resolveDescription(options: OptionValues): string | undefined;
+export interface PreparedDescription {
+    /** The (possibly rewritten) description text to send to Linear */
+    description: string | undefined;
+    /** Map<identifier, uuid> of refs that resolved — passed to autoLink to avoid re-resolution */
+    preResolved: Map<string, string>;
+    /** True when the original description was rewritten (i.e. at least one link was wrapped) */
+    rewritten: boolean;
+}
+/**
+ * Pre-process a description before sending to Linear:
+ *  1. Extract all issue references.
+ *  2. Validate them (drop ones that don't resolve in the workspace —
+ *     handles "ISO-1424"-style false positives).
+ *  3. Wrap valid identifiers as markdown links — skipping any
+ *     already inside a link, code block, or backtick span.
+ *
+ * No-ops (returns the original description with an empty map) when:
+ *  - description is empty/undefined
+ *  - the user passed `--no-auto-link`
+ */
+export declare function prepareAutoLinkedDescription(description: string | undefined, options: OptionValues, selfIdentifier: string | undefined, linearService: LinearService, graphQLService: GraphQLService): Promise<PreparedDescription>;
+export interface PreparedRewrite {
+    /** Resolved id→uuid map (passed to autoLink to skip duplicate resolution) */
+    preResolved: Map<string, string> | undefined;
+    /** New description text — undefined when wrapping wouldn't change anything */
+    wrapped: string | undefined;
+}
+/**
+ * Prepare a description rewrite for `link-references --rewrite-description`.
+ * Same wrap-and-resolve core; different return shape so the caller can
+ * skip the rewrite mutation when nothing would change.
+ */
+export declare function prepareDescriptionRewrite(description: string, selfIdentifier: string, linearService: LinearService, graphQLService: GraphQLService): Promise<PreparedRewrite>;
+export declare function pushDescriptionUpdate(issueUuid: string, description: string, graphQLService: GraphQLService): Promise<void>;
+interface MaybeAutoLinkInput {
+    description: string | null | undefined;
+    graphQLService: GraphQLService;
+    identifier: string;
+    issueId: string;
+    linearService: LinearService;
+    options: OptionValues;
+    preResolved?: Map<string, string>;
+}
+/**
+ * Run auto-linking for issue references found in a description, unless
+ * the user opted out with `--no-auto-link` or no description was
+ * provided. Returns undefined when nothing was linked / skipped /
+ * failed (so callers can omit the field from JSON output).
+ */
+export declare function maybeAutoLink(input: MaybeAutoLinkInput): Promise<AutoLinkResult | undefined>;
+export {};

package/dist/commands/issues/description.js

@@ -0,0 +1,183 @@
+/**
+ * Description-handling helpers for issues create/update and the
+ * `issues link-references --rewrite-description` flow.
+ *
+ * Three concerns live here:
+ *
+ *  1. Resolving the description value from `--description`,
+ *     `--description-file`, or `--template`.
+ *  2. The shared wrap-and-resolve pipeline (`wrapAndResolveRefs`)
+ *     used by the create/update path and the rewrite-description
+ *     path. Both wrap valid identifiers as markdown links and
+ *     return the resolved id→uuid map for downstream auto-link.
+ *  3. The post-create/update `maybeAutoLink` hook that creates
+ *     sidebar relations for refs in the description.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) so that file can
+ * focus on commander wiring + handlers.
+ */
+import fs from "node:fs";
+import { loadConfig } from "../../config/config.js";
+import { UPDATE_ISSUE_MUTATION } from "../../queries/issues.js";
+import { autoLinkReferences, } from "../../utils/auto-link-references.js";
+import { extractIssueReferences } from "../../utils/issue-reference-extractor.js";
+import { wrapIssueReferencesAsLinks } from "../../utils/issue-reference-wrapper.js";
+import { validateReferences } from "../../utils/validate-references.js";
+import { getWorkspaceUrlKey } from "../../utils/workspace-url.js";
+/**
+ * Read description from a file path or stdin ("-").
+ * Avoids shell escaping issues when descriptions contain special characters.
+ */
+export function readDescriptionFile(filePath) {
+    if (filePath === "-") {
+        return fs.readFileSync(0, "utf8").trim();
+    }
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Description file not found: ${filePath}`);
+    }
+    return fs.readFileSync(filePath, "utf8").trim();
+}
+/**
+ * Resolve the description from --description, --description-file, or
+ * --template (looked up in `config.descriptionTemplates`).
+ *
+ * Precedence: --description-file > --description > --template
+ *
+ * Passing --template alongside --description / --description-file is
+ * a usage error — the explicit body and a template both producing
+ * content would silently drop one. We throw so the user picks one.
+ */
+export function resolveDescription(options) {
+    const hasInline = typeof options.description === "string" && options.description.length > 0;
+    const hasFile = Boolean(options.descriptionFile);
+    const hasTemplate = typeof options.template === "string" && options.template;
+    if (hasTemplate && (hasInline || hasFile)) {
+        throw new Error("--template is mutually exclusive with --description / --description-file. " +
+            "Pick one.");
+    }
+    if (hasFile) {
+        return readDescriptionFile(options.descriptionFile);
+    }
+    if (hasInline) {
+        return options.description;
+    }
+    if (hasTemplate) {
+        const templates = loadConfig().descriptionTemplates ?? {};
+        const body = templates[options.template];
+        if (!body) {
+            const available = Object.keys(templates).sort();
+            const hint = available.length
+                ? `Available templates: ${available.join(", ")}`
+                : "No templates configured. Add one under `descriptionTemplates` in your config.";
+            throw new Error(`Template "${options.template}" not found. ${hint}`);
+        }
+        return body;
+    }
+    return undefined;
+}
+/**
+ * Shared core for the wrap-and-resolve pipeline used by both the
+ * create/update path (`prepareAutoLinkedDescription`) and the
+ * `link-references --rewrite-description` path
+ * (`prepareDescriptionRewrite`).
+ *
+ * Returns:
+ *   - `wrapped: undefined` when the original description had no
+ *     resolvable refs to wrap (no-op for the caller),
+ *   - `wrapped: <string>` when at least one ref was wrapped,
+ *   - `preResolved` — the validated id→uuid map, passed downstream
+ *     to `autoLinkReferences` to skip a second resolve roundtrip.
+ */
+async function wrapAndResolveRefs(description, selfIdentifier, linearService, graphQLService) {
+    const refs = extractIssueReferences(description, selfIdentifier);
+    if (refs.length === 0) {
+        return { wrapped: undefined, preResolved: new Map() };
+    }
+    const preResolved = await validateReferences(refs.map((r) => r.identifier), linearService);
+    if (preResolved.size === 0) {
+        return { wrapped: undefined, preResolved };
+    }
+    const validIds = new Set(preResolved.keys());
+    const urlKey = await getWorkspaceUrlKey(graphQLService);
+    const rewritten = wrapIssueReferencesAsLinks(description, validIds, urlKey);
+    return {
+        wrapped: rewritten === description ? undefined : rewritten,
+        preResolved,
+    };
+}
+/**
+ * Pre-process a description before sending to Linear:
+ *  1. Extract all issue references.
+ *  2. Validate them (drop ones that don't resolve in the workspace —
+ *     handles "ISO-1424"-style false positives).
+ *  3. Wrap valid identifiers as markdown links — skipping any
+ *     already inside a link, code block, or backtick span.
+ *
+ * No-ops (returns the original description with an empty map) when:
+ *  - description is empty/undefined
+ *  - the user passed `--no-auto-link`
+ */
+export async function prepareAutoLinkedDescription(description, options, selfIdentifier, linearService, graphQLService) {
+    if (!description || options.autoLink === false) {
+        return { description, preResolved: new Map(), rewritten: false };
+    }
+    const { wrapped, preResolved } = await wrapAndResolveRefs(description, selfIdentifier, linearService, graphQLService);
+    return {
+        description: wrapped ?? description,
+        preResolved,
+        rewritten: wrapped !== undefined,
+    };
+}
+/**
+ * Prepare a description rewrite for `link-references --rewrite-description`.
+ * Same wrap-and-resolve core; different return shape so the caller can
+ * skip the rewrite mutation when nothing would change.
+ */
+export async function prepareDescriptionRewrite(description, selfIdentifier, linearService, graphQLService) {
+    if (!description) {
+        return { preResolved: undefined, wrapped: undefined };
+    }
+    const { wrapped, preResolved } = await wrapAndResolveRefs(description, selfIdentifier, linearService, graphQLService);
+    return {
+        // `link-references --rewrite-description` historically used
+        // `preResolved: undefined` to mean "no refs at all"; preserve
+        // that signal so the existing call site keeps the same shape.
+        preResolved: preResolved.size === 0 ? undefined : preResolved,
+        wrapped,
+    };
+}
+export async function pushDescriptionUpdate(issueUuid, description, graphQLService) {
+    const updateResult = await graphQLService.rawRequest(UPDATE_ISSUE_MUTATION, { id: issueUuid, input: { description } });
+    if (!updateResult.issueUpdate.success) {
+        throw new Error("Failed to rewrite description");
+    }
+}
+/**
+ * Run auto-linking for issue references found in a description, unless
+ * the user opted out with `--no-auto-link` or no description was
+ * provided. Returns undefined when nothing was linked / skipped /
+ * failed (so callers can omit the field from JSON output).
+ */
+export async function maybeAutoLink(input) {
+    const { issueId, identifier, description, options, graphQLService, linearService, preResolved, } = input;
+    if (options.autoLink === false) {
+        return;
+    }
+    if (!description) {
+        return;
+    }
+    const result = await autoLinkReferences({
+        issueId,
+        identifier,
+        description,
+        graphQLService,
+        linearService,
+        preResolved,
+    });
+    if (result.linked.length === 0 &&
+        result.skipped.length === 0 &&
+        result.failed.length === 0) {
+        return;
+    }
+    return result;
+}

package/dist/commands/issues/link-references.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `el-linear issues link-references` handler.
+ *
+ * Two modes:
+ *   - Single-issue (`<issueId>`): scan one issue's description (and
+ *     optionally its comments) for issue refs, create sidebar
+ *     relations for any that aren't already linked, optionally
+ *     rewrite the description to wrap the bare refs as markdown
+ *     links.
+ *   - Batch (`--team <key>`): walk the team's recent issues and run
+ *     the same auto-link pass on each. Description rewrite is
+ *     intentionally disabled in batch mode — bulk rewrites
+ *     bot-author every issue's revision history, which makes
+ *     "who edited this?" attribution noisy.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) so that file can
+ * focus on commander wiring + the create / update / read / search
+ * handlers.
+ */
+import type { Command, OptionValues } from "commander";
+export declare function handleLinkReferencesIssue(issueIdOrTeamFlag: string | undefined, options: OptionValues, command: Command): Promise<void>;