@enrichlayer/el-linear 1.2.0

package/dist/utils/linear-service.js

@@ -0,0 +1,442 @@
+import { LinearClient } from "@linear/sdk";
+import { resolveUserDisplayName } from "../config/resolver.js";
+import { getApiToken } from "./auth.js";
+import { toISOStringOrNow, toISOStringOrUndefined } from "./date-format.js";
+import { multipleMatchesError, notFoundError } from "./error-messages.js";
+import { parseIssueIdentifier } from "./identifier-parser.js";
+import { isUuid } from "./uuid.js";
+const DEFAULT_CYCLE_PAGINATION_LIMIT = 250;
+// The Linear SDK types don't accept string orderBy values, but the API does.
+// This helper avoids repeating the double-cast at every call site.
+function sdkOrderBy(field) {
+    return field;
+}
+// Filter-building helpers for Linear SDK queries.
+function eqFilter(value) {
+    return { eq: value };
+}
+function teamIdFilter(teamId) {
+    return { id: { eq: teamId } };
+}
+function nonEmptyFilter(filter) {
+    return Object.keys(filter).length > 0 ? filter : undefined;
+}
+export class LinearService {
+    client;
+    constructor(apiToken) {
+        this.client = new LinearClient({ apiKey: apiToken });
+    }
+    async resolveIssueId(issueId) {
+        if (isUuid(issueId)) {
+            return issueId;
+        }
+        const { teamKey, issueNumber } = parseIssueIdentifier(issueId);
+        const issues = await this.client.issues({
+            filter: {
+                number: { eq: issueNumber },
+                team: { key: { eq: teamKey } },
+            },
+            first: 1,
+        });
+        if (issues.nodes.length === 0) {
+            throw notFoundError("Issue", issueId);
+        }
+        return issues.nodes[0].id;
+    }
+    async getTeams(limit = 100) {
+        const teamsConnection = await this.client.teams({ first: limit });
+        const teams = teamsConnection.nodes.map((team) => ({
+            id: team.id,
+            key: team.key,
+            name: team.name,
+            description: team.description || null,
+        }));
+        return teams.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async resolveUserId(nameOrEmailOrId) {
+        if (isUuid(nameOrEmailOrId)) {
+            return nameOrEmailOrId;
+        }
+        if (nameOrEmailOrId.includes("@")) {
+            const byEmail = await this.client.users({
+                filter: { email: { eq: nameOrEmailOrId } },
+                first: 1,
+            });
+            if (byEmail.nodes.length > 0) {
+                return byEmail.nodes[0].id;
+            }
+            throw notFoundError("User", nameOrEmailOrId);
+        }
+        const byDisplay = await this.client.users({
+            filter: { displayName: { eqIgnoreCase: nameOrEmailOrId } },
+            first: 5,
+        });
+        if (byDisplay.nodes.length === 1) {
+            return byDisplay.nodes[0].id;
+        }
+        if (byDisplay.nodes.length > 1) {
+            throw multipleMatchesError("User", nameOrEmailOrId, byDisplay.nodes.map((u) => `${u.displayName} (${u.email})`), "use the full email or UUID instead");
+        }
+        const byName = await this.client.users({
+            filter: { name: { containsIgnoreCase: nameOrEmailOrId } },
+            first: 5,
+        });
+        if (byName.nodes.length === 1) {
+            return byName.nodes[0].id;
+        }
+        if (byName.nodes.length > 1) {
+            throw multipleMatchesError("User", nameOrEmailOrId, byName.nodes.map((u) => `${u.name} (${u.email})`), "use the full email or UUID instead");
+        }
+        throw notFoundError("User", nameOrEmailOrId);
+    }
+    async getUsers(activeOnly, limit = 100) {
+        const filter = {};
+        if (activeOnly) {
+            filter.active = eqFilter(true);
+        }
+        const usersConnection = await this.client.users({
+            filter: nonEmptyFilter(filter),
+            first: limit,
+        });
+        const users = usersConnection.nodes.map((user) => ({
+            id: user.id,
+            name: user.name,
+            displayName: user.displayName,
+            email: user.email,
+            active: user.active,
+        }));
+        return users.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async getProjects(limit = 100) {
+        const projects = await this.client.projects({
+            first: limit,
+            orderBy: sdkOrderBy("updatedAt"),
+            includeArchived: false,
+        });
+        const projectsWithData = await Promise.all(projects.nodes.map(async (project) => {
+            const [teams, lead] = await Promise.all([
+                project.teams(),
+                project.lead,
+            ]);
+            return { project, teams, lead };
+        }));
+        return projectsWithData.map(({ project, teams, lead }) => ({
+            id: project.id,
+            name: project.name,
+            description: project.description || undefined,
+            state: project.state,
+            progress: project.progress,
+            teams: teams.nodes.map((team) => ({
+                id: team.id,
+                key: team.key,
+                name: team.name,
+            })),
+            lead: lead ? { id: lead.id, name: lead.name } : undefined,
+            targetDate: toISOStringOrUndefined(project.targetDate),
+            createdAt: toISOStringOrNow(project.createdAt),
+            updatedAt: toISOStringOrNow(project.updatedAt),
+        }));
+    }
+    async resolveTeamId(teamKeyOrNameOrId) {
+        if (isUuid(teamKeyOrNameOrId)) {
+            return teamKeyOrNameOrId;
+        }
+        // 1. Exact match via server-side filter (case-sensitive key, case-insensitive name)
+        const byKey = await this.client.teams({
+            filter: { key: { eq: teamKeyOrNameOrId.toUpperCase() } },
+            first: 1,
+        });
+        if (byKey.nodes.length > 0) {
+            return byKey.nodes[0].id;
+        }
+        const byName = await this.client.teams({
+            filter: { name: { eqIgnoreCase: teamKeyOrNameOrId } },
+            first: 1,
+        });
+        if (byName.nodes.length > 0) {
+            return byName.nodes[0].id;
+        }
+        // 2. No exact match — fetch all teams for prefix matching
+        let page = await this.client.teams({ first: 50 });
+        const allNodes = [...page.nodes];
+        while (page.pageInfo.hasNextPage) {
+            page = await page.fetchNext();
+            allNodes.push(...page.nodes);
+        }
+        const input = teamKeyOrNameOrId.toLowerCase();
+        const prefixMatches = allNodes.filter((team) => team.key.toLowerCase().startsWith(input) ||
+            team.name.toLowerCase().startsWith(input));
+        if (prefixMatches.length === 1) {
+            return prefixMatches[0].id;
+        }
+        if (prefixMatches.length > 1) {
+            throw multipleMatchesError("team", teamKeyOrNameOrId, prefixMatches.map((t) => `${t.key} (${t.name})`), "use a more specific prefix or the full team key");
+        }
+        // 3. No match
+        const available = allNodes.map((t) => `${t.key} (${t.name})`);
+        throw notFoundError("Team", teamKeyOrNameOrId, undefined, `\n  Available teams: ${available.join(", ")}`);
+    }
+    async resolveStatusId(statusName, teamId) {
+        if (isUuid(statusName)) {
+            return statusName;
+        }
+        const filter = {
+            name: { eqIgnoreCase: statusName },
+        };
+        if (teamId) {
+            filter.team = teamIdFilter(teamId);
+        }
+        const statuses = await this.client.workflowStates({
+            filter,
+            first: 1,
+        });
+        if (statuses.nodes.length === 0) {
+            // Fallback: if "Triage" not found, try "Backlog" as a safe default
+            if (statusName.toLowerCase() === "triage" && teamId) {
+                const fallback = await this.client.workflowStates({
+                    filter: {
+                        name: { eqIgnoreCase: "Backlog" },
+                        team: teamIdFilter(teamId),
+                    },
+                    first: 1,
+                });
+                if (fallback.nodes.length > 0) {
+                    return fallback.nodes[0].id;
+                }
+            }
+            throw notFoundError("Status", statusName, teamId ? `for team ${teamId}` : undefined);
+        }
+        return statuses.nodes[0].id;
+    }
+    async buildLabelData(label, scope, team) {
+        const parent = await label.parent;
+        const labelData = {
+            id: label.id,
+            name: label.name,
+            color: label.color,
+            scope,
+            team,
+        };
+        if (parent) {
+            const parentLabel = await this.client.issueLabel(parent.id);
+            labelData.group = { id: parent.id, name: parentLabel.name };
+        }
+        return labelData;
+    }
+    async getLabels(teamFilter, limit = 100) {
+        const labels = [];
+        if (teamFilter) {
+            const teamId = await this.resolveTeamId(teamFilter);
+            const team = await this.client.team(teamId);
+            const teamLabels = await this.client.issueLabels({
+                filter: { team: teamIdFilter(teamId) },
+                first: limit,
+            });
+            const teamRef = { id: team.id, key: team.key, name: team.name };
+            for (const label of teamLabels.nodes) {
+                if (label.isGroup) {
+                    continue;
+                }
+                labels.push(await this.buildLabelData(label, "team", teamRef));
+            }
+        }
+        else {
+            const allLabels = await this.client.issueLabels({ first: limit });
+            for (const label of allLabels.nodes) {
+                if (label.isGroup) {
+                    continue;
+                }
+                const team = await label.team;
+                const scope = team ? "team" : "workspace";
+                const teamRef = team
+                    ? { id: team.id, key: team.key, name: team.name }
+                    : undefined;
+                labels.push(await this.buildLabelData(label, scope, teamRef));
+            }
+        }
+        return { labels };
+    }
+    async createComment(args) {
+        const payload = await this.client.createComment({
+            issueId: args.issueId,
+            body: args.body,
+        });
+        if (!payload.success) {
+            throw new Error("Failed to create comment");
+        }
+        const comment = await payload.comment;
+        if (!comment) {
+            throw new Error("Failed to retrieve created comment");
+        }
+        const user = await comment.user;
+        if (!user) {
+            throw new Error("Failed to retrieve comment user information");
+        }
+        return {
+            id: comment.id,
+            body: comment.body,
+            user: {
+                id: user.id,
+                name: resolveUserDisplayName(user.id, user.name),
+                url: user.url || undefined,
+            },
+            createdAt: comment.createdAt.toISOString(),
+            updatedAt: comment.updatedAt.toISOString(),
+        };
+    }
+    async getCycles(teamFilter, activeOnly, limit) {
+        const filter = {};
+        if (teamFilter) {
+            const teamId = await this.resolveTeamId(teamFilter);
+            filter.team = teamIdFilter(teamId);
+        }
+        if (activeOnly) {
+            filter.isActive = eqFilter(true);
+        }
+        const cyclesConnection = await this.client.cycles({
+            filter: nonEmptyFilter(filter),
+            orderBy: sdkOrderBy("createdAt"),
+            first: limit ?? DEFAULT_CYCLE_PAGINATION_LIMIT,
+        });
+        const cyclesWithData = await Promise.all(cyclesConnection.nodes.map(async (cycle) => {
+            const team = await cycle.team;
+            return {
+                id: cycle.id,
+                name: cycle.name ?? undefined,
+                number: cycle.number,
+                startsAt: toISOStringOrUndefined(cycle.startsAt),
+                endsAt: toISOStringOrUndefined(cycle.endsAt),
+                isActive: cycle.isActive,
+                isPrevious: cycle.isPrevious,
+                isNext: cycle.isNext,
+                progress: cycle.progress,
+                issueCountHistory: cycle.issueCountHistory,
+                team: team
+                    ? { id: team.id, key: team.key, name: team.name }
+                    : undefined,
+            };
+        }));
+        return cyclesWithData;
+    }
+    async getCycleById(cycleId, issuesLimit = 50) {
+        const cycle = await this.client.cycle(cycleId);
+        const [team, issuesConnection] = await Promise.all([
+            cycle.team,
+            cycle.issues({ first: issuesLimit }),
+        ]);
+        const issues = [];
+        for (const issue of issuesConnection.nodes) {
+            const [state, assignee, issueTeam, project, labels] = await Promise.all([
+                issue.state,
+                issue.assignee,
+                issue.team,
+                issue.project,
+                issue.labels(),
+            ]);
+            issues.push({
+                id: issue.id,
+                identifier: issue.identifier,
+                url: issue.url,
+                title: issue.title,
+                description: issue.description || undefined,
+                priority: issue.priority,
+                estimate: issue.estimate || undefined,
+                state: state ? { id: state.id, name: state.name } : undefined,
+                assignee: assignee
+                    ? { id: assignee.id, name: assignee.name }
+                    : undefined,
+                team: issueTeam
+                    ? { id: issueTeam.id, key: issueTeam.key, name: issueTeam.name }
+                    : undefined,
+                project: project ? { id: project.id, name: project.name } : undefined,
+                labels: labels.nodes.map((label) => ({
+                    id: label.id,
+                    name: label.name,
+                })),
+                createdAt: toISOStringOrNow(issue.createdAt),
+                updatedAt: toISOStringOrNow(issue.updatedAt),
+            });
+        }
+        return {
+            id: cycle.id,
+            name: cycle.name ?? undefined,
+            number: cycle.number,
+            startsAt: toISOStringOrUndefined(cycle.startsAt),
+            endsAt: toISOStringOrUndefined(cycle.endsAt),
+            isActive: cycle.isActive,
+            progress: cycle.progress,
+            issueCountHistory: cycle.issueCountHistory,
+            team: team ? { id: team.id, key: team.key, name: team.name } : undefined,
+            issues,
+        };
+    }
+    async resolveCycleId(cycleNameOrId, teamFilter) {
+        if (isUuid(cycleNameOrId)) {
+            return cycleNameOrId;
+        }
+        const filter = {
+            name: { eq: cycleNameOrId },
+        };
+        if (teamFilter) {
+            const teamId = await this.resolveTeamId(teamFilter);
+            filter.team = teamIdFilter(teamId);
+        }
+        const cyclesConnection = await this.client.cycles({
+            filter,
+            first: 10,
+        });
+        const cyclesData = cyclesConnection.nodes;
+        const nodes = [];
+        for (const cycle of cyclesData) {
+            const team = await cycle.team;
+            nodes.push({
+                id: cycle.id,
+                name: cycle.name ?? undefined,
+                number: cycle.number,
+                startsAt: toISOStringOrUndefined(cycle.startsAt),
+                isActive: cycle.isActive,
+                isNext: cycle.isNext,
+                isPrevious: cycle.isPrevious,
+                team: team
+                    ? { id: team.id, key: team.key, name: team.name }
+                    : undefined,
+            });
+        }
+        if (nodes.length === 0) {
+            throw notFoundError("Cycle", cycleNameOrId, teamFilter ? `for team ${teamFilter}` : undefined);
+        }
+        let chosen = nodes.find((n) => n.isActive);
+        if (!chosen) {
+            chosen = nodes.find((n) => n.isNext);
+        }
+        if (!chosen) {
+            chosen = nodes.find((n) => n.isPrevious);
+        }
+        if (!chosen && nodes.length === 1) {
+            chosen = nodes[0];
+        }
+        if (!chosen) {
+            const matches = nodes.map((n) => `${n.id} (${n.team?.key || "?"} / #${n.number} / ${n.startsAt})`);
+            throw multipleMatchesError("cycle", cycleNameOrId, matches, "use an ID or scope with --team");
+        }
+        return chosen.id;
+    }
+    async resolveProjectId(projectNameOrId) {
+        if (isUuid(projectNameOrId)) {
+            return projectNameOrId;
+        }
+        const filter = { name: { eqIgnoreCase: projectNameOrId } };
+        const projectsConnection = await this.client.projects({
+            filter,
+            first: 1,
+        });
+        if (projectsConnection.nodes.length === 0) {
+            throw notFoundError("Project", projectNameOrId);
+        }
+        return projectsConnection.nodes[0].id;
+    }
+}
+export function createLinearService(options) {
+    const apiToken = getApiToken(options);
+    return new LinearService(apiToken);
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,4 @@
+export declare const logger: {
+    info(message: string): void;
+    error(message: string): void;
+};

package/dist/utils/logger.js

@@ -0,0 +1,8 @@
+export const logger = {
+    info(message) {
+        process.stdout.write(`${message}\n`);
+    },
+    error(message) {
+        process.stderr.write(`${message}\n`);
+    },
+};

package/dist/utils/markdown-prosemirror.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Lightweight markdown → ProseMirror document converter.
+ *
+ * Handles the subset of markdown commonly used in Linear comments:
+ * headings, bullet/ordered lists, code blocks, blockquotes, horizontal rules,
+ * and inline marks (bold, italic, code, links).
+ */
+interface ProseMirrorMark {
+    attrs?: Record<string, unknown>;
+    type: string;
+}
+export interface ProseMirrorNode {
+    attrs?: Record<string, unknown>;
+    content?: ProseMirrorNode[];
+    marks?: ProseMirrorMark[];
+    text?: string;
+    type: string;
+}
+export declare function markdownToProseMirror(text: string): ProseMirrorNode;
+/**
+ * Parse inline markdown (bold, italic, code, links) into ProseMirror nodes with marks.
+ */
+export declare function parseInline(text: string): ProseMirrorNode[];
+export {};