@enrichlayer/el-linear 1.10.0 → 1.15.0

package/dist/utils/extract-field.js

@@ -0,0 +1,99 @@
+/**
+ * Extract a named section from a Linear issue's markdown description.
+ *
+ * Linear issue bodies follow a small set of repeated structures —
+ * "Why we need this", "Done when", "Scope", "Out of scope", etc. —
+ * usually as `##` or `###` headers, sometimes as bold pseudo-headers
+ * (`**Done when**`). Agents end up repeatedly piping
+ * `el-linear issues read X | python -c '...desc.find("Done when")...'`
+ * to pull one section out. This helper centralizes that.
+ *
+ * Matching is case-insensitive on the header text. The first matching
+ * header wins. Content is everything between that header and the next
+ * header line (any `#{1,6}` or bold pseudo-header at line start) or EOF,
+ * trimmed of surrounding whitespace.
+ *
+ * Returns `null` when the field isn't found, so callers can distinguish
+ * "missing" from "empty body".
+ */
+// Header forms accepted:
+//   `# ... `, `## ...`, `### ...`, ... up to `######`
+//   `**Done when**`, `**Done when:**` (bold pseudo-headers)
+// Trailing colons after the header text are stripped.
+const ATX_HEADER_RE = /^(?:#{1,6})\s+([^\n]+?)(?::\s*)?\s*$/;
+const BOLD_PSEUDO_HEADER_RE = /^\*\*([^*\n]+?)(?::\s*)?\*\*\s*$/;
+// Fenced code block delimiters per CommonMark: at least three backticks or
+// tildes at the start of a line, with up to 3 leading SPACES of indent (4+
+// is an indented code block, which is a different construct; tabs are not
+// permitted as fence indent per the CommonMark spec). We toggle an inFence
+// flag while scanning so section headers inside code samples don't
+// terminate the real section.
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+function normalize(s) {
+    return s.toLowerCase().trim().replace(/\s+/g, " ");
+}
+// Bold pseudo-header heuristic: any `**...**` line could be a header, but
+// inline emphasis paragraphs (e.g. a single bolded sentence in prose) are
+// false positives. Require either a trailing colon OR ≤6 words so that
+// "**Done when:**" and "**Why we need this**" qualify but "**Note that all
+// downstream consumers ...**" does not.
+function isLikelyBoldHeader(text, hadTrailingColon) {
+    if (hadTrailingColon)
+        return true;
+    const wordCount = text.trim().split(/\s+/).filter(Boolean).length;
+    return wordCount > 0 && wordCount <= 6;
+}
+function matchHeader(line) {
+    const atx = line.match(ATX_HEADER_RE);
+    if (atx)
+        return { text: atx[1] };
+    const bold = line.match(BOLD_PSEUDO_HEADER_RE);
+    if (bold) {
+        const text = bold[1];
+        // match[1] excludes the bold delimiters; the regex consumed a trailing
+        // colon if present, so detect by re-checking the raw line.
+        const hadColon = /:\*\*\s*$/.test(line);
+        if (!isLikelyBoldHeader(text, hadColon))
+            return null;
+        return { text };
+    }
+    return null;
+}
+export function extractField(body, fieldName) {
+    if (!body)
+        return null;
+    const target = normalize(fieldName);
+    const lines = body.split("\n");
+    let inFence = false;
+    let startIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (FENCE_RE.test(lines[i])) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const match = matchHeader(lines[i]);
+        if (!match)
+            continue;
+        if (normalize(match.text) === target) {
+            startIdx = i + 1;
+            break;
+        }
+    }
+    if (startIdx === -1)
+        return null;
+    const out = [];
+    let sectionInFence = false;
+    for (let i = startIdx; i < lines.length; i++) {
+        if (FENCE_RE.test(lines[i])) {
+            sectionInFence = !sectionInFence;
+            out.push(lines[i]);
+            continue;
+        }
+        if (!sectionInFence && matchHeader(lines[i]) !== null)
+            break;
+        out.push(lines[i]);
+    }
+    return out.join("\n").trim();
+}

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

@@ -1,19 +1,12 @@
+import type { LinearCredential } from "../auth/linear-credential.js";
 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.
+ * Constructor arg for `FileService`. Re-exported alias of the shared
+ * `LinearCredential` union (`{ apiKey } | { oauthToken }`). See
+ * `src/auth/linear-credential.ts` for the contract. The bare-string
+ * legacy arm was dropped in DEV-4068 T7.
  */
-export type FileServiceAuth = string | {
-    apiKey: string;
-} | {
-    oauthToken: string;
-};
+export type FileServiceAuth = LinearCredential;
 export declare class FileService {
     private readonly authHeader;
     constructor(auth: FileServiceAuth);

package/dist/utils/file-service.js

@@ -38,8 +38,6 @@ function getMimeType(filePath) {
     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;

package/dist/utils/formatters/summary.js

@@ -591,7 +591,12 @@ function formatGenericInline(v) {
     if (o)
         return s(o.name ?? o.displayName ?? o.identifier ?? o.id ?? "{…}");
     if (typeof v === "string" && v.length > 80) {
-        return `${v.slice(0, 80)}…`;
+        // Route through sanitizeForTerminal (via `s()`) before slicing so that
+        // long strings from the generic-fallback path can't smuggle ANSI
+        // escapes (cursor moves, clear-screen, OSC 8 hyperlinks) into the
+        // user's terminal. Every other branch in this function already goes
+        // through `s()`; this one previously didn't.
+        return `${s(v).slice(0, 80)}…`;
     }
     return s(v);
 }

package/dist/utils/graphql-issues-service.d.ts

@@ -1,7 +1,21 @@
 import type { IssueArchiveEntity, IssueNode, IssueWithCommentsNode } from "../queries/issues-types.js";
-import type { LinearIssue } from "../types/linear.js";
+import type { LinearIssue, LinearPriority } from "../types/linear.js";
 import type { GraphQLService } from "./graphql-service.js";
 import type { LinearService } from "./linear-service.js";
+/**
+ * Project filter for `SearchIssueArgs`. Discriminated on `kind` so the
+ * "filter by project" and "filter to issues with no project" cases are
+ * mutually exclusive at the type level — the old `projectId?: string;
+ * noProject?: boolean` pair allowed `{ projectId: "x", noProject: true }`
+ * to compile but had to be detangled at runtime (`noProject` won by
+ * convention). The discriminant is the contract.
+ */
+export type SearchIssueProject = {
+    kind: "id";
+    id: string;
+} | {
+    kind: "none";
+};
 /**
  * Arguments accepted by `GraphQLIssuesService.searchIssues`. Two
  * modes:
@@ -15,52 +29,80 @@ export interface SearchIssueArgs {
     query?: string;
     /** Team key, name, or UUID. */
     teamId?: string;
-    /** Project name or UUID. */
-    projectId?: string;
-    /** Set true to match only issues with NO project. Mutually
-     * exclusive with `projectId`. */
-    noProject?: boolean;
+    /**
+     * Project filter. `{ kind: "id", id }` filters to a specific project
+     * (name or UUID accepted); `{ kind: "none" }` matches issues with no
+     * project. Undefined leaves the filter off.
+     */
+    project?: SearchIssueProject;
     /** Assignee name, email, alias, or UUID. */
     assigneeId?: string;
+    /** Agent user name, email, alias, or UUID delegated to the issue. */
+    delegateId?: string;
     /** Issue states to include (e.g. `["Todo", "In Progress"]`). */
     status?: string[];
     /** Label names to require (intersection). */
     labelNames?: string[];
     /** Priority values (0-4) to include. */
-    priority?: number[];
+    priority?: LinearPriority[];
     /** Result cap; defaults to 10 when not set. */
     limit?: number;
     /** Linear orderBy enum (`createdAt` / `updatedAt`). */
     orderBy?: string;
 }
 /**
- * Arguments accepted by `GraphQLIssuesService.updateIssue`. Same
- * field shapes as `CreateIssueArgs` (UUID-or-name where applicable),
- * but with `id` required (the issue to update) and `subscriberIds` /
- * `templateId` omitted (not valid on update).
+ * Fields shared by `CreateIssueArgs` and `UpdateIssueArgs`. Both mutations
+ * accept the same scalar/foreign-key fields — only their lifecycle
+ * fields differ. `Create` adds `teamInput`/`subscriberIds`/`templateId`
+ * (initial-state-only); `Update` adds the required `id` and widens
+ * `cycleId` to `| null` (Linear's API uses `null` to detach from a
+ * cycle on update).
+ *
+ * Pre-fix this lived as two parallel 13-field interfaces. A field added
+ * to one would silently diverge from the other; the shared base now
+ * forces a deliberate per-side decision.
  */
-export interface UpdateIssueArgs {
-    /** Issue identifier (e.g. `DEV-3592`) or UUID. Required. */
-    id: string;
+interface IssueMutationFields {
     title?: string;
+    /** Team key, name, or UUID. Required on create unless `templateId` is set. */
+    teamId?: string;
     description?: string;
     /** Assignee name, email, alias, or UUID. */
     assigneeId?: string;
-    priority?: number;
+    /** Agent user name, email, alias, or UUID delegated to work on the issue. */
+    delegateId?: string | null;
+    /** Linear priority: 0 (none), 1 (urgent), 2 (high), 3 (medium), 4 (low). */
+    priority?: LinearPriority;
+    /** Project name or UUID. */
     projectId?: string;
+    /** Status name or UUID — resolved per team. */
     statusId?: string;
-    /**
-     * Hint for the team-aware label resolver when the issue is being
-     * moved between teams.
-     */
-    teamId?: string;
+    /** Label names or UUIDs — auto-created on the team if missing. */
     labelIds?: string[];
+    /** Parent issue identifier or UUID. */
     parentId?: string;
+    /** Project milestone name or UUID — resolved within the project. */
     milestoneId?: string;
-    cycleId?: string | null;
+    /** Due date, ISO 8601. */
     dueDate?: string;
+    /** Story-points / estimate. */
     estimate?: number;
 }
+/**
+ * Arguments accepted by `GraphQLIssuesService.updateIssue`. Same field
+ * shapes as `CreateIssueArgs` (UUID-or-name where applicable), but with
+ * `id` required (the issue to update) and the create-only initial-state
+ * fields (`teamInput` / `subscriberIds` / `templateId`) omitted.
+ */
+export interface UpdateIssueArgs extends IssueMutationFields {
+    /** Issue identifier (e.g. `DEV-3592`) or UUID. Required. */
+    id: string;
+    /**
+     * On update, `null` detaches the issue from its current cycle.
+     * (`undefined` leaves it unchanged; a UUID/number/name moves it.)
+     */
+    cycleId?: string | null;
+}
 /**
  * Arguments accepted by `GraphQLIssuesService.createIssue`. Most fields
  * may be passed as a Linear UUID OR a name/identifier — the service
@@ -73,35 +115,13 @@ export interface UpdateIssueArgs {
  * `assigneeId` compiled cleanly and silently dropped the field. With
  * the typed shape, `tsc` catches the typo.
  */
-export interface CreateIssueArgs {
-    title?: string;
-    /** Team key, name, or UUID. Required unless `templateId` is set. */
-    teamId?: string;
+export interface CreateIssueArgs extends IssueMutationFields {
     /** Original team token (key or name) — used in label resolution error messages. */
     teamInput?: string;
-    description?: string;
-    /** Assignee name, email, alias, or UUID. */
-    assigneeId?: string;
-    /** Linear priority: 0 (none), 1 (urgent), 2 (high), 3 (medium), 4 (low). */
-    priority?: number;
-    /** Project name or UUID. */
-    projectId?: string;
-    /** Status name or UUID — resolved per team. */
-    statusId?: string;
-    /** Label names or UUIDs — auto-created on the team if missing. */
-    labelIds?: string[];
-    /** Parent issue identifier or UUID. */
-    parentId?: string;
-    /** Project milestone name or UUID — resolved within the project. */
-    milestoneId?: string;
-    /** Cycle number, name, or UUID — resolved per team. */
+    /** Cycle number, name, or UUID — resolved per team. (No `null` on create.) */
     cycleId?: string;
     /** Subscriber names, emails, aliases, or UUIDs. */
     subscriberIds?: string[];
-    /** Due date, ISO 8601. */
-    dueDate?: string;
-    /** Story-points / estimate. */
-    estimate?: number;
     /** Linear server-side template UUID for `--from-template`. */
     templateId?: string;
 }
@@ -110,12 +130,26 @@ export interface IssueArchiveOperationResult {
     entity?: IssueArchiveEntity;
     lastSyncId: number;
 }
+export interface StartIssueResult {
+    issue: LinearIssue;
+    previousState?: {
+        id: string;
+        name: string;
+        type: string;
+    };
+    started: boolean;
+    targetState?: {
+        id: string;
+        name: string;
+    };
+}
 export declare class GraphQLIssuesService {
     private readonly graphQLService;
     private readonly linearService;
     constructor(graphQLService: GraphQLService, linearService: LinearService);
     getIssues(limit?: number): Promise<LinearIssue[]>;
     getIssueById(issueId: string): Promise<LinearIssue>;
+    startIssue(issueId: string): Promise<StartIssueResult>;
     updateIssue(args: UpdateIssueArgs, labelMode?: string): Promise<LinearIssue>;
     archiveIssue(issueId: string): Promise<IssueArchiveOperationResult>;
     deleteIssue(issueId: string, options?: {
@@ -124,6 +158,19 @@ export declare class GraphQLIssuesService {
     private extractMilestoneNodes;
     private executeUpdateMutation;
     createIssue(args: CreateIssueArgs): Promise<LinearIssue>;
+    /**
+     * Folds the `@include`-gated `projectsByName` / `projectsById` aliases
+     * from a create batch response into the single `projects` field the
+     * field-resolution helpers expect. At most one project alias is ever
+     * present, since a `--project` input is either a name or a UUID.
+     */
+    private foldCreateBatchResult;
+    /**
+     * Folds the `@include`-gated `projectsByName` / `projectsById` aliases
+     * from an update batch response into the single `projects` field the
+     * field-resolution helpers expect. See `foldCreateBatchResult`.
+     */
+    private foldUpdateBatchResult;
     private resolveCreateFields;
     private executeCreateMutation;
     searchIssues(args: SearchIssueArgs): Promise<LinearIssue[]>;
@@ -149,9 +196,17 @@ export declare class GraphQLIssuesService {
     private applySearchFilters;
     private buildSearchFilter;
     private resolveAssigneeId;
+    private resolveDelegateId;
     private resolveUpdateContext;
     private resolveCycleIdForUpdate;
     private resolveStatusIdForUpdate;
+    /**
+     * Pre-resolve URL/slug-id project inputs to UUIDs before the batch
+     * resolver runs. Plain names and UUIDs pass through unchanged; only
+     * URL/slug-id forms incur a separate slug→UUID round-trip (the batch
+     * query's `name eqIgnoreCase` filter can't match a URL string).
+     */
+    private withNormalizedProjectId;
     private buildCreateResolveVariables;
     private resolveParentId;
     transformIssueData(issue: IssueNode | IssueWithCommentsNode): LinearIssue;
@@ -160,3 +215,4 @@ export declare class GraphQLIssuesService {
     private transformIssueHierarchy;
     private transformIssueComments;
 }
+export {};