@enrichlayer/el-linear 1.33.0 → 1.34.1

package/dist/commands/issues.js

@@ -1042,8 +1042,30 @@ export function setupIssuesCommands(program) {
     const issues = program
         .command("issues")
         .alias("issue")
-        .description("Issue operations");
-    issues.action(() => issues.help());
+        .description("Issue operations")
+        .argument("[issueId...]", "issue ID(s) to read when no subcommand is given — shorthand for `issues read`")
+        .option("--body", "Print the issue's full description as raw markdown text — no JSON " +
+        "envelope, single-issue only. Exits non-zero if the issue has no " +
+        "description. The whole-body sibling of --field; mutually exclusive " +
+        "with --field / --sections / --with.")
+        .option("--field <name>", 'Extract a single named section from the issue description (e.g. "Done when"). ' +
+        "Matches H2/H3 headers and bold pseudo-headers case-insensitively. " +
+        "Outputs the section text only — no JSON envelope. Single-issue only.")
+        .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.")
+        .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", "\nNo-subcommand shorthand: `el-linear issue DEV-123` behaves like `issues read DEV-123`, " +
+        "including its options (--body, --field, --sections, --with).");
+    issues.action(handleAsyncCommand((issueIds = [], options, command) => {
+        if (issueIds.length === 0) {
+            issues.help();
+            return Promise.resolve();
+        }
+        return readIssues(issueIds, options, command);
+    }));
     // DEV-4480: `issues tree <ID>` lives in its own file because the
     // recursive query builder + ASCII formatter belong together and are
     // substantial enough to warrant the split.

package/dist/utils/formatters/summary.d.ts

@@ -42,6 +42,15 @@ export declare function formatLabelList(labels: unknown[]): string;
  * the row falls back to the stored direction.
  */
 export declare function formatRelationList(relations: unknown[], sourceRef?: string): string;
+/**
+ * Table render for `issues related <id>` — the `{ data: RelatedIssueEntry[] }`
+ * envelope where each entry is `{ type, direction, issue }`. Distinct from
+ * `formatRelationList` (the `issues relate` mutation echo, `{ type, issue,
+ * relatedIssue }` shape): this is the read-path listing of ALL of an issue's
+ * relations, so direction, state, and assignee are surfaced per row instead
+ * of collapsing to a single source-oriented type/target/title line.
+ */
+export declare function formatIssueRelationList(relations: unknown[]): string;
 export declare function formatUserSummary(user: Record<string, unknown>): string;
 export declare function formatUserList(users: unknown[]): string;
 export declare function formatDocumentSummary(doc: Record<string, unknown>): string;
@@ -59,7 +68,7 @@ export declare function formatSearchResultList(results: unknown[]): string;
  * the full payload. Lists fall back to a simple bulleted list.
  */
 export declare function formatGenericSummary(value: unknown): string;
-export type ResourceKind = "issue" | "issue-list" | "project" | "project-list" | "comment" | "comment-list" | "cycle" | "cycle-list" | "milestone" | "milestone-list" | "team-list" | "label-list" | "user" | "user-list" | "document" | "document-list" | "template" | "template-list" | "attachment-list" | "release" | "release-list" | "search-result-list" | "relation-list" | "empty-list" | "generic";
+export type ResourceKind = "issue" | "issue-list" | "project" | "project-list" | "comment" | "comment-list" | "cycle" | "cycle-list" | "milestone" | "milestone-list" | "team-list" | "label-list" | "user" | "user-list" | "document" | "document-list" | "template" | "template-list" | "attachment-list" | "release" | "release-list" | "search-result-list" | "relation-list" | "issue-relation-list" | "empty-list" | "generic";
 /**
  * Heuristic — used by the central `outputSuccess` path which doesn't know
  * which command produced the payload. Looks at the shape of the data to

package/dist/utils/formatters/summary.js

@@ -749,6 +749,42 @@ export function formatRelationList(relations, sourceRef = "—") {
         },
     ], { emptyText: "(no relations)", itemNoun: "relation" });
 }
+/**
+ * Table render for `issues related <id>` — the `{ data: RelatedIssueEntry[] }`
+ * envelope where each entry is `{ type, direction, issue }`. Distinct from
+ * `formatRelationList` (the `issues relate` mutation echo, `{ type, issue,
+ * relatedIssue }` shape): this is the read-path listing of ALL of an issue's
+ * relations, so direction, state, and assignee are surfaced per row instead
+ * of collapsing to a single source-oriented type/target/title line.
+ */
+export function formatIssueRelationList(relations) {
+    const rows = relations.map((raw) => asObj(raw) ?? {});
+    return renderTable(rows, [
+        { header: "RELATION", minWidth: 8, extract: (r) => s(r.type) },
+        { header: "DIRECTION", minWidth: 9, extract: (r) => s(r.direction) },
+        {
+            header: "ID",
+            minWidth: 2,
+            extract: (r) => s(asObj(r.issue)?.identifier),
+        },
+        {
+            header: "STATE",
+            minWidth: 5,
+            extract: (r) => getName(asObj(r.issue)?.state),
+        },
+        {
+            header: "ASSIGNEE",
+            minWidth: 8,
+            extract: (r) => getName(asObj(r.issue)?.assignee),
+        },
+        {
+            header: "TITLE",
+            minWidth: 5,
+            maxWidth: TITLE_TRUNC,
+            extract: (r) => s(asObj(r.issue)?.title),
+        },
+    ], { emptyText: "(no issue relations)", itemNoun: "relation" });
+}
 // ── users ──────────────────────────────────────────────────────
 export function formatUserSummary(user) {
     const name = s(user.name);
@@ -1032,6 +1068,10 @@ function inferListKind(items) {
     // identifier/title, so this must precede the issue-list check below.
     if ("relatedIssue" in sample && "issue" in sample && "type" in sample)
         return "relation-list";
+    // `issues related <id>` rows ({ type, direction, issue }) — the read-path
+    // listing, distinct from the `relatedIssue`-shaped mutation echo above.
+    if ("direction" in sample && "issue" in sample && "type" in sample)
+        return "issue-relation-list";
     if ("identifier" in sample && "title" in sample) {
         // could be issue or search result
         if ("type" in sample && !("templateData" in sample)) {
@@ -1154,6 +1194,8 @@ export function dispatch(kind, payload, fields) {
             return formatSearchResultList(list ?? []);
         case "relation-list":
             return formatRelationList(list ?? [], s(asObj(obj?.meta)?.source));
+        case "issue-relation-list":
+            return formatIssueRelationList(list ?? []);
         case "empty-list":
             return "(no results)";
         case "generic":

package/dist/utils/linear-service.js

@@ -131,20 +131,32 @@ export class LinearService {
         else if (options.excludeStates && options.excludeStates.length > 0) {
             filter.state = { nin: options.excludeStates };
         }
-        if (options.teamId) {
-            filter.teams = { some: { id: { eq: options.teamId } } };
-        }
         // `limit === 0` means "no limit" — paginate the full result set.
         // Otherwise a single page of `limit` projects. DEV-4175: `--all` /
         // `--limit 0` must return every project so callers never make a false
         // "does not exist" determination off a silently truncated page.
         const unlimited = limit === 0;
-        let page = await this.client.projects({
-            filter: nonEmptyFilter(filter),
-            first: unlimited ? 250 : limit,
-            orderBy: sdkOrderBy("updatedAt"),
-            includeArchived: false,
-        });
+        // DEV-5325: ProjectFilter has no `teams` relation filter — the
+        // `teams: { some: … }` shape this used since DEV-4165 errors against
+        // the live GraphQL schema ('Field "teams" is not defined by type
+        // "ProjectFilter"'). Team scoping queries from the team side instead:
+        // `Team.projects` accepts the same name/state ProjectFilter and
+        // paginates identically, keeping the filter server-side. (Args stay
+        // inline in each branch so `sdkOrderBy`'s generic keeps its contextual
+        // type from the SDK signature.)
+        let page = options.teamId
+            ? await (await this.client.team(options.teamId)).projects({
+                filter: nonEmptyFilter(filter),
+                first: unlimited ? 250 : limit,
+                orderBy: sdkOrderBy("updatedAt"),
+                includeArchived: false,
+            })
+            : await this.client.projects({
+                filter: nonEmptyFilter(filter),
+                first: unlimited ? 250 : limit,
+                orderBy: sdkOrderBy("updatedAt"),
+                includeArchived: false,
+            });
         const projectNodes = [...page.nodes];
         if (unlimited) {
             while (page.pageInfo.hasNextPage) {
@@ -516,25 +528,21 @@ export class LinearService {
             throw notFoundError("Project", projectInput);
         }
         // DEV-4103: scope by team when provided so a name shared across teams
-        // doesn't resolve to a different team's project. Same SDK filter shape
-        // `getProjects` already uses for `--team` filtering.
+        // doesn't resolve to a different team's project. DEV-5325: the scoping
+        // goes through `Team.projects` (same as `getProjects`) — ProjectFilter
+        // rejects a `teams` relation filter against the live schema.
         const teamId = teamInput ? await this.resolveTeamId(teamInput) : undefined;
         const filter = {
             name: { eqIgnoreCase: projectInput },
         };
-        if (teamId) {
-            // Matches the filter shape `getProjects` uses for `--team`.
-            filter.teams = { some: { id: { eq: teamId } } };
-        }
         // `first: 5` is wide enough to detect ambiguity (same name across
         // multiple teams) without paying for a deeper page. Linear's UI caps
         // effective project-name collisions at a handful in practice; if a
         // workspace ever exceeds this we'll see it as a still-ambiguous error
         // listing the first 5 teams — better than a silent wrong pick.
-        const projectsConnection = await this.client.projects({
-            filter,
-            first: 5,
-        });
+        const projectsConnection = teamId
+            ? await (await this.client.team(teamId)).projects({ filter, first: 5 })
+            : await this.client.projects({ filter, first: 5 });
         if (projectsConnection.nodes.length === 0) {
             const context = teamInput ? `on team "${teamInput}"` : undefined;
             throw notFoundError("Project", projectInput, context);

package/dist/utils/output.js

@@ -40,9 +40,58 @@ export function setOutputFormat(format) {
 export function getOutputFormat() {
     return outputFormat;
 }
-function filterFields(obj, fields) {
+/**
+ * Resolve a dot-separated path against a value (`a.b.c`; array indices are
+ * numeric segments, `items.0.id`). Returns `undefined` when any segment is
+ * missing so callers can distinguish "missing" from a real `null` value.
+ * Same path grammar as el-git's `--field` selector — keeping the two flags'
+ * semantics aligned is the point (DEV-5323).
+ */
+function getNestedPath(obj, path) {
+    let cur = obj;
+    for (const seg of path.split(".")) {
+        if (cur === null || cur === undefined || typeof cur !== "object") {
+            return undefined;
+        }
+        cur = cur[seg];
+    }
+    return cur;
+}
+/**
+ * Project `obj` down to the requested fields.
+ *
+ * - Top-level keys copy through as before.
+ * - Dot-separated paths (DEV-5323) resolve nested values; the requested path
+ *   string becomes a flat output key (`{"pipeline.status": "success"}`), so
+ *   consumers read exactly what they asked for.
+ * - A field that resolves nowhere is emitted as an explicit `null` AND
+ *   reported via `unresolved` — never silently omitted. Silent omission made
+ *   a typo'd field indistinguishable from an empty value (DEV-5323).
+ * - For arrays, each item is projected; a field counts as unresolved only
+ *   when it resolves on NO item (heterogeneous lists legitimately have
+ *   per-item gaps).
+ */
+function filterFields(obj, fields, unresolved) {
     if (Array.isArray(obj)) {
-        return obj.map((item) => filterFields(item, fields));
+        const resolvedSomewhere = new Set();
+        const items = obj.map((item) => {
+            const perItem = new Set();
+            const projected = filterFields(item, fields, perItem);
+            for (const field of fields) {
+                if (!perItem.has(field)) {
+                    resolvedSomewhere.add(field);
+                }
+            }
+            return projected;
+        });
+        if (unresolved) {
+            for (const field of fields) {
+                if (!resolvedSomewhere.has(field)) {
+                    unresolved.add(field);
+                }
+            }
+        }
+        return items;
     }
     if (obj !== null && typeof obj === "object") {
         const source = obj;
@@ -50,7 +99,17 @@ function filterFields(obj, fields) {
         for (const field of fields) {
             if (field in source) {
                 result[field] = source[field];
+                continue;
             }
+            const nested = field.includes(".")
+                ? getNestedPath(source, field)
+                : undefined;
+            if (nested !== undefined) {
+                result[field] = nested;
+                continue;
+            }
+            result[field] = null;
+            unresolved?.add(field);
         }
         return result;
     }
@@ -143,18 +202,41 @@ export function outputSuccess(data) {
     // (project.name, teams[].key) the formatter needs to render. Skip the
     // JSON filter when summary is active and let the formatter do the work.
     if (fieldsFilter && outputFormat !== "summary") {
+        const unresolved = new Set();
         if (Array.isArray(output)) {
-            output = filterFields(output, fieldsFilter);
+            output = filterFields(output, fieldsFilter, unresolved);
         }
         else if (output !== null && typeof output === "object") {
             const obj = output;
             if (Array.isArray(obj.data)) {
-                output = { ...obj, data: filterFields(obj.data, fieldsFilter) };
+                output = {
+                    ...obj,
+                    data: filterFields(obj.data, fieldsFilter, unresolved),
+                };
+            }
+            else if (obj.data !== null &&
+                obj.data !== undefined &&
+                typeof obj.data === "object") {
+                // Envelope with an OBJECT data payload (e.g. el-git context):
+                // project inside `data`, same as the array branch. Before
+                // DEV-5323 this fell through to root filtering, so
+                // `--fields branch,issueId` on an envelope returned `{}`.
+                // Paths are relative to `data` for every envelope shape.
+                output = {
+                    ...obj,
+                    data: filterFields(obj.data, fieldsFilter, unresolved),
+                };
             }
             else {
-                output = filterFields(output, fieldsFilter);
+                output = filterFields(output, fieldsFilter, unresolved);
             }
         }
+        if (unresolved.size > 0) {
+            // Fail-visible: the projected keys carry explicit nulls and this
+            // warning names them, so a typo'd/missing field is never mistaken
+            // for an empty value (DEV-5323).
+            outputWarning(`fields_unresolved: ${[...unresolved].join(", ")} did not resolve on this payload (emitted as null). Paths are dot-separated and relative to the envelope's data when one is present.`);
+        }
     }
     // summary format takes the post-raw value and renders it as a
     // human-readable block. We bypass the jq path because jq is a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.33.0",
+  "version": "1.34.1",
   "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",