@enrichlayer/el-linear 1.5.0 → 1.7.0

package/dist/commands/refs.js

@@ -4,6 +4,7 @@ import { extractIssueReferences } from "../utils/issue-reference-extractor.js";
 import { wrapIssueReferencesAsLinks, } from "../utils/issue-reference-wrapper.js";
 import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 import { validateReferences } from "../utils/validate-references.js";
 import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
 const VALID_TARGETS = new Set(["markdown", "slack"]);
@@ -58,15 +59,15 @@ async function handleWrap(options, command) {
     const text = typeof options.file === "string" && options.file.length > 0
         ? readFileSync(options.file, "utf8")
         : await readAllStdin();
-    const rootOpts = command.parent.parent.opts();
+    const rootOpts = getRootOpts(command);
     const deps = {
         async resolveValidIdentifiers(ids) {
-            const linearService = createLinearService(rootOpts);
+            const linearService = await createLinearService(rootOpts);
             const map = await validateReferences(ids, linearService);
             return new Set(map.keys());
         },
         async resolveUrlKey() {
-            const graphQLService = createGraphQLService(rootOpts);
+            const graphQLService = await createGraphQLService(rootOpts);
             return getWorkspaceUrlKey(graphQLService);
         },
     };

package/dist/commands/releases.js

@@ -1,6 +1,7 @@
 import { CREATE_RELEASE_MUTATION, GET_RELEASE_BY_ID_QUERY, GET_RELEASE_PIPELINES_QUERY, GET_RELEASES_QUERY, } from "../queries/releases.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 function transformRelease(release) {
     return {
         id: release.id,
@@ -36,8 +37,8 @@ function transformRelease(release) {
     };
 }
 async function handleCreateRelease(name, options, command) {
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
     const pipelines = await graphQLService.rawRequest(GET_RELEASE_PIPELINES_QUERY, { first: 50 });
     const pipelineNodes = pipelines.releasePipelines
         ?.nodes;
@@ -84,8 +85,8 @@ export function setupReleasesCommands(program) {
         .option("--pipeline <pipeline>", "filter by pipeline name or ID")
         .option("-l, --limit <number>", "limit results", "25")
         .action(handleAsyncCommand(async (options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const filter = {};
         if (options.pipeline) {
             filter.pipeline = { name: { eqIgnoreCase: options.pipeline } };
@@ -102,8 +103,8 @@ export function setupReleasesCommands(program) {
         .command("read <releaseId>")
         .description("Get release details including linked documents")
         .action(handleAsyncCommand(async (releaseId, _options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const result = await graphQLService.rawRequest(GET_RELEASE_BY_ID_QUERY, { id: releaseId });
         if (!result.release) {
             throw new Error(`Release "${releaseId}" not found`);
@@ -122,8 +123,8 @@ export function setupReleasesCommands(program) {
         .command("pipelines")
         .description("List release pipelines and their stages")
         .action(handleAsyncCommand(async (_options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const result = await graphQLService.rawRequest(GET_RELEASE_PIPELINES_QUERY, { first: 50 });
         const data = (result.releasePipelines
             ?.nodes ?? []).map((p) => ({

package/dist/commands/search.js

@@ -2,6 +2,7 @@ import { resolveTeam, resolveUserDisplayName } from "../config/resolver.js";
 import { SEMANTIC_SEARCH_QUERY } from "../queries/search.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 const TEMPLATES_QUERY = `
   query {
     templates {
@@ -137,8 +138,8 @@ export function setupSearchCommands(program) {
         .option("--team <team>", "filter issue results by team key")
         .option("-l, --limit <number>", "max results", "10")
         .action(handleAsyncCommand(async (query, options, command) => {
-        const rootOpts = command.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const limit = Number.parseInt(options.limit, 10);
         const requestedTypes = options.type
             ? options.type.split(",").map((t) => t.trim().toLowerCase())

package/dist/commands/teams.js

@@ -1,5 +1,8 @@
+import { loadConfig } from "../config/config.js";
+import { cached, resolveCacheTTL } from "../utils/disk-cache.js";
 import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 export function setupTeamsCommands(program) {
     const teams = program
         .command("teams")
@@ -11,9 +14,17 @@ export function setupTeamsCommands(program) {
         .description("List all teams")
         .option("-l, --limit <number>", "limit results", "100")
         .action(handleAsyncCommand(async (options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const service = createLinearService(rootOpts);
-        const result = await service.getTeams(Number.parseInt(options.limit, 10));
+        const rootOpts = getRootOpts(command);
+        const limit = Number.parseInt(options.limit, 10);
+        const ttl = resolveCacheTTL({
+            configTTL: loadConfig().cacheTTLSeconds,
+            // commander's `--no-cache` produces `cache: false` on the root opts.
+            noCacheFlag: rootOpts.cache === false,
+        });
+        const result = await cached(`teams-list-limit:${limit}`, ttl, async () => {
+            const service = await createLinearService(rootOpts);
+            return service.getTeams(limit);
+        });
         outputSuccess({ data: result, meta: { count: result.length } });
     }));
 }

package/dist/commands/templates.js

@@ -1,6 +1,7 @@
 import { TEMPLATE_BY_ID_QUERY, TEMPLATES_LIST_QUERY, } from "../queries/templates.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 import { parsePositiveInt } from "../utils/validators.js";
 function formatTemplateSummary(t) {
     return {
@@ -25,8 +26,8 @@ export function setupTemplatesCommands(program) {
         .option("--type <type>", "filter by type (issue, document, project, recurringIssue)")
         .option("-l, --limit <number>", "limit results", "50")
         .action(handleAsyncCommand(async (options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const limit = parsePositiveInt(options.limit, "--limit");
         const result = await graphQLService.rawRequest(TEMPLATES_LIST_QUERY);
         let items = result.templates ?? [];
@@ -44,8 +45,8 @@ export function setupTemplatesCommands(program) {
         .command("read <templateId>")
         .description("Read a template including its full content (templateData)")
         .action(handleAsyncCommand(async (templateId, _options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const graphQLService = createGraphQLService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const graphQLService = await createGraphQLService(rootOpts);
         const result = await graphQLService.rawRequest(TEMPLATE_BY_ID_QUERY, {
             id: templateId,
         });

package/dist/commands/users.js

@@ -1,5 +1,6 @@
 import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 export function setupUsersCommands(program) {
     const users = program.command("users").description("User operations");
     users.action(() => users.help());
@@ -9,8 +10,8 @@ export function setupUsersCommands(program) {
         .option("--active", "Only show active users")
         .option("-l, --limit <number>", "limit results", "100")
         .action(handleAsyncCommand(async (options, command) => {
-        const rootOpts = command.parent.parent.opts();
-        const service = createLinearService(rootOpts);
+        const rootOpts = getRootOpts(command);
+        const service = await createLinearService(rootOpts);
         const result = await service.getUsers(options.active, Number.parseInt(options.limit, 10));
         outputSuccess({ data: result, meta: { count: result.length } });
     }));

package/dist/config/config.d.ts

@@ -39,6 +39,43 @@ export interface ElLinearConfig {
      * once per session and caches the result.
      */
     workspaceUrlKey?: string;
+    /**
+     * Text appended to issue descriptions and comment bodies on the `create`
+     * paths. Treated as a literal string — include any `\n\n---\n` separator
+     * yourself if you want a horizontal rule. CLI flags `--footer <text>` and
+     * `--no-footer` override this per-invocation.
+     */
+    messageFooter?: string;
+    /**
+     * Named description boilerplates for `el-linear issues create --template <name>`.
+     * The template's value is used as the description body when `--template` is
+     * provided and neither `--description` nor `--description-file` is set.
+     *
+     * Example:
+     *   "descriptionTemplates": {
+     *     "bug": "## Steps to reproduce\n\n1. ...\n\n## Expected\n\n...\n\n## Actual\n\n..."
+     *   }
+     */
+    descriptionTemplates?: Record<string, string>;
+    /**
+     * Default assignee identifier (alias / display name / email / UUID — same
+     * shapes resolveAssignee accepts) for `issues create`. Applied when
+     * `--assignee` is not passed. Pass `--no-assignee` to override at one site.
+     */
+    defaultAssignee?: string;
+    /**
+     * Default priority for `issues create` / `issues update`. Accepts the same
+     * keywords as the --priority flag: `none|urgent|high|medium|normal|low`
+     * or `0`–`4`. Applied when `--priority` is not passed.
+     */
+    defaultPriority?: string;
+    /**
+     * TTL (seconds) for the on-disk cache used by `teams list`, `labels list`,
+     * and `projects list`. Defaults to 3600 (1 hour) when omitted. A value of
+     * `0` disables the cache entirely. Override per-invocation with
+     * `--no-cache`.
+     */
+    cacheTTLSeconds?: number;
 }
 /** Test seam — resets the cache between test cases. */
 export declare function _resetConfigCacheForTests(): void;

package/dist/config/issue-validation.js

@@ -210,7 +210,7 @@ function checkTitleVerbAlignment(title, typeLabel, result) {
         for (const verb of typeVerbs) {
             if (!verb.includes(" "))
                 continue;
-            if (title.toLowerCase().startsWith(verb.toLowerCase() + " ") ||
+            if (title.toLowerCase().startsWith(`${verb.toLowerCase()} `) ||
                 title.toLowerCase() === verb.toLowerCase()) {
                 if (type === typeLabel)
                     return; // match — all good

package/dist/config/paths.d.ts

@@ -6,6 +6,7 @@
 export declare const CONFIG_DIR: string;
 export declare const CONFIG_PATH: string;
 export declare const TOKEN_PATH: string;
+export declare const TEAM_OAUTH_CONFIG_PATH: string;
 export declare const ALIASES_PROGRESS_PATH: string;
 /**
  * Legacy fallback paths kept for backward compatibility. The CLI was briefly

package/dist/config/paths.js

@@ -9,6 +9,7 @@ import path from "node:path";
 export const CONFIG_DIR = path.join(os.homedir(), ".config", "el-linear");
 export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 export const TOKEN_PATH = path.join(CONFIG_DIR, "token");
+export const TEAM_OAUTH_CONFIG_PATH = path.join(CONFIG_DIR, "team-oauth.json");
 export const ALIASES_PROGRESS_PATH = path.join(CONFIG_DIR, ".init-aliases-progress");
 /**
  * Legacy fallback paths kept for backward compatibility. The CLI was briefly

package/dist/config/resolver.js

@@ -91,7 +91,7 @@ export function resolveMember(input) {
  */
 export async function resolveAssignee(input, rootOpts) {
     if (input.toLowerCase() === "me") {
-        const graphQLService = createGraphQLService(rootOpts);
+        const graphQLService = await createGraphQLService(rootOpts);
         const result = await graphQLService.rawRequest("{ viewer { id } }");
         const viewer = result.viewer;
         if (!viewer?.id) {

package/dist/main.js

@@ -30,13 +30,14 @@ import { splitList } from "./utils/validators.js";
 program
     .name("el-linear")
     .description("A pragmatic CLI for Linear.app — deterministic resolution, structured validation, GraphQL escape hatch.")
-    .version("1.5.0")
+    .version("1.7.0")
     .option("--api-token <token>", "Linear API token")
     .option("--profile <name>", "named profile (under ~/.config/el-linear/profiles/<name>/) for this invocation. Overrides EL_LINEAR_PROFILE env + the on-disk active-profile marker.")
     .option("--json", "output as JSON (default, accepted for compatibility)")
     .option("--raw", "strip { data, meta } wrapper from list output — emit the array directly")
     .option("--jq <filter>", "apply a jq filter to the JSON output")
-    .option("--fields <fields>", "filter output to specific fields (comma-separated)");
+    .option("--fields <fields>", "filter output to specific fields (comma-separated)")
+    .option("--no-cache", "bypass the on-disk cache for `teams list` / `labels list` / `projects list`");
 program.hook("preAction", (_thisCommand, actionCommand) => {
     const rootOpts = actionCommand.optsWithGlobals();
     if (rootOpts.raw) {

package/dist/utils/disk-cache.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Profile-aware disk cache with TTL. Stores JSON envelopes at
+ * `<profile-dir>/cache/<key>.json`:
+ *
+ *   { v: 1, key, fetchedAt, expiresAt, data }
+ *
+ * `cached(key, ttlSeconds, fetcher)`:
+ *   - returns cached `data` when expiresAt > now
+ *   - else awaits fetcher, writes envelope, returns fresh data
+ *   - on read error (corrupt JSON, missing dir), silently refetches
+ *
+ * Bypass:
+ *   - `bypass: true` option always refetches and rewrites (used by --no-cache)
+ *   - any error during write is logged via stderr but doesn't fail the call
+ *
+ * Eviction:
+ *   - no automatic eviction; old keys stay until manually cleared
+ *   - `clearCache(prefix?)` for tests + a future `el-linear cache clear` command
+ *
+ * Path:
+ *   - profile-aware via resolveActiveProfile() — caches don't bleed between
+ *     profiles
+ */
+export interface CacheOptions {
+    /** When true, skip the read step and always refetch + rewrite. */
+    bypass?: boolean;
+}
+/**
+ * Read-through cache wrapper.
+ *
+ *   `key`         — stable string identifier including any filter params
+ *                   (e.g. `teams-list`, `labels-list-team:ENG`)
+ *   `ttlSeconds`  — lifetime; `0` disables the cache entirely (always
+ *                   refetch, never write).
+ *   `fetcher`     — async function returning the fresh data on a miss.
+ *   `options.bypass` — force a refetch even when an unexpired envelope
+ *                      exists. Still rewrites on success.
+ */
+export declare function cached<T>(key: string, ttlSeconds: number, fetcher: () => Promise<T>, options?: CacheOptions): Promise<T>;
+/**
+ * Clear cached entries. With no `prefix`, removes the entire cache
+ * directory. With a `prefix`, only deletes envelopes whose sanitized key
+ * starts with it. Errors (missing dir, permission) are swallowed so this is
+ * safe to call from tests.
+ */
+export declare function clearCache(prefix?: string): Promise<void>;
+/** Resolved cache TTL for command call sites: respects --no-cache + config. */
+export declare function resolveCacheTTL(args: {
+    configTTL: number | undefined;
+    noCacheFlag: boolean | undefined;
+}): number;

package/dist/utils/disk-cache.js

@@ -0,0 +1,178 @@
+/**
+ * Profile-aware disk cache with TTL. Stores JSON envelopes at
+ * `<profile-dir>/cache/<key>.json`:
+ *
+ *   { v: 1, key, fetchedAt, expiresAt, data }
+ *
+ * `cached(key, ttlSeconds, fetcher)`:
+ *   - returns cached `data` when expiresAt > now
+ *   - else awaits fetcher, writes envelope, returns fresh data
+ *   - on read error (corrupt JSON, missing dir), silently refetches
+ *
+ * Bypass:
+ *   - `bypass: true` option always refetches and rewrites (used by --no-cache)
+ *   - any error during write is logged via stderr but doesn't fail the call
+ *
+ * Eviction:
+ *   - no automatic eviction; old keys stay until manually cleared
+ *   - `clearCache(prefix?)` for tests + a future `el-linear cache clear` command
+ *
+ * Path:
+ *   - profile-aware via resolveActiveProfile() — caches don't bleed between
+ *     profiles
+ */
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveActiveProfile } from "../config/paths.js";
+const CACHE_VERSION = 1;
+const CACHE_FILE_MODE = 0o644;
+const CACHE_DIR_MODE = 0o700;
+/**
+ * Resolve `<profile-dir>/cache/`. Profile-aware so caches don't bleed
+ * across profiles. The directory of the active profile's `configPath` is
+ * the canonical "profile dir" — this matches what `commands/init/shared.ts`
+ * uses.
+ */
+function cacheDir() {
+    const active = resolveActiveProfile();
+    return path.join(path.dirname(active.configPath), "cache");
+}
+function cachePath(key) {
+    return path.join(cacheDir(), `${sanitizeKey(key)}.json`);
+}
+/**
+ * Cache keys may include filter values like `team:ENG` or `status:active`,
+ * which are POSIX-safe but we still strip path separators defensively so a
+ * malicious or buggy caller can't write outside the cache directory.
+ */
+function sanitizeKey(key) {
+    return key.replace(/[/\\\0]/g, "_");
+}
+/**
+ * Atomic write: write to a sibling tmp file then rename. Mirrors the helper
+ * in `commands/init/shared.ts` and `auth/oauth-fs.ts`. Duplicated (12 lines)
+ * to keep the dependency graph clean — the wizard depends on cache callers
+ * indirectly, so importing wizard internals here would be a cycle hazard.
+ */
+async function atomicWrite(targetPath, data) {
+    const tmpPath = `${targetPath}.tmp-${randomBytes(8).toString("hex")}`;
+    try {
+        await fs.writeFile(tmpPath, data, {
+            encoding: "utf8",
+            mode: CACHE_FILE_MODE,
+        });
+        await fs.chmod(tmpPath, CACHE_FILE_MODE);
+        await fs.rename(tmpPath, targetPath);
+    }
+    catch (err) {
+        await fs.unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+}
+async function readEnvelope(key) {
+    let raw;
+    try {
+        raw = await fs.readFile(cachePath(key), "utf8");
+    }
+    catch {
+        // Missing dir, missing file, permission errors → treat as cache miss.
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        // Reject envelopes from a future cache version we don't understand.
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            parsed.v !== CACHE_VERSION ||
+            typeof parsed.expiresAt !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        // Corrupt JSON → treat as cache miss.
+        return null;
+    }
+}
+async function writeEnvelope(key, envelope) {
+    const dir = cacheDir();
+    await fs.mkdir(dir, { recursive: true, mode: CACHE_DIR_MODE });
+    await atomicWrite(cachePath(key), JSON.stringify(envelope));
+}
+/**
+ * Read-through cache wrapper.
+ *
+ *   `key`         — stable string identifier including any filter params
+ *                   (e.g. `teams-list`, `labels-list-team:ENG`)
+ *   `ttlSeconds`  — lifetime; `0` disables the cache entirely (always
+ *                   refetch, never write).
+ *   `fetcher`     — async function returning the fresh data on a miss.
+ *   `options.bypass` — force a refetch even when an unexpired envelope
+ *                      exists. Still rewrites on success.
+ */
+export async function cached(key, ttlSeconds, fetcher, options) {
+    // TTL = 0 disables caching: never read, never write.
+    if (ttlSeconds <= 0) {
+        return fetcher();
+    }
+    const now = Date.now();
+    if (!options?.bypass) {
+        const envelope = await readEnvelope(key);
+        if (envelope && envelope.expiresAt > now) {
+            return envelope.data;
+        }
+    }
+    const data = await fetcher();
+    const envelope = {
+        v: CACHE_VERSION,
+        key,
+        fetchedAt: now,
+        expiresAt: now + ttlSeconds * 1000,
+        data,
+    };
+    try {
+        await writeEnvelope(key, envelope);
+    }
+    catch (err) {
+        // Cache writes are best-effort — log to stderr and return the data
+        // anyway so a flaky disk doesn't break the user's command.
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[disk-cache] write failed for "${key}": ${msg}\n`);
+    }
+    return data;
+}
+/**
+ * Clear cached entries. With no `prefix`, removes the entire cache
+ * directory. With a `prefix`, only deletes envelopes whose sanitized key
+ * starts with it. Errors (missing dir, permission) are swallowed so this is
+ * safe to call from tests.
+ */
+export async function clearCache(prefix) {
+    const dir = cacheDir();
+    if (!prefix) {
+        await fs.rm(dir, { recursive: true, force: true });
+        return;
+    }
+    const sanitized = sanitizeKey(prefix);
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    await Promise.all(entries
+        .filter((name) => name.endsWith(".json") && name.startsWith(sanitized))
+        .map((name) => fs.unlink(path.join(dir, name)).catch(() => { })));
+}
+/** Resolved cache TTL for command call sites: respects --no-cache + config. */
+export function resolveCacheTTL(args) {
+    if (args.noCacheFlag) {
+        return 0;
+    }
+    if (args.configTTL === undefined) {
+        return 3600;
+    }
+    return args.configTTL;
+}

package/dist/utils/download-uploads.d.ts

@@ -1,7 +1,8 @@
 import type { LinearIssue } from "../types/linear.js";
+import type { FileService } from "./file-service.js";
 /**
  * Downloads all uploads.linear.app URLs found in an issue's description
  * and comments, replacing them with local file paths so Claude Code
  * can read the images directly.
  */
-export declare function downloadLinearUploads(issue: LinearIssue, apiToken: string): Promise<LinearIssue>;
+export declare function downloadLinearUploads(issue: LinearIssue, fileService: FileService): Promise<LinearIssue>;

package/dist/utils/download-uploads.js

@@ -1,7 +1,6 @@
 import { mkdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { FileService } from "./file-service.js";
 const DOWNLOAD_DIR = join(tmpdir(), "el-linear-downloads");
 const UPLOAD_URL_REGEX = /https:\/\/uploads\.linear\.app\/[^\s)>\]"]+/g;
 function collectUploadUrls(text) {
@@ -20,7 +19,7 @@ function replaceUrls(text, urlMap) {
  * and comments, replacing them with local file paths so Claude Code
  * can read the images directly.
  */
-export async function downloadLinearUploads(issue, apiToken) {
+export async function downloadLinearUploads(issue, fileService) {
     const allUrls = new Set();
     if (issue.description) {
         for (const url of collectUploadUrls(issue.description)) {
@@ -38,7 +37,6 @@ export async function downloadLinearUploads(issue, apiToken) {
         return issue;
     }
     await mkdir(DOWNLOAD_DIR, { recursive: true });
-    const fileService = new FileService(apiToken);
     const urlMap = new Map();
     await Promise.all([...allUrls].map(async (url) => {
         const filename = extractUniqueFilename(url);
@@ -78,7 +76,7 @@ function extractUniqueFilename(url) {
         // Path like /workspace-id/uuid1/uuid2/filename.png — take last two parts for uniqueness
         const parts = urlObj.pathname.split("/").filter(Boolean);
         if (parts.length >= 2) {
-            return `${parts.at(-2).slice(0, 8)}-${parts.at(-1)}`;
+            return `${parts.at(-2)?.slice(0, 8)}-${parts.at(-1) ?? ""}`;
         }
         return parts.at(-1) || "download";
     }

package/dist/utils/file-service.d.ts

@@ -1,7 +1,22 @@
 import type { FileDownloadResult, FileUploadResult } from "../types/linear.js";
+/**
+ * Constructor arg shapes for `FileService`:
+ *   - `string` → personal API token (legacy; sent as `Authorization: <token>`).
+ *   - `{apiKey: string}` → personal API token (explicit).
+ *   - `{oauthToken: string}` → OAuth access token (sent as
+ *     `Authorization: Bearer <token>`).
+ *
+ * The string variant exists because dozens of tests construct `FileService`
+ * with a plain string. We continue to support it indefinitely.
+ */
+export type FileServiceAuth = string | {
+    apiKey: string;
+} | {
+    oauthToken: string;
+};
 export declare class FileService {
-    private readonly apiToken;
-    constructor(apiToken: string);
+    private readonly authHeader;
+    constructor(auth: FileServiceAuth);
     downloadFile(url: string, options?: {
         output?: string;
         overwrite?: boolean;
@@ -11,3 +26,12 @@ export declare class FileService {
     private requestUploadUrl;
     private putFileToUrl;
 }
+import type { AuthOptions } from "./auth.js";
+/**
+ * OAuth-aware factory: resolves the active credential (with auto-refresh
+ * for OAuth tokens) and returns a `FileService` configured with the right
+ * `Authorization` header shape. Personal tokens use `Authorization:
+ * <token>` (no Bearer prefix); OAuth tokens use `Authorization: Bearer
+ * <token>`.
+ */
+export declare function createFileService(options: AuthOptions): Promise<FileService>;

package/dist/utils/file-service.js

@@ -37,10 +37,17 @@ function getMimeType(filePath) {
     const ext = extname(filePath).toLowerCase();
     return MIME_TYPES[ext] || "application/octet-stream";
 }
+function buildAuthHeader(auth) {
+    if (typeof auth === "string")
+        return auth;
+    if ("oauthToken" in auth)
+        return `Bearer ${auth.oauthToken}`;
+    return auth.apiKey;
+}
 export class FileService {
-    apiToken;
-    constructor(apiToken) {
-        this.apiToken = apiToken;
+    authHeader;
+    constructor(auth) {
+        this.authHeader = buildAuthHeader(auth);
     }
     async downloadFile(url, options = {}) {
         if (!isLinearUploadUrl(url)) {
@@ -67,7 +74,7 @@ export class FileService {
             const isSignedUrl = urlObj.searchParams.has("signature");
             const headers = {};
             if (!isSignedUrl) {
-                headers.Authorization = this.apiToken;
+                headers.Authorization = this.authHeader;
             }
             const response = await fetch(url, { method: "GET", headers });
             if (!response.ok) {
@@ -162,7 +169,7 @@ export class FileService {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                Authorization: this.apiToken,
+                Authorization: this.authHeader,
             },
             body: JSON.stringify({
                 query,
@@ -237,3 +244,18 @@ export class FileService {
         return { success: true, assetUrl: meta.assetUrl, filename };
     }
 }
+import { getActiveAuth } from "../auth/token-resolver.js";
+/**
+ * OAuth-aware factory: resolves the active credential (with auto-refresh
+ * for OAuth tokens) and returns a `FileService` configured with the right
+ * `Authorization` header shape. Personal tokens use `Authorization:
+ * <token>` (no Bearer prefix); OAuth tokens use `Authorization: Bearer
+ * <token>`.
+ */
+export async function createFileService(options) {
+    const auth = await getActiveAuth(options);
+    if (auth.kind === "oauth") {
+        return new FileService({ oauthToken: auth.token });
+    }
+    return new FileService({ apiKey: auth.token });
+}