@enrichlayer/el-linear 1.20.0 → 1.21.0

package/README.md

@@ -599,6 +599,30 @@ with `--field`. (Named `--sections` rather than the seemingly-obvious
 `--fields` because `--fields` is already taken at the program level for
 output-key filtering — `el-linear` is the namespace owner.)
 
+### Opt-in includes: `--with`
+
+`issues read --with <names>` adds extra blocks of related data to the
+JSON envelope. Comma-separated; unknown values are rejected with the
+candidate list.
+
+Currently supported:
+
+| Include | What it adds |
+|---------|--------------|
+| `relations` | A top-level `relations` array (outgoing + incoming cross-issue links), built from the same data as `issues related`. |
+
+```bash
+# Issue + its sidebar relations in one call:
+el-linear issues read DEV-123 --with relations
+
+# Across multiple issues — relations fetched per issue in parallel:
+el-linear read DEV-1 DEV-2 --with relations | jq '.data[].relations'
+```
+
+`--with` is JSON-only — it composes with `--jq` / `--fields` / `--raw`,
+and is mutually exclusive with `--field` (which prints raw section text,
+no envelope).
+
 ## Wrapping Linear references in arbitrary text
 
 `el-linear refs wrap` takes plain text on stdin (or via `--file`) and rewrites

package/dist/commands/issues.js

@@ -1000,7 +1000,10 @@ export function setupIssuesCommands(program) {
         .option("--sections <names>", 'Extract multiple named description sections in one call (comma-separated, e.g. "Done when,Out of scope"). ' +
         "Single-issue only. Returns a JSON envelope { identifier, sections: { name -> text|null } }; missing sections appear as null + a _warnings entry. " +
         "Sibling of --field (singular). Named --sections rather than --fields because the program already has a global --fields for output-key filtering.")
-        .addHelpText("after", '\nBoth UUID and identifiers like ABC-123 are supported.\nMultiple IDs: el-linear issue get DEV-123 DEV-456 DEV-789\nExtract a section: el-linear issue read DEV-123 --field "Done when"\nMulti-section: el-linear issue read DEV-123 --sections "Done when,Out of scope"')
+        .option("--with <names>", "Comma-separated opt-in includes. Each value fetches an extra " +
+        'block of data and adds it to the JSON envelope. Currently supported: "relations" ' +
+        "(adds an array of cross-issue relations under a top-level `relations` key).")
+        .addHelpText("after", '\nBoth UUID and identifiers like ABC-123 are supported.\nMultiple IDs: el-linear issue get DEV-123 DEV-456 DEV-789\nExtract a section: el-linear issue read DEV-123 --field "Done when"\nMulti-section: el-linear issue read DEV-123 --sections "Done when,Out of scope"\nWith relations: el-linear issue read DEV-123 --with relations')
         .action(handleAsyncCommand(readIssues));
     issues
         .command("update <issueId>")

package/dist/commands/read-shortcut.js

@@ -1,9 +1,12 @@
+import { GET_ISSUE_RELATIONS_QUERY } from "../queries/issues.js";
 import { downloadLinearUploads } from "../utils/download-uploads.js";
 import { extractField, extractFields } from "../utils/extract-field.js";
 import { createFileService } from "../utils/file-service.js";
 import { createIssuesService } from "../utils/issues-service-bootstrap.js";
 import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
+import { parseWithIncludes, } from "../utils/with-includes.js";
+import { buildIncomingRelationEntries, buildOutgoingRelationEntries, } from "./issues/relations.js";
 /**
  * Issue ID pattern: 1-5 uppercase letters, dash, 1+ digits (e.g. ADM-652, DEV-12).
  */
@@ -26,7 +29,10 @@ export function setupReadShortcut(program) {
         .option("--sections <names>", 'Extract multiple named description sections in one call (comma-separated, e.g. "Done when,Out of scope,Steps"). ' +
         "Single-issue only. Returns a JSON envelope { identifier, sections: { name -> text|null } }; missing sections appear as null + a _warnings entry. " +
         "Sibling of --field (singular). Named --sections rather than --fields because the program already has a global --fields for output-key filtering.")
-        .addHelpText("after", '\nExamples:\n  el-linear read ADM-652\n  el-linear get DEV-123 DEV-456\n  el-linear ADM-652          (auto-detected)\n  el-linear read DEV-123 --field "Done when"   (just that section)\n  el-linear read DEV-123 --sections "Done when,Out of scope"')
+        .option("--with <names>", "Comma-separated opt-in includes. Each value fetches an extra " +
+        'block of data and adds it to the JSON envelope. Currently supported: "relations" ' +
+        "(adds an array of cross-issue relations under a top-level `relations` key).")
+        .addHelpText("after", '\nExamples:\n  el-linear read ADM-652\n  el-linear get DEV-123 DEV-456\n  el-linear ADM-652          (auto-detected)\n  el-linear read DEV-123 --field "Done when"   (just that section)\n  el-linear read DEV-123 --sections "Done when,Out of scope"\n  el-linear read DEV-123 --with relations       (issue + cross-issue links)')
         .action(handleAsyncCommand(readIssues));
     // Catch-all: if argv looks like `el-linear ADM-652 [DEV-123 ...]`, run read
     const originalParse = program.parse.bind(program);
@@ -61,10 +67,16 @@ export function setupReadShortcut(program) {
  */
 export async function readIssues(issueIds, options, command) {
     const rootOpts = getRootOpts(command);
-    const { issuesService } = await createIssuesService(rootOpts);
+    const { graphQLService, issuesService } = await createIssuesService(rootOpts);
     const fileService = await createFileService(rootOpts);
     const fieldName = typeof options.field === "string" ? options.field : null;
     const sectionsRaw = typeof options.sections === "string" ? options.sections : null;
+    // DEV-4476: --with opt-in includes (currently `relations`). Throws on
+    // unknown values via parseWithIncludes — fail fast in the CLI per the
+    // deterministic-CLI doctrine.
+    const includes = typeof options.with === "string"
+        ? parseWithIncludes(options.with)
+        : { relations: false };
     if (fieldName && sectionsRaw) {
         throw new Error("--field and --sections are mutually exclusive. Use --field for a single section (plain-text output) or --sections for multiple (JSON map).");
     }
@@ -87,6 +99,12 @@ export async function readIssues(issueIds, options, command) {
     if (sectionNames !== null && sectionNames.length === 0) {
         throw new Error("--sections was empty after trimming. Pass a comma-separated list of section names.");
     }
+    // --field is also an extract-this-section operation; pairing it with
+    // --with would produce ambiguous output (section text vs. JSON envelope).
+    // Reject up front rather than silently dropping one.
+    if (fieldName && includes.relations) {
+        throw new Error("--field and --with are mutually exclusive (--field outputs raw section text; --with extends the JSON envelope).");
+    }
     if (issueIds.length === 1) {
         const issue = await issuesService.getIssueById(issueIds[0]);
         const resolved = await downloadLinearUploads(issue, fileService);
@@ -124,7 +142,15 @@ export async function readIssues(issueIds, options, command) {
             });
             return;
         }
-        outputSuccess(resolved);
+        // DEV-4476: --with relations (mutually exclusive with --sections, which
+        // returns above). Enrich the single-issue envelope when requested.
+        const envelope = includes.relations
+            ? {
+                ...resolved,
+                relations: await fetchRelations(graphQLService, resolved.id),
+            }
+            : resolved;
+        outputSuccess(envelope);
     }
     else {
         // DEV-4477: one batched GraphQL call instead of N parallel single-issue
@@ -133,7 +159,45 @@ export async function readIssues(issueIds, options, command) {
         // that's HTTP, not GraphQL, and downloadLinearUploads is a no-op when
         // there's nothing to download.
         const issues = await issuesService.getIssuesByRefs(issueIds);
-        const results = await Promise.all(issues.map((issue) => downloadLinearUploads(issue, fileService)));
+        const results = await Promise.all(
+        // Apply --with relations over the batch-fetched issues (DEV-4476),
+        // preserving DEV-4477's single batched GraphQL fetch above — don't
+        // re-fetch per id, which would defeat the batch optimization.
+        issues.map(async (issue) => {
+            const resolved = await downloadLinearUploads(issue, fileService);
+            if (!includes.relations) {
+                return resolved;
+            }
+            return {
+                ...resolved,
+                relations: await fetchRelations(graphQLService, resolved.id),
+            };
+        }));
         outputSuccess(results);
     }
 }
+/**
+ * Fetch relations for a known-UUID issue and flatten outgoing + incoming
+ * via the shared relations builders. `relatedIssue` / `issue` peers that
+ * Linear omits (rare — deleted-relation edge case) are skipped, matching
+ * the `issues related` command's behavior.
+ *
+ * Race semantics: when `result.issue` is null (the issue existed at the
+ * `getIssueById` call upstream but is missing here — Linear deleted /
+ * unarchived it between the two calls), returns `[]` rather than
+ * throwing. The base issue is still emitted, and the caller sees an
+ * empty `relations` array — preferable to failing the whole envelope
+ * for a rare race. This intentionally diverges from `handleRelatedIssues`
+ * (which throws), because that command's *primary* output is relations,
+ * whereas here relations are an opt-in side dish.
+ */
+async function fetchRelations(graphQLService, issueId) {
+    const result = await graphQLService.rawRequest(GET_ISSUE_RELATIONS_QUERY, { id: issueId });
+    if (!result.issue) {
+        return [];
+    }
+    return [
+        ...buildOutgoingRelationEntries(result.issue.relations.nodes),
+        ...buildIncomingRelationEntries(result.issue.inverseRelations.nodes),
+    ];
+}

package/dist/utils/with-includes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `issues read --with` parser (DEV-4476).
+ *
+ * Opt-in includes for `issues read`. Each value names an additional block
+ * of data to fetch alongside the base issue and inject into the JSON
+ * envelope. Comma-separated; whitespace tolerated; unknown values rejected
+ * with a structured error naming the candidates (deterministic-CLI
+ * doctrine — fail fast in the CLI, not in the consumer's script).
+ *
+ * Currently supported:
+ *   - `relations` — fetches `Issue.relations` + `Issue.inverseRelations`
+ *                   and adds a `relations` array to the envelope.
+ *
+ * Reserved for future MRs (the value space is a closed set so adding more
+ * later is back-compat):
+ *   - `children`  — refetch with expanded sub-issue fragment (state,
+ *                   assignee, priority — beyond the default id/identifier/
+ *                   title trio that's already in the envelope).
+ *   - `comments`  — no-op for fetching (comments are already in the
+ *                   default envelope via `_WITH_COMMENTS` fragment) but
+ *                   would gate explicit summary-format rendering.
+ *
+ * Doctrine note: comments are intentionally NOT included today because
+ * adding `--with comments` would imply that comments are *off* by default,
+ * which would be a breaking JSON-shape change.
+ */
+export declare const WITH_INCLUDE_VALUES: readonly ["relations"];
+export type WithInclude = (typeof WITH_INCLUDE_VALUES)[number];
+export interface ParsedWithIncludes {
+    relations: boolean;
+}
+/**
+ * Parse a `--with <names>` argument. Returns a flag object so call sites
+ * read `if (includes.relations)` instead of `Set.has("relations")`.
+ *
+ * Empty / whitespace-only values are caller errors (commander allows
+ * `--with ""` through) — reject with the same message as unknown values
+ * so the user gets one consistent failure mode.
+ */
+export declare function parseWithIncludes(raw: string): ParsedWithIncludes;

package/dist/utils/with-includes.js

@@ -0,0 +1,55 @@
+/**
+ * `issues read --with` parser (DEV-4476).
+ *
+ * Opt-in includes for `issues read`. Each value names an additional block
+ * of data to fetch alongside the base issue and inject into the JSON
+ * envelope. Comma-separated; whitespace tolerated; unknown values rejected
+ * with a structured error naming the candidates (deterministic-CLI
+ * doctrine — fail fast in the CLI, not in the consumer's script).
+ *
+ * Currently supported:
+ *   - `relations` — fetches `Issue.relations` + `Issue.inverseRelations`
+ *                   and adds a `relations` array to the envelope.
+ *
+ * Reserved for future MRs (the value space is a closed set so adding more
+ * later is back-compat):
+ *   - `children`  — refetch with expanded sub-issue fragment (state,
+ *                   assignee, priority — beyond the default id/identifier/
+ *                   title trio that's already in the envelope).
+ *   - `comments`  — no-op for fetching (comments are already in the
+ *                   default envelope via `_WITH_COMMENTS` fragment) but
+ *                   would gate explicit summary-format rendering.
+ *
+ * Doctrine note: comments are intentionally NOT included today because
+ * adding `--with comments` would imply that comments are *off* by default,
+ * which would be a breaking JSON-shape change.
+ */
+export const WITH_INCLUDE_VALUES = ["relations"];
+/**
+ * Parse a `--with <names>` argument. Returns a flag object so call sites
+ * read `if (includes.relations)` instead of `Set.has("relations")`.
+ *
+ * Empty / whitespace-only values are caller errors (commander allows
+ * `--with ""` through) — reject with the same message as unknown values
+ * so the user gets one consistent failure mode.
+ */
+export function parseWithIncludes(raw) {
+    const names = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (names.length === 0) {
+        throw new Error(`--with requires at least one include name. Supported: ${WITH_INCLUDE_VALUES.join(", ")}`);
+    }
+    const includes = { relations: false };
+    for (const name of names) {
+        if (!WITH_INCLUDE_VALUES.includes(name)) {
+            throw new Error(`--with: unknown include "${name}". Supported: ${WITH_INCLUDE_VALUES.join(", ")}`);
+        }
+        // Narrowing: only assignable members of ParsedWithIncludes.
+        if (name === "relations") {
+            includes.relations = true;
+        }
+    }
+    return includes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",