wrsmith108/linear-claude-skill
Linear
UnverifiedManaging Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows.
scripts/lib/linear-utils.ts
View on GitHub/**
* Shared Linear API utilities
*
* Common patterns extracted from Linear scripts for consistent
* API key validation, entity lookups, and type definitions.
*/
import { LinearClient } from '@linear/sdk';
import { withRetry } from './retry';
// ============================================================================
// Types
// ============================================================================
/**
* Health status for project and initiative updates
*/
export type HealthStatus = 'onTrack' | 'atRisk' | 'offTrack';
/**
* Valid health status values
*/
export const VALID_HEALTH_VALUES: readonly HealthStatus[] = ['onTrack', 'atRisk', 'offTrack'] as const;
/**
* Project information returned by findProjectByName
*/
export interface ProjectInfo {
id: string;
name: string;
slugId: string;
}
/**
* Initiative information returned by findInitiativeByName
*/
export interface InitiativeInfo {
id: string;
name: string;
description?: string;
}
/**
* Team information returned by findTeamByKey
*/
export interface TeamInfo {
id: string;
key: string;
name: string;
}
/**
* Label lookup result with case-insensitive missing-label reporting
*/
export interface LabelLookupResult {
ids: string[];
found: Array<{ id: string; name: string }>;
missing: string[];
}
// ============================================================================
// Type Guards
// ============================================================================
/**
* Type guard to check if a string is a valid health status
*/
export function isValidHealth(value: string): value is HealthStatus {
return VALID_HEALTH_VALUES.includes(value as HealthStatus);
}
// ============================================================================
// Client Initialization
// ============================================================================
/**
* Create a LinearClient instance with the provided API key
*
* @param apiKey Linear API key
* @returns LinearClient instance
*/
export function createLinearClient(apiKey: string): LinearClient {
return new LinearClient({ apiKey });
}
let _cachedClient: LinearClient | null = null;
/**
* Get a LinearClient instance with API key validation
*
* Reads the API key from LINEAR_API_KEY environment variable.
* Returns a cached instance on subsequent calls.
*
* @throws Error if LINEAR_API_KEY environment variable is not set
* @returns LinearClient instance
*/
export function getLinearClient(): LinearClient {
if (_cachedClient) return _cachedClient;
const apiKey = process.env.LINEAR_API_KEY;
if (!apiKey) {
throw new Error('LINEAR_API_KEY environment variable is required');
}
_cachedClient = createLinearClient(apiKey);
return _cachedClient;
}
// ============================================================================
// Entity Lookups
// ============================================================================
/**
* Find a project by name with exact-match preference
*
* Searches for projects with case-insensitive partial matching.
* If multiple matches are found, prefers exact match (case-insensitive).
*
* @param client LinearClient instance
* @param name Project name to search for
* @returns ProjectInfo or null if not found
*/
export async function findProjectByName(
client: LinearClient,
name: string
): Promise<ProjectInfo | null> {
const projects = await client.projects({
filter: {
name: { containsIgnoreCase: name }
},
first: 10
});
if (projects.nodes.length === 0) {
return null;
}
// Prefer exact match (case-insensitive)
const exactMatch = projects.nodes.find(
p => p.name.toLowerCase() === name.toLowerCase()
);
const project = exactMatch || projects.nodes[0];
return {
id: project.id,
name: project.name,
slugId: project.slugId
};
}
/**
* Find an initiative by name with exact-match preference
*
* Searches for initiatives with case-insensitive partial matching.
* If multiple matches are found, prefers exact match (case-insensitive).
*
* @param client LinearClient instance
* @param name Initiative name to search for
* @returns InitiativeInfo or null if not found
*/
export async function findInitiativeByName(
client: LinearClient,
name: string
): Promise<InitiativeInfo | null> {
const query = `
query FindInitiative($filter: InitiativeFilter!) {
initiatives(filter: $filter, first: 10) {
nodes {
id
name
description
}
}
}
`;
const result = await client.client.rawRequest(query, {
filter: {
name: { containsIgnoreCase: name }
}
});
const data = result.data as { initiatives: { nodes: InitiativeInfo[] } };
const initiatives = data.initiatives.nodes;
if (initiatives.length === 0) {
return null;
}
// Prefer exact match (case-insensitive)
const exactMatch = initiatives.find(
i => i.name.toLowerCase() === name.toLowerCase()
);
return exactMatch || initiatives[0];
}
/**
* Find a team by its key (e.g., "ENG", "PRODUCT")
*
* @param client LinearClient instance
* @param key Team key to search for (case-insensitive)
* @returns TeamInfo or null if not found
*/
export async function findTeamByKey(
client: LinearClient,
key: string
): Promise<TeamInfo | null> {
const query = `
query TeamByKey($filter: TeamFilter!) {
teams(filter: $filter, first: 1) {
nodes {
id
key
name
}
}
}
`;
const result = await client.client.rawRequest(query, {
filter: {
key: { eq: key.toUpperCase() }
}
});
const data = result.data as {
teams: {
nodes: TeamInfo[];
};
};
return data.teams.nodes[0] || null;
}
/**
* Find a team by name with case-insensitive matching
*
* Searches for teams with case-insensitive partial matching.
* If multiple matches are found, prefers exact match (case-insensitive).
*
* @param client LinearClient instance
* @param name Team name to search for
* @returns TeamInfo or null if not found
*/
export async function findTeamByName(
client: LinearClient,
name: string
): Promise<TeamInfo | null> {
const query = `
query TeamByName($filter: TeamFilter!) {
teams(filter: $filter, first: 10) {
nodes {
id
key
name
}
}
}
`;
const result = await client.client.rawRequest(query, {
filter: {
name: { containsIgnoreCase: name }
}
});
const data = result.data as {
teams: {
nodes: TeamInfo[];
};
};
const teams = data.teams.nodes;
if (teams.length === 0) {
return null;
}
// Prefer exact match (case-insensitive)
const exactMatch = teams.find(
t => t.name.toLowerCase() === name.toLowerCase()
);
return exactMatch || teams[0];
}
/**
* Find a workflow state ID by exact name within a team.
*
* @param client LinearClient instance
* @param teamId Linear team UUID
* @param stateName Workflow state name to resolve
* @returns Workflow state ID or null if not found
*/
export async function findWorkflowStateIdByName(
client: LinearClient,
teamId: string,
stateName: string
): Promise<string | null> {
const query = `
query WorkflowStates($filter: WorkflowStateFilter!) {
workflowStates(filter: $filter, first: 1) {
nodes {
id
name
}
}
}
`;
const result = await withRetry(
() => client.client.rawRequest(query, {
filter: {
team: { id: { eq: teamId } },
name: { eq: stateName },
},
}),
{ label: 'linear-utils:workflow-state' }
);
const data = result.data as {
workflowStates: {
nodes: Array<{ id: string; name: string }>;
};
};
return data.workflowStates.nodes[0]?.id || null;
}
/**
* Resolve label names to IDs within a team, matching names case-insensitively.
*
* @param client LinearClient instance
* @param teamId Linear team UUID
* @param labelNames Label names requested by the caller
* @returns Found label IDs plus missing label names
*/
export async function findLabelIdsByName(
client: LinearClient,
teamId: string,
labelNames: string[]
): Promise<LabelLookupResult> {
if (labelNames.length === 0) {
return { ids: [], found: [], missing: [] };
}
const requested = labelNames
.map(name => name.trim())
.filter(name => name.length > 0);
if (requested.length === 0) {
return { ids: [], found: [], missing: [] };
}
const query = `
query Labels($filter: IssueLabelFilter!) {
issueLabels(filter: $filter, first: 250) {
nodes {
id
name
}
}
}
`;
const result = await withRetry(
() => client.client.rawRequest(query, {
filter: {
team: { id: { eq: teamId } },
},
}),
{ label: 'linear-utils:labels' }
);
const data = result.data as {
issueLabels: {
nodes: Array<{ id: string; name: string }>;
};
};
const teamLabels = data.issueLabels.nodes;
const found: Array<{ id: string; name: string }> = [];
const missing: string[] = [];
for (const requestedName of requested) {
const label = teamLabels.find(
candidate => candidate.name.toLowerCase() === requestedName.toLowerCase()
);
if (label) {
found.push(label);
} else {
missing.push(requestedName);
}
}
return {
ids: found.map(label => label.id),
found,
missing,
};
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |