@enrichlayer/el-linear 1.6.0 → 1.9.0

package/dist/auth/token-resolver.js

@@ -16,7 +16,8 @@
  *   - oauth:     `Authorization: Bearer <token>`
  */
 import { getApiToken } from "../utils/auth.js";
-import { isAccessTokenFresh, readOAuthState, writeOAuthState, } from "./oauth-storage.js";
+import { withFileLock } from "./oauth-fs.js";
+import { oauthStatePath, readOAuthState, writeOAuthState, } from "./oauth-storage.js";
 import { refreshTokens, } from "./oauth-token.js";
 /**
  * Resolve the credential for this invocation.
@@ -52,44 +53,63 @@ export async function getActiveAuth(options = {}) {
  *
  * On refresh failure, throws an actionable error pointing at
  * `el-linear init oauth`.
+ *
+ * **Concurrency.** When a refresh is needed, this acquires an exclusive
+ * file lock on the oauth.json sidecar before reading-refreshing-writing.
+ * Two parallel CLI invocations would otherwise both call `refreshTokens`
+ * with the same refresh token; Linear's server invalidates the loser's
+ * stored token and the next refresh permanently fails. The lock
+ * serialises them — the second process re-reads the freshly-written
+ * state inside the lock and uses the winner's tokens instead of issuing
+ * a second refresh.
  */
 export async function ensureFreshAccessToken(state, options = {}) {
     const now = options.now ?? Date.now;
-    if (isAccessTokenFresh(state, /* skewMs */ 60_000)) {
-        // `isAccessTokenFresh` reads `Date.now()` internally; for the
-        // purpose of the test seam we re-check against the injected clock.
-        if (now() + 60_000 < state.expiresAt) {
-            return state;
-        }
-    }
-    if (!state.refreshToken) {
-        throw new Error("OAuth access token expired and no refresh token is stored. Re-run `el-linear init oauth`.");
-    }
-    let refreshed;
-    try {
-        refreshed = await refreshTokens({
-            clientId: state.clientId,
-            clientSecret: state.clientSecret,
-            refreshToken: state.refreshToken,
-        }, options.fetchImpl, now);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`OAuth refresh failed: ${message}. Re-run \`el-linear init oauth\` to re-authorize.`);
+    // Fast path: token is fresh; no lock, no refresh.
+    if (now() + 60_000 < state.expiresAt) {
+        return state;
     }
-    const next = {
-        ...state,
-        accessToken: refreshed.accessToken,
-        // Preserve the previous refresh token if the server didn't rotate
-        // (some OAuth servers only return a new refresh_token periodically).
-        refreshToken: refreshed.refreshToken ?? state.refreshToken,
-        tokenType: refreshed.tokenType,
-        // Use the freshly-returned scopes only if non-empty; otherwise keep
-        // what we had, since some token endpoints omit `scope` on refresh.
-        scopes: refreshed.scopes.length > 0 ? refreshed.scopes : state.scopes,
-        expiresAt: refreshed.expiresAt,
-        obtainedAt: now(),
-    };
-    await writeOAuthState(next);
-    return next;
+    // Snapshot the target path ONCE so a profile switch between the
+    // lock acquisition and the write inside the closure can't cause
+    // cross-profile contamination. The lock + read + write all bind
+    // to this path. ALL-935 deferred fix.
+    const targetPath = oauthStatePath();
+    return withFileLock(targetPath, async () => {
+        // Re-read inside the lock — another process may have refreshed
+        // while we were waiting. If so, use their result.
+        const current = (await readOAuthState(targetPath)) ?? state;
+        if (now() + 60_000 < current.expiresAt) {
+            return current;
+        }
+        if (!current.refreshToken) {
+            throw new Error("OAuth access token expired and no refresh token is stored. Re-run `el-linear init oauth`.");
+        }
+        let refreshed;
+        try {
+            refreshed = await refreshTokens({
+                clientId: current.clientId,
+                clientSecret: current.clientSecret,
+                refreshToken: current.refreshToken,
+            }, options.fetchImpl, now);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`OAuth refresh failed: ${message}. Re-run \`el-linear init oauth\` to re-authorize.`);
+        }
+        const next = {
+            ...current,
+            accessToken: refreshed.accessToken,
+            // Preserve the previous refresh token if the server didn't rotate
+            // (some OAuth servers only return a new refresh_token periodically).
+            refreshToken: refreshed.refreshToken ?? current.refreshToken,
+            tokenType: refreshed.tokenType,
+            // Use the freshly-returned scopes only if non-empty; otherwise
+            // keep what we had — some token endpoints omit `scope` on refresh.
+            scopes: refreshed.scopes.length > 0 ? refreshed.scopes : current.scopes,
+            expiresAt: refreshed.expiresAt,
+            obtainedAt: now(),
+        };
+        await writeOAuthState(next, targetPath);
+        return next;
+    });
 }

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

@@ -1,5 +1,6 @@
 /**
- * Step 4 of the wizard: default labels, status defaults, term enforcement.
+ * Step 4 of the wizard: default labels, default assignee, default priority,
+ * status defaults, term enforcement, cache TTL.
  *
  * All optional. Each subsection asks "change?" with default=N so re-running
  * with no input is a no-op.
@@ -7,6 +8,19 @@
 import { type WizardConfig } from "./shared.js";
 export interface DefaultsStepResult {
     defaultLabels: string[] | undefined;
+    /**
+     * Default assignee identifier (alias / display name / email / UUID — same
+     * shapes resolveAssignee accepts) for `issues create`. The wizard does NOT
+     * validate this against Linear (no API call) — the runtime resolver handles
+     * validation at issue-create time, keeping the wizard offline.
+     */
+    defaultAssignee: string | undefined;
+    /**
+     * Default priority keyword: `none|urgent|high|medium|normal|low`. Stored
+     * as-is; the runtime path runs it through validatePriority() to get the
+     * Linear priority number.
+     */
+    defaultPriority: string | undefined;
     /**
      * Status defaults. Both fields are optional so the wizard preserves
      * partial existing configs (`{ noProject: "Backlog" }` only) byte-for-byte
@@ -21,5 +35,8 @@ export interface DefaultsStepResult {
         canonical: string;
         reject: string[];
     }> | undefined;
+    /** TTL (seconds) for `teams list` / `labels list` / `projects list` disk
+     * cache. `0` disables. */
+    cacheTTLSeconds: number | undefined;
 }
 export declare function runDefaultsStep(existing: WizardConfig): Promise<DefaultsStepResult>;

package/dist/commands/init/defaults.js

@@ -1,12 +1,22 @@
 /**
- * Step 4 of the wizard: default labels, status defaults, term enforcement.
+ * Step 4 of the wizard: default labels, default assignee, default priority,
+ * status defaults, term enforcement, cache TTL.
  *
  * All optional. Each subsection asks "change?" with default=N so re-running
  * with no input is a no-op.
  */
-import { confirm, input } from "@inquirer/prompts";
+import { confirm, input, select } from "@inquirer/prompts";
 import { parseCsvList } from "./shared.js";
 const STATUS_FALLBACK = { noProject: "Triage", withAssigneeAndProject: "Todo" };
+const CACHE_TTL_FALLBACK = 3600;
+const PRIORITY_CHOICES = [
+    { name: "none", value: "none" },
+    { name: "urgent", value: "urgent" },
+    { name: "high", value: "high" },
+    { name: "medium", value: "medium" },
+    { name: "normal", value: "normal" },
+    { name: "low", value: "low" },
+];
 export async function runDefaultsStep(existing) {
     // Idempotency rule: when the user skips a sub-section, return the existing
     // value byte-for-byte. We deliberately do NOT spread or backfill optional
@@ -14,8 +24,11 @@ export async function runDefaultsStep(existing) {
     // with no input produces a byte-identical config.
     const result = {
         defaultLabels: existing.defaultLabels,
+        defaultAssignee: existing.defaultAssignee,
+        defaultPriority: existing.defaultPriority,
         statusDefaults: existing.statusDefaults,
         terms: existing.terms,
+        cacheTTLSeconds: existing.cacheTTLSeconds,
     };
     // ── Default labels ────────────────────────────────────────────────
     const currentLabels = existing.defaultLabels ?? [];
@@ -32,6 +45,45 @@ export async function runDefaultsStep(existing) {
         const parsed = parseCsvList(raw);
         result.defaultLabels = parsed.length > 0 ? parsed : undefined;
     }
+    // ── Default assignee ──────────────────────────────────────────────
+    console.log(`  Current default assignee: ${existing.defaultAssignee ?? "(none)"}`);
+    const editAssignee = await confirm({
+        message: "Change default assignee for new issues?",
+        default: false,
+    });
+    if (editAssignee) {
+        // We deliberately don't validate against Linear here — the wizard runs
+        // offline-friendly. The runtime resolver (resolveAssignee) catches
+        // typos at issue-create time. "none" is the explicit-clear sentinel
+        // so users have an unambiguous way to wipe the field.
+        const raw = (await input({
+            message: "Default assignee (alias, name, email, or 'none' to clear):",
+            default: existing.defaultAssignee ?? "",
+        })).trim();
+        if (!raw || raw.toLowerCase() === "none") {
+            result.defaultAssignee = undefined;
+        }
+        else {
+            result.defaultAssignee = raw;
+        }
+    }
+    // ── Default priority ──────────────────────────────────────────────
+    console.log(`  Current default priority: ${existing.defaultPriority ?? "(none)"}`);
+    const editPriority = await confirm({
+        message: "Change default priority for new issues?",
+        default: false,
+    });
+    if (editPriority) {
+        // `select` always picks one option — so picking "none" stores the
+        // keyword string "none" (Linear's "No priority"), distinct from
+        // `undefined` which means "no default at all".
+        const choice = await select({
+            message: "Default priority:",
+            choices: PRIORITY_CHOICES,
+            default: existing.defaultPriority ?? "none",
+        });
+        result.defaultPriority = choice;
+    }
     // ── Status defaults ────────────────────────────────────────────────
     const cur = existing.statusDefaults;
     console.log(`  Current status defaults: noProject=${cur?.noProject ?? STATUS_FALLBACK.noProject}, ` +
@@ -54,6 +106,35 @@ export async function runDefaultsStep(existing) {
             withAssigneeAndProject: withAP.trim(),
         };
     }
+    // ── Cache TTL ─────────────────────────────────────────────────────
+    const currentTTL = existing.cacheTTLSeconds ?? CACHE_TTL_FALLBACK;
+    console.log(`  Current cache TTL: ${currentTTL}s`);
+    const editTTL = await confirm({
+        message: "Change cache TTL?",
+        default: false,
+    });
+    if (editTTL) {
+        const raw = await input({
+            message: "Cache TTL in seconds (0 to disable):",
+            default: String(currentTTL),
+            // `validate` runs per submit; we reject anything that isn't a
+            // non-negative integer literal. Number("") is `0` (truthy by
+            // the integer test) so we explicitly require non-empty input —
+            // otherwise an empty submission would silently store 0.
+            validate: (value) => {
+                const trimmed = value.trim();
+                if (trimmed === "") {
+                    return "Enter a non-negative integer (e.g. 3600 for 1 hour, 0 to disable).";
+                }
+                const n = Number(trimmed);
+                if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {
+                    return "Enter a non-negative integer (e.g. 3600 for 1 hour, 0 to disable).";
+                }
+                return true;
+            },
+        });
+        result.cacheTTLSeconds = Number(raw);
+    }
     // ── Term enforcement ───────────────────────────────────────────────
     const currentTerms = existing.terms ?? [];
     console.log(`  Current term-enforcement rules: ${currentTerms.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
@@ -127,15 +129,18 @@ export function setupInitCommands(program) {
     }));
     init
         .command("defaults")
-        .description("Default labels, status defaults, term enforcement rules")
+        .description("Default labels, default assignee, default priority, status defaults, cache TTL, term enforcement")
         .action(withCleanExit(async () => {
         const existing = await readConfig();
         printStep("defaults", "Defaults");
         const result = await runDefaultsStep(existing);
         const merged = assignDefined(existing, {
             defaultLabels: result.defaultLabels,
+            defaultAssignee: result.defaultAssignee,
+            defaultPriority: result.defaultPriority,
             statusDefaults: result.statusDefaults,
             terms: result.terms,
+            cacheTTLSeconds: result.cacheTTLSeconds,
         });
         await writeConfig(merged);
         console.log("  ✓ Defaults saved.");
@@ -175,8 +180,11 @@ async function runFullWizardImpl(options) {
         // defaults step: result is `existing.X` itself when the user skipped
         // the edit branch, so direct assignment is safe.
         defaultLabels: defaults.defaultLabels,
+        defaultAssignee: defaults.defaultAssignee,
+        defaultPriority: defaults.defaultPriority,
         statusDefaults: defaults.statusDefaults,
         terms: defaults.terms,
+        cacheTTLSeconds: defaults.cacheTTLSeconds,
         // workspace step: `ws.defaultTeam` may be the existing value (user
         // skipped) or a new pick.
         defaultTeam: ws.defaultTeam,

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

@@ -2,10 +2,10 @@
  * Wizard step for OAuth 2.0 (PKCE flow) authorization.
  *
  * Flow:
- *   1. Present a "what is this?" intro pointing the user at Linear's OAuth
- *      app registration page. (Until we ship a shared OAuth client_id,
- *      every user registers their own app.)
- *   2. Prompt for `client_id`, optional `client_secret`, port, scopes.
+ *   1. Read optional local/team OAuth app defaults, if present.
+ *   2. Otherwise present a "what is this?" intro pointing the user at
+ *      Linear's OAuth app registration page, then prompt for `client_id`,
+ *      optional `client_secret`, port, scopes.
  *   3. Generate PKCE verifier + state, build the authorize URL.
  *   4. Try to open the system browser; fall back to printing the URL.
  *   5. Spin a localhost listener (or fall back to pasted-code prompt) to
@@ -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

@@ -2,10 +2,10 @@
  * Wizard step for OAuth 2.0 (PKCE flow) authorization.
  *
  * Flow:
- *   1. Present a "what is this?" intro pointing the user at Linear's OAuth
- *      app registration page. (Until we ship a shared OAuth client_id,
- *      every user registers their own app.)
- *   2. Prompt for `client_id`, optional `client_secret`, port, scopes.
+ *   1. Read optional local/team OAuth app defaults, if present.
+ *   2. Otherwise present a "what is this?" intro pointing the user at
+ *      Linear's OAuth app registration page, then prompt for `client_id`,
+ *      optional `client_secret`, port, scopes.
  *   3. Generate PKCE verifier + state, build the authorize URL.
  *   4. Try to open the system browser; fall back to printing the URL.
  *   5. Spin a localhost listener (or fall back to pasted-code prompt) to
@@ -19,6 +19,7 @@
  */
 import { spawn } from "node:child_process";
 import { checkbox, input, password, select } from "@inquirer/prompts";
+import { readTeamOAuthConfig } from "../../auth/oauth-app-config.js";
 import { DEFAULT_CALLBACK_PATH, runLocalhostCallback, } from "../../auth/oauth-callback.js";
 import { ALL_SCOPES, buildAuthorizeUrl, DEFAULT_SCOPES, generatePkce, generateState, SCOPE_DESCRIPTIONS, validateScopes, } from "../../auth/oauth-client.js";
 import { promptForPastedCode } from "../../auth/oauth-headless.js";
@@ -165,6 +166,22 @@ async function promptRegistration(defaults) {
         scopes: validateScopes(scopes),
     };
 }
+async function resolveRegistration(defaults) {
+    const teamConfig = await readTeamOAuthConfig();
+    if (!teamConfig) {
+        return promptRegistration({ port: defaults.manualPort });
+    }
+    const port = defaults.requestedPort ?? teamConfig.redirectPort;
+    logLine("");
+    logLine(TS(`Using Linear OAuth app defaults from ${teamConfig.sourcePath}.`));
+    logLine(TS(`Callback URL: http://localhost:${port}${DEFAULT_CALLBACK_PATH}`));
+    logLine("");
+    return {
+        clientId: teamConfig.clientId,
+        port,
+        scopes: teamConfig.scopes,
+    };
+}
 /**
  * Default viewer-validation routine. Calls `viewer { ... }` with the new
  * bearer token to confirm Linear accepted it. Reused for both the wizard
@@ -213,8 +230,9 @@ export async function runOAuthStep(options = {}) {
         }
         // Both `reauth` and `revoked` fall through to the re-auth flow.
     }
-    const reg = await promptRegistration({
-        port: options.port ?? extractPortFromRedirect(existing) ?? DEFAULT_PORT,
+    const reg = await resolveRegistration({
+        manualPort: options.port ?? extractPortFromRedirect(existing) ?? DEFAULT_PORT,
+        requestedPort: options.port,
     });
     const redirectUri = `http://localhost:${reg.port}${DEFAULT_CALLBACK_PATH}`;
     const pkce = generatePkce();
@@ -252,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/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 {};