@enrichlayer/el-linear 1.2.0

package/dist/queries/releases.js

@@ -0,0 +1,85 @@
+export const GET_RELEASES_QUERY = `
+  query GetReleases($first: Int!, $filter: ReleaseFilter) {
+    releases(first: $first, filter: $filter) {
+      nodes {
+        id
+        name
+        description
+        version
+        url
+        startDate
+        targetDate
+        startedAt
+        completedAt
+        canceledAt
+        stage { id name type color }
+        pipeline { id name }
+        createdAt
+        updatedAt
+      }
+    }
+  }
+`;
+export const GET_RELEASE_BY_ID_QUERY = `
+  query GetReleaseById($id: String!) {
+    release(id: $id) {
+      id
+      name
+      description
+      version
+      url
+      startDate
+      targetDate
+      startedAt
+      completedAt
+      canceledAt
+      stage { id name type color }
+      pipeline { id name }
+      documents {
+        nodes {
+          id
+          title
+          slugId
+        }
+      }
+      createdAt
+      updatedAt
+    }
+  }
+`;
+export const CREATE_RELEASE_MUTATION = `
+  mutation CreateRelease($input: ReleaseCreateInput!) {
+    releaseCreate(input: $input) {
+      success
+      release {
+        id
+        name
+        description
+        version
+        url
+        stage { id name type color }
+        pipeline { id name }
+        createdAt
+        updatedAt
+      }
+    }
+  }
+`;
+export const GET_RELEASE_PIPELINES_QUERY = `
+  query GetReleasePipelines($first: Int!) {
+    releasePipelines(first: $first) {
+      nodes {
+        id
+        name
+        stages {
+          nodes {
+            id
+            name
+            type
+            color
+          }
+        }
+      }
+    }
+  }
+`;

package/dist/queries/search.d.ts

@@ -0,0 +1 @@
+export declare const SEMANTIC_SEARCH_QUERY = "\n  query SemanticSearch($query: String!, $maxResults: Int, $filters: SemanticSearchFilters) {\n    semanticSearch(query: $query, maxResults: $maxResults, filters: $filters) {\n      results {\n        type\n        issue {\n          id\n          identifier\n          title\n          priority\n          state { id name }\n          team { id key name }\n          assignee { id name url }\n          project { id name }\n        }\n        project {\n          id\n          name\n          state\n        }\n        initiative {\n          id\n          name\n          status\n        }\n        document {\n          id\n          title\n          slugId\n          project { id name }\n        }\n      }\n    }\n  }\n";

package/dist/queries/search.js

@@ -0,0 +1,35 @@
+export const SEMANTIC_SEARCH_QUERY = `
+  query SemanticSearch($query: String!, $maxResults: Int, $filters: SemanticSearchFilters) {
+    semanticSearch(query: $query, maxResults: $maxResults, filters: $filters) {
+      results {
+        type
+        issue {
+          id
+          identifier
+          title
+          priority
+          state { id name }
+          team { id key name }
+          assignee { id name url }
+          project { id name }
+        }
+        project {
+          id
+          name
+          state
+        }
+        initiative {
+          id
+          name
+          status
+        }
+        document {
+          id
+          title
+          slugId
+          project { id name }
+        }
+      }
+    }
+  }
+`;

package/dist/queries/templates.d.ts

@@ -0,0 +1,2 @@
+export declare const TEMPLATES_LIST_QUERY = "\n  query {\n    templates {\n      id\n      name\n      type\n      description\n      templateData\n      createdAt\n      updatedAt\n      team { id key name }\n      creator { id name }\n    }\n  }\n";
+export declare const TEMPLATE_BY_ID_QUERY = "\n  query ($id: String!) {\n    template(id: $id) {\n      id\n      name\n      type\n      description\n      templateData\n      createdAt\n      updatedAt\n      team { id key name }\n      creator { id name }\n    }\n  }\n";

package/dist/queries/templates.js

@@ -0,0 +1,30 @@
+export const TEMPLATES_LIST_QUERY = `
+  query {
+    templates {
+      id
+      name
+      type
+      description
+      templateData
+      createdAt
+      updatedAt
+      team { id key name }
+      creator { id name }
+    }
+  }
+`;
+export const TEMPLATE_BY_ID_QUERY = `
+  query ($id: String!) {
+    template(id: $id) {
+      id
+      name
+      type
+      description
+      templateData
+      createdAt
+      updatedAt
+      team { id key name }
+      creator { id name }
+    }
+  }
+`;

package/dist/types/linear.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Core entity types returned by el-linear service methods.
+ * These represent the public API surface — GraphQL responses are
+ * transformed into these shapes at the service boundary.
+ */
+interface TeamRef {
+    id: string;
+    key: string;
+    name: string;
+}
+interface UserRef {
+    id: string;
+    name: string;
+    url?: string;
+}
+interface StateRef {
+    id: string;
+    name: string;
+}
+interface ProjectRef {
+    id: string;
+    name: string;
+}
+interface LabelRef {
+    id: string;
+    name: string;
+}
+interface CycleRef {
+    id: string;
+    name: string;
+    number: number;
+}
+interface MilestoneRef {
+    id: string;
+    name: string;
+    targetDate?: string;
+}
+interface IssueRef {
+    id: string;
+    identifier: string;
+    title: string;
+}
+export interface LinearTeam {
+    description: string | null;
+    id: string;
+    key: string;
+    name: string;
+}
+export interface LinearUser {
+    active: boolean;
+    displayName: string;
+    email: string;
+    id: string;
+    name: string;
+}
+export interface LinearLabel {
+    color: string;
+    group?: LabelRef;
+    id: string;
+    name: string;
+    scope: "team" | "workspace";
+    team?: TeamRef;
+}
+export interface LinearProject {
+    createdAt: string;
+    description?: string;
+    id: string;
+    lead?: UserRef;
+    name: string;
+    progress: number;
+    state: string;
+    targetDate?: string;
+    teams: TeamRef[];
+    updatedAt: string;
+}
+export interface LinearComment {
+    body: string;
+    createdAt: string;
+    embeds?: import("../utils/embed-parser.js").Embed[];
+    id: string;
+    updatedAt: string;
+    user?: UserRef;
+}
+export interface LinearIssue {
+    assignee?: UserRef;
+    branchName?: string;
+    comments?: LinearComment[];
+    createdAt: string;
+    cycle?: CycleRef;
+    description?: string;
+    dueDate?: string;
+    embeds?: import("../utils/embed-parser.js").Embed[];
+    estimate?: number;
+    id: string;
+    identifier: string;
+    labels: LabelRef[];
+    parentIssue?: IssueRef;
+    priority: number;
+    project?: ProjectRef;
+    projectMilestone?: MilestoneRef;
+    state?: StateRef;
+    subIssues?: IssueRef[];
+    summary?: string;
+    team?: TeamRef;
+    title: string;
+    updatedAt: string;
+    url: string;
+}
+export interface LinearCycleSummary {
+    endsAt?: string;
+    id: string;
+    isActive: boolean;
+    isNext?: boolean;
+    isPrevious?: boolean;
+    issueCountHistory?: number[];
+    name?: string;
+    number: number;
+    progress: number;
+    startsAt?: string;
+    team?: TeamRef;
+}
+export interface LinearCycleDetail extends LinearCycleSummary {
+    issues: LinearIssue[];
+}
+export interface LinearDocument {
+    color?: string;
+    content?: string;
+    createdAt?: string;
+    creator?: UserRef;
+    icon?: string;
+    id: string;
+    issue?: IssueRef;
+    project?: ProjectRef;
+    slugId?: string;
+    title: string;
+    updatedAt?: string;
+    url?: string;
+}
+export interface LinearAttachment {
+    createdAt?: string;
+    id: string;
+    title?: string;
+    updatedAt?: string;
+    url: string;
+}
+export interface LinearIssueRelation {
+    id: string;
+    issue: IssueRef;
+    relatedIssue: IssueRef;
+    type: string;
+}
+export interface LinearRelease {
+    canceledAt?: string;
+    completedAt?: string;
+    createdAt: string;
+    description?: string;
+    documents?: {
+        id: string;
+        title: string;
+        slugId: string;
+    }[];
+    id: string;
+    name: string;
+    pipeline?: {
+        id: string;
+        name: string;
+    };
+    stage?: {
+        id: string;
+        name: string;
+        type: string;
+    };
+    startDate?: string;
+    startedAt?: string;
+    targetDate?: string;
+    updatedAt: string;
+    url?: string;
+    version?: string;
+}
+export interface IssueStateSpan {
+    endedAt?: string;
+    startedAt: string;
+    state: StateRef & {
+        type: string;
+    };
+}
+export type FileDownloadResult = {
+    success: true;
+    filePath: string;
+} | {
+    success: false;
+    error: string;
+    statusCode?: number;
+};
+export type FileUploadResult = {
+    success: true;
+    assetUrl: string;
+    filename: string;
+} | {
+    success: false;
+    error: string;
+    statusCode?: number;
+};
+export type GraphQLVariables = Record<string, unknown>;
+/** Primitive values that appear in GraphQL JSON responses. */
+type GraphQLPrimitive = string | number | boolean | null | undefined;
+/** Union of all value types in a raw GraphQL response. */
+type GraphQLValue = GraphQLPrimitive | GraphQLResponseData | GraphQLResponseData[];
+/**
+ * Recursive index type for raw GraphQL responses.
+ * All nested property access requires narrowing via `as GraphQLResponseData`
+ * or `as string` etc. — this prevents `any` from leaking into the type system.
+ */
+export interface GraphQLResponseData {
+    [key: string]: GraphQLValue;
+}
+export {};

package/dist/types/linear.js

@@ -0,0 +1,6 @@
+/**
+ * Core entity types returned by el-linear service methods.
+ * These represent the public API surface — GraphQL responses are
+ * transformed into these shapes at the service boundary.
+ */
+export {};

package/dist/utils/auth.d.ts

@@ -0,0 +1,4 @@
+export interface AuthOptions {
+    apiToken?: string;
+}
+export declare function getApiToken(options: AuthOptions): string;

package/dist/utils/auth.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import { LEGACY_LINCTL_TOKEN_PATH, LEGACY_TOKEN_PATH, TOKEN_PATH, } from "../config/paths.js";
+export function getApiToken(options) {
+    if (options.apiToken) {
+        return options.apiToken;
+    }
+    if (process.env.LINEAR_API_TOKEN) {
+        return process.env.LINEAR_API_TOKEN;
+    }
+    if (fs.existsSync(TOKEN_PATH)) {
+        return fs.readFileSync(TOKEN_PATH, "utf8").trim();
+    }
+    // Fallback to the linctl-era token (the CLI was briefly published as
+    // `@enrichlayer/linctl` then reverted). Kept for one release.
+    if (fs.existsSync(LEGACY_LINCTL_TOKEN_PATH)) {
+        return fs.readFileSync(LEGACY_LINCTL_TOKEN_PATH, "utf8").trim();
+    }
+    // Even older fallback from before the `~/.config/...` move.
+    if (fs.existsSync(LEGACY_TOKEN_PATH)) {
+        return fs.readFileSync(LEGACY_TOKEN_PATH, "utf8").trim();
+    }
+    throw new Error("No API token found. Use --api-token, LINEAR_API_TOKEN env var, ~/.config/el-linear/token, or ~/.linear_api_token file");
+}

package/dist/utils/auto-link-references.d.ts

@@ -0,0 +1,47 @@
+import type { GraphQLService } from "./graphql-service.js";
+import { type IssueRelationType } from "./issue-reference-extractor.js";
+import type { LinearService } from "./linear-service.js";
+export interface AutoLinkLinked {
+    identifier: string;
+    /** True when source/target were swapped on the create (e.g. "blocked by X" → X→source) */
+    reverse: boolean;
+    title: string;
+    type: IssueRelationType;
+}
+export interface AutoLinkSkipped {
+    existingType: string;
+    identifier: string;
+    /** Type that would have been created had the reference been new */
+    inferredType: IssueRelationType;
+}
+export interface AutoLinkFailed {
+    identifier: string;
+    reason: string;
+}
+export interface AutoLinkResult {
+    failed: AutoLinkFailed[];
+    linked: AutoLinkLinked[];
+    skipped: AutoLinkSkipped[];
+}
+interface AutoLinkInput {
+    /** Optional comment bodies to also scan (description wins for type inference on conflicts) */
+    comments?: string[] | undefined;
+    /** Description text to scan for references */
+    description: string | null | undefined;
+    /** When true, skip the create mutation but still report what would be linked */
+    dryRun?: boolean;
+    graphQLService: GraphQLService;
+    /** Human identifier of the source issue (e.g. "EMW-258") — used to skip self-references */
+    identifier: string;
+    /** Resolved UUID of the source issue */
+    issueId: string;
+    linearService: LinearService;
+    /**
+     * Optional pre-resolved Map<identifier, uuid>. When provided, the linker uses these
+     * UUIDs instead of re-calling resolveIssueId. Identifiers absent from the map are
+     * still resolved on-demand (so callers can pass partial maps).
+     */
+    preResolved?: Map<string, string>;
+}
+export declare function autoLinkReferences(input: AutoLinkInput): Promise<AutoLinkResult>;
+export {};

package/dist/utils/auto-link-references.js

@@ -0,0 +1,188 @@
+import { GET_ISSUE_RELATIONS_QUERY, ISSUE_RELATION_CREATE_MUTATION, } from "../queries/issues.js";
+import { extractIssueReferences, } from "./issue-reference-extractor.js";
+function specificity(ref) {
+    if (ref.type === "duplicate") {
+        return 3;
+    }
+    if (ref.type === "blocks") {
+        return 2;
+    }
+    return 1;
+}
+/**
+ * Merge candidates from multiple sources (description, comments) into one list,
+ * keeping the strongest (most-specific) inference per identifier. The first source
+ * wins on ties — so callers should pass description first.
+ */
+function mergeCandidates(...sources) {
+    const byId = new Map();
+    for (const refs of sources) {
+        for (const ref of refs) {
+            const existing = byId.get(ref.identifier);
+            if (!existing || specificity(ref) > specificity(existing)) {
+                byId.set(ref.identifier, ref);
+            }
+        }
+    }
+    return [...byId.values()];
+}
+function mergeRelationNodes(nodes, peerKey, normalizeType, out) {
+    for (const rel of nodes ?? []) {
+        const peer = rel[peerKey];
+        if (!peer) {
+            continue;
+        }
+        const id = peer.identifier;
+        const uuid = peer.id;
+        const type = normalizeType(rel.type);
+        if (id && !out.byIdentifier.has(id)) {
+            out.byIdentifier.set(id, type);
+        }
+        if (uuid && !out.byUuid.has(uuid)) {
+            out.byUuid.set(uuid, type);
+        }
+    }
+}
+async function fetchExistingRelations(issueId, graphQLService) {
+    const result = await graphQLService.rawRequest(GET_ISSUE_RELATIONS_QUERY, {
+        id: issueId,
+    });
+    const issue = result.issue;
+    const out = { byIdentifier: new Map(), byUuid: new Map() };
+    if (!issue) {
+        return out;
+    }
+    const outgoing = issue.relations;
+    mergeRelationNodes(outgoing?.nodes, "relatedIssue", (raw) => raw, out);
+    const incoming = issue.inverseRelations;
+    // Normalize incoming "blocks" → "blockedBy" so the reported type reads naturally
+    mergeRelationNodes(incoming?.nodes, "issue", (raw) => (raw === "blocks" ? "blockedBy" : raw), out);
+    return out;
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function createTypedRelation(ref, sourceId, resolvedId, graphQLService) {
+    const result = await graphQLService.rawRequest(ISSUE_RELATION_CREATE_MUTATION, {
+        input: {
+            issueId: ref.reverse ? resolvedId : sourceId,
+            relatedIssueId: ref.reverse ? sourceId : resolvedId,
+            type: ref.type,
+        },
+    });
+    const create = result.issueRelationCreate;
+    const issueRelation = create?.issueRelation;
+    // The peer (the issue NOT identified by `sourceId`) is whichever side wasn't the source
+    const peerKey = ref.reverse ? "issue" : "relatedIssue";
+    const peer = issueRelation?.[peerKey];
+    return {
+        identifier: peer?.identifier ?? ref.identifier,
+        title: peer?.title ?? "",
+        type: ref.type,
+        reverse: ref.reverse,
+    };
+}
+async function processCandidate(ref, ctx) {
+    const existingType = ctx.existing.byIdentifier.get(ref.identifier);
+    if (existingType) {
+        return {
+            kind: "skipped",
+            entry: {
+                identifier: ref.identifier,
+                existingType,
+                inferredType: ref.type,
+            },
+        };
+    }
+    let resolvedId;
+    const cached = ctx.preResolved?.get(ref.identifier);
+    if (cached) {
+        resolvedId = cached;
+    }
+    else {
+        try {
+            resolvedId = await ctx.linearService.resolveIssueId(ref.identifier);
+        }
+        catch (err) {
+            return {
+                kind: "failed",
+                entry: { identifier: ref.identifier, reason: describeError(err) },
+            };
+        }
+    }
+    if (resolvedId === ctx.sourceId) {
+        return { kind: "self" };
+    }
+    const existingByUuid = ctx.existing.byUuid.get(resolvedId);
+    if (existingByUuid) {
+        return {
+            kind: "skipped",
+            entry: {
+                identifier: ref.identifier,
+                existingType: existingByUuid,
+                inferredType: ref.type,
+            },
+            resolvedId,
+        };
+    }
+    if (ctx.dryRun) {
+        return {
+            kind: "linked",
+            entry: {
+                identifier: ref.identifier,
+                title: "",
+                type: ref.type,
+                reverse: ref.reverse,
+            },
+            resolvedId,
+        };
+    }
+    try {
+        const linked = await createTypedRelation(ref, ctx.sourceId, resolvedId, ctx.graphQLService);
+        return { kind: "linked", entry: linked, resolvedId };
+    }
+    catch (err) {
+        return {
+            kind: "failed",
+            entry: { identifier: ref.identifier, reason: describeError(err) },
+        };
+    }
+}
+export async function autoLinkReferences(input) {
+    const { issueId, identifier, description, comments, graphQLService, linearService, dryRun, preResolved, } = input;
+    const linked = [];
+    const skipped = [];
+    const failed = [];
+    const descriptionRefs = extractIssueReferences(description ?? "", identifier);
+    const commentRefs = (comments ?? []).flatMap((body) => extractIssueReferences(body, identifier));
+    const candidates = mergeCandidates(descriptionRefs, commentRefs);
+    if (candidates.length === 0) {
+        return { linked, skipped, failed };
+    }
+    const existing = await fetchExistingRelations(issueId, graphQLService);
+    const ctx = {
+        sourceId: issueId,
+        existing,
+        dryRun: Boolean(dryRun),
+        graphQLService,
+        linearService,
+        preResolved,
+    };
+    for (const ref of candidates) {
+        const outcome = await processCandidate(ref, ctx);
+        if (outcome.kind === "linked") {
+            linked.push(outcome.entry);
+            // Track in the existing maps so the same ref repeated in input isn't re-linked
+            const recordedType = ref.reverse && ref.type === "blocks" ? "blockedBy" : ref.type;
+            existing.byIdentifier.set(ref.identifier, recordedType);
+            existing.byUuid.set(outcome.resolvedId, recordedType);
+        }
+        else if (outcome.kind === "skipped") {
+            skipped.push(outcome.entry);
+        }
+        else if (outcome.kind === "failed") {
+            failed.push(outcome.entry);
+        }
+    }
+    return { linked, skipped, failed };
+}

package/dist/utils/date-format.d.ts

@@ -0,0 +1,4 @@
+/** Convert a date-like value to an ISO string, falling back to the current time. */
+export declare function toISOStringOrNow(value: string | Date | null | undefined): string;
+/** Convert a date-like value to an ISO string, or return undefined if absent. */
+export declare function toISOStringOrUndefined(value: string | Date | null | undefined): string | undefined;

package/dist/utils/date-format.js

@@ -0,0 +1,8 @@
+/** Convert a date-like value to an ISO string, falling back to the current time. */
+export function toISOStringOrNow(value) {
+    return value ? new Date(value).toISOString() : new Date().toISOString();
+}
+/** Convert a date-like value to an ISO string, or return undefined if absent. */
+export function toISOStringOrUndefined(value) {
+    return value ? new Date(value).toISOString() : undefined;
+}

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

@@ -0,0 +1,7 @@
+import type { LinearIssue } from "../types/linear.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>;