@enrichlayer/el-linear 1.18.1 → 1.20.0

package/dist/commands/read-shortcut.js

@@ -1,8 +1,8 @@
 import { downloadLinearUploads } from "../utils/download-uploads.js";
-import { extractField } from "../utils/extract-field.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 } from "../utils/output.js";
+import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 /**
  * Issue ID pattern: 1-5 uppercase letters, dash, 1+ digits (e.g. ADM-652, DEV-12).
@@ -23,7 +23,10 @@ export function setupReadShortcut(program) {
         .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.")
-        .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)')
+        .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"')
         .action(handleAsyncCommand(readIssues));
     // Catch-all: if argv looks like `el-linear ADM-652 [DEV-123 ...]`, run read
     const originalParse = program.parse.bind(program);
@@ -61,12 +64,28 @@ export async function readIssues(issueIds, options, command) {
     const { issuesService } = await createIssuesService(rootOpts);
     const fileService = await createFileService(rootOpts);
     const fieldName = typeof options.field === "string" ? options.field : null;
-    // --field is single-issue only. With multiple issues, a section
-    // extraction can't sensibly fan out to N different bodies — the
-    // caller almost always wants one section from one issue.
-    if (fieldName && issueIds.length > 1) {
-        throw new Error("--field is single-issue only; pass exactly one issueId. " +
-            "For multiple issues, drop --field and use --jq or --format summary.");
+    const sectionsRaw = typeof options.sections === "string" ? options.sections : null;
+    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).");
+    }
+    // Both --field and --sections are single-issue only — section extraction
+    // can't sensibly fan out to N different bodies, the caller almost always
+    // wants the named sections of one issue.
+    if ((fieldName || sectionsRaw) && issueIds.length > 1) {
+        throw new Error("--field / --sections are single-issue only; pass exactly one issueId. " +
+            "For multiple issues, drop the section flags and use --jq or --format summary.");
+    }
+    // Parse the comma-separated --sections list once. Preserve the caller's
+    // order, trim each entry, and drop empties so trailing commas don't
+    // surface as ghost "" sections.
+    const sectionNames = sectionsRaw
+        ? sectionsRaw
+            .split(",")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)
+        : null;
+    if (sectionNames !== null && sectionNames.length === 0) {
+        throw new Error("--sections was empty after trimming. Pass a comma-separated list of section names.");
     }
     if (issueIds.length === 1) {
         const issue = await issuesService.getIssueById(issueIds[0]);
@@ -83,13 +102,38 @@ export async function readIssues(issueIds, options, command) {
             process.stdout.write(`${section}\n`);
             return;
         }
+        if (sectionNames !== null) {
+            const sectionsMap = extractFields(resolved.description ?? "", sectionNames);
+            const sections = {};
+            const missing = [];
+            for (const [name, text] of sectionsMap) {
+                sections[name] = text;
+                if (text === null)
+                    missing.push(name);
+            }
+            if (missing.length > 0) {
+                // Coalesce: one warning naming every missing section is denser than
+                // N entries and easier for an agent to act on (cycle-1 nit).
+                outputWarning(`sections not found in ${resolved.identifier}'s description: ${missing
+                    .map((n) => `"${n}"`)
+                    .join(", ")}`);
+            }
+            outputSuccess({
+                identifier: resolved.identifier,
+                sections,
+            });
+            return;
+        }
         outputSuccess(resolved);
     }
     else {
-        const results = await Promise.all(issueIds.map(async (id) => {
-            const issue = await issuesService.getIssueById(id);
-            return downloadLinearUploads(issue, fileService);
-        }));
+        // DEV-4477: one batched GraphQL call instead of N parallel single-issue
+        // queries. The service preserves input order and throws notFoundError
+        // on any missing ref. Attachment download still fans out per-issue —
+        // 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)));
         outputSuccess(results);
     }
 }

package/dist/config/migrate-from-personal.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Plan + apply the personal-to-team-backed config slim.
+ *
+ * After the team-config split (DEV-4172 / ALL-964) members typically still
+ * carry full duplicates of the now-shared keys in their personal/profile
+ * configs. The duplicates are silent shadows when identical and silent
+ * divergences when they drift. This module computes a per-file plan:
+ *
+ *  - **Top-level shadowable keys** (`members`, `teams`, `labels`,
+ *    `statusDefaults`, `teamAliases`) are *dropped* only when the personal
+ *    copy is a strict subset of team (zero divergence and zero non-trivial
+ *    personal-only entries). Otherwise the key is left untouched and the
+ *    diff is reported, so a human resolves it.
+ *  - The deprecated `brand: { name, reject }` key is dropped when content-
+ *    identical to an existing team `terms[]` entry; otherwise it is
+ *    *converted* into a personal `terms[]` entry (no shadowing of team).
+ *  - Genuinely personal keys (`defaultTeam`, `defaultLabels`,
+ *    `teamConfigPath`, anything not in the shadowable set or `brand`) are
+ *    never touched.
+ *
+ * Pure: no fs / no process / no logging. The caller does I/O. DEV-4458.
+ */
+/** Top-level keys typically owned by the team config layer. */
+export declare const TEAM_SHADOWABLE_KEYS: readonly ["members", "teams", "labels", "statusDefaults", "teamAliases"];
+export type TeamShadowableKey = (typeof TEAM_SHADOWABLE_KEYS)[number];
+export type JsonValue = string | number | boolean | null | {
+    [k: string]: JsonValue;
+} | JsonValue[];
+export type JsonObject = {
+    [k: string]: JsonValue;
+};
+/** Per-key decision in the plan. */
+export interface KeyAction {
+    key: string;
+    action: "drop" | "keep-divergent" | "keep-additions" | "absent";
+    /** Leaves whose personal value matched team exactly. */
+    matchCount: number;
+    /** Leaves whose personal value differs from team (would be a silent shadow). */
+    divergentCount: number;
+    /** Non-trivial personal-only leaves (would be lost if dropped). */
+    additionCount: number;
+    /** First few divergent / addition paths, for human-readable context. */
+    sampleDivergent?: string[];
+    sampleAdditions?: string[];
+}
+/** What we did with the deprecated `brand` key. */
+export interface BrandAction {
+    status: "absent" | "drop-duplicate" | "convert-to-term" /** Couldn't convert safely (e.g. existing personal `terms` is malformed). */ | "keep-malformed";
+    /** When status === "convert-to-term", the new entry appended to terms[]. */
+    convertedTo?: {
+        canonical: string;
+        reject: string[];
+    };
+    reason?: string;
+}
+export interface MigrationPlan {
+    keys: KeyAction[];
+    brand: BrandAction;
+    warnings: string[];
+}
+export interface MigrationResult {
+    slimmed: JsonObject;
+    plan: MigrationPlan;
+}
+/** A canonical JSON-friendly deep equality. */
+export declare function deepEqual(a: JsonValue, b: JsonValue): boolean;
+/**
+ * Compute the slimmed config + the plan that explains it. Pure.
+ *
+ * @param personal The personal/profile config object as parsed from disk.
+ * @param team     The active team config object as parsed from disk. Pass
+ *                 `{}` if no team config is configured — every shadowable
+ *                 key becomes either `keep-additions` or `keep-divergent`,
+ *                 so nothing gets dropped (correct: without team there is
+ *                 nothing to fall back to).
+ */
+export declare function planMigration(personal: JsonObject, team: JsonObject): MigrationResult;

package/dist/config/migrate-from-personal.js

@@ -0,0 +1,236 @@
+/**
+ * Plan + apply the personal-to-team-backed config slim.
+ *
+ * After the team-config split (DEV-4172 / ALL-964) members typically still
+ * carry full duplicates of the now-shared keys in their personal/profile
+ * configs. The duplicates are silent shadows when identical and silent
+ * divergences when they drift. This module computes a per-file plan:
+ *
+ *  - **Top-level shadowable keys** (`members`, `teams`, `labels`,
+ *    `statusDefaults`, `teamAliases`) are *dropped* only when the personal
+ *    copy is a strict subset of team (zero divergence and zero non-trivial
+ *    personal-only entries). Otherwise the key is left untouched and the
+ *    diff is reported, so a human resolves it.
+ *  - The deprecated `brand: { name, reject }` key is dropped when content-
+ *    identical to an existing team `terms[]` entry; otherwise it is
+ *    *converted* into a personal `terms[]` entry (no shadowing of team).
+ *  - Genuinely personal keys (`defaultTeam`, `defaultLabels`,
+ *    `teamConfigPath`, anything not in the shadowable set or `brand`) are
+ *    never touched.
+ *
+ * Pure: no fs / no process / no logging. The caller does I/O. DEV-4458.
+ */
+/** Top-level keys typically owned by the team config layer. */
+export const TEAM_SHADOWABLE_KEYS = [
+    "members",
+    "teams",
+    "labels",
+    "statusDefaults",
+    "teamAliases",
+];
+/** A canonical JSON-friendly deep equality. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b))
+            return false;
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (typeof a === "object") {
+        const ak = Object.keys(a).sort();
+        const bk = Object.keys(b).sort();
+        if (ak.length !== bk.length)
+            return false;
+        if (ak.some((k, i) => k !== bk[i]))
+            return false;
+        return ak.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+function isTriviallyEmpty(v) {
+    if (v === undefined || v === null)
+        return true;
+    if (Array.isArray(v))
+        return v.length === 0;
+    if (typeof v === "object")
+        return Object.keys(v).length === 0;
+    return false;
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/**
+ * Walk personal and classify each LEAF against team at the same path:
+ *   match     — present in team with the same value
+ *   divergent — present in team with a different value (would silently shadow)
+ *   addition  — absent from team and non-trivially non-empty (would be lost)
+ *
+ * Trivially-empty containers (e.g. `members.handles.github = {}`) are not
+ * counted as additions — dropping them loses no information.
+ */
+function classifyDeep(personal, team, path, out) {
+    if (personal === undefined)
+        return;
+    // Both objects → recurse into keys.
+    if (isPlainObject(personal) && isPlainObject(team)) {
+        for (const k of Object.keys(personal)) {
+            classifyDeep(personal[k], team[k], path ? `${path}.${k}` : k, out);
+        }
+        return;
+    }
+    // Personal is a leaf (primitive / array / object without a matching team obj).
+    if (team === undefined) {
+        if (!isTriviallyEmpty(personal))
+            out.additions.push(path);
+        return;
+    }
+    if (deepEqual(personal, team)) {
+        out.matches += 1;
+    }
+    else {
+        out.divergent.push(path);
+    }
+}
+function planTopLevelKey(key, personal, team) {
+    if (personal === undefined) {
+        return {
+            key,
+            action: "absent",
+            matchCount: 0,
+            divergentCount: 0,
+            additionCount: 0,
+        };
+    }
+    const acc = { matches: 0, divergent: [], additions: [] };
+    classifyDeep(personal, team, key, acc);
+    const action = acc.divergent.length === 0 && acc.additions.length === 0
+        ? "drop"
+        : acc.divergent.length > 0
+            ? "keep-divergent"
+            : "keep-additions";
+    const ka = {
+        key,
+        action,
+        matchCount: acc.matches,
+        divergentCount: acc.divergent.length,
+        additionCount: acc.additions.length,
+    };
+    if (acc.divergent.length > 0)
+        ka.sampleDivergent = acc.divergent.slice(0, 5);
+    if (acc.additions.length > 0)
+        ka.sampleAdditions = acc.additions.slice(0, 5);
+    return ka;
+}
+function readBrand(personal) {
+    const raw = personal.brand;
+    if (!isPlainObject(raw))
+        return null;
+    const name = raw.name;
+    const reject = raw.reject;
+    if (typeof name !== "string")
+        return null;
+    if (!Array.isArray(reject) || !reject.every((r) => typeof r === "string")) {
+        return null;
+    }
+    return { name, reject: reject };
+}
+function readTeamTerms(team) {
+    const t = team.terms;
+    if (!Array.isArray(t))
+        return [];
+    const out = [];
+    for (const e of t) {
+        if (!isPlainObject(e))
+            continue;
+        const canonical = e.canonical;
+        const reject = e.reject;
+        if (typeof canonical !== "string")
+            continue;
+        if (!Array.isArray(reject) || !reject.every((r) => typeof r === "string")) {
+            continue;
+        }
+        out.push({ canonical, reject: reject });
+    }
+    return out;
+}
+function brandMatchesTerm(brand, term) {
+    return brand.name === term.canonical && deepEqual(brand.reject, term.reject);
+}
+/**
+ * Compute the slimmed config + the plan that explains it. Pure.
+ *
+ * @param personal The personal/profile config object as parsed from disk.
+ * @param team     The active team config object as parsed from disk. Pass
+ *                 `{}` if no team config is configured — every shadowable
+ *                 key becomes either `keep-additions` or `keep-divergent`,
+ *                 so nothing gets dropped (correct: without team there is
+ *                 nothing to fall back to).
+ */
+export function planMigration(personal, team) {
+    const warnings = [];
+    const slimmed = { ...personal };
+    const keyActions = TEAM_SHADOWABLE_KEYS.map((key) => planTopLevelKey(key, personal[key], team[key]));
+    for (const ka of keyActions) {
+        if (ka.action === "drop")
+            delete slimmed[ka.key];
+    }
+    // Brand → terms.
+    let brand;
+    const brandShape = readBrand(personal);
+    if (brandShape === null) {
+        brand = { status: "absent" };
+    }
+    else {
+        const teamTerms = readTeamTerms(team);
+        const dup = teamTerms.find((t) => brandMatchesTerm(brandShape, t));
+        if (dup !== undefined) {
+            delete slimmed.brand;
+            brand = {
+                status: "drop-duplicate",
+                reason: `brand is content-identical to team terms entry "${dup.canonical}"`,
+            };
+        }
+        else if (personal.terms !== undefined && !Array.isArray(personal.terms)) {
+            // Refuse to convert: an existing personal `terms` field is not an
+            // array (likely a hand-edit gone wrong). The strict-subset gate
+            // elsewhere never silently destroys info — neither should this
+            // path. Leave brand AND terms as-is; surface as a warning so a
+            // human can resolve.
+            brand = {
+                status: "keep-malformed",
+                reason: "existing personal 'terms' field is not an array; leaving 'brand' and 'terms' untouched for human review",
+            };
+            warnings.push(`Cannot convert deprecated 'brand': existing 'terms' field is not an array (got ${typeof personal.terms}). Left 'brand' and 'terms' as-is — fix 'terms' to a proper array of { canonical, reject } entries and re-run.`);
+        }
+        else {
+            // Convert: append a personal terms entry, drop brand.
+            delete slimmed.brand;
+            const existing = Array.isArray(slimmed.terms)
+                ? slimmed.terms
+                : [];
+            const converted = {
+                canonical: brandShape.name,
+                reject: brandShape.reject,
+            };
+            slimmed.terms = [...existing, { ...converted }];
+            brand = {
+                status: "convert-to-term",
+                convertedTo: converted,
+                reason: teamTerms.length === 0
+                    ? "team config has no terms; converted brand to a personal terms entry"
+                    : "brand does not match any team terms entry; converted to a personal terms entry",
+            };
+            if (teamTerms.length > 0) {
+                warnings.push(`brand on this file diverges from team terms — preserved as a personal terms entry. Review whether the team config should adopt it.`);
+            }
+        }
+    }
+    return { slimmed, plan: { keys: keyActions, brand, warnings } };
+}

package/dist/queries/common.d.ts

@@ -1,2 +1,2 @@
-export declare const COMPLETE_ISSUE_FRAGMENT = "\n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n";
-export declare const COMPLETE_ISSUE_WITH_COMMENTS_FRAGMENT = "\n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n";
+export declare const COMPLETE_ISSUE_FRAGMENT = "\n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n";
+export declare const COMPLETE_ISSUE_WITH_COMMENTS_FRAGMENT = "\n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n";

package/dist/queries/common.js

@@ -16,6 +16,7 @@ const ISSUE_STATE_FRAGMENT = `
   state {
     id
     name
+    type
   }
 `;
 const ISSUE_ASSIGNEE_FRAGMENT = `

package/dist/queries/issue-tree.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tree-fetch query builder for `issues tree <ID>` (DEV-4480).
+ *
+ * GraphQL has no native depth-N recursion, so the query is generated by
+ * nesting `children { nodes { ... } }` N times at build time. This keeps
+ * the *fetch* to a single round-trip even for deep trees, at the cost of
+ * a larger query string.
+ *
+ * Each level fetches the minimal field set needed to render a tree entry:
+ * id, identifier, title, state.{name,type}, assignee.name. State.type is
+ * present so the renderer can flag terminal states (Done / Canceled) and
+ * the caller's `--include-closed` filter can be applied client-side after
+ * the fetch (Linear doesn't accept a top-level filter that scopes to the
+ * issue subtree — the children connection is filterless).
+ *
+ * Depth bounds: `1` (just the root + its direct children) through `5`.
+ * Above 5 the query string grows too large to be useful as a single call;
+ * callers wanting deeper walks should iterate `tree` on leaf nodes.
+ */
+export declare const MIN_TREE_DEPTH = 1;
+export declare const MAX_TREE_DEPTH = 5;
+export declare const DEFAULT_TREE_DEPTH = 3;
+export declare function buildIssueTreeQuery(depth: number): string;
+/**
+ * Shape of a single tree node — used for both the GraphQL response and
+ * the post-filter return value (after `--include-closed` is applied
+ * client-side).
+ */
+export interface IssueTreeNode {
+    id: string;
+    identifier: string;
+    title: string;
+    state: {
+        id: string;
+        name: string;
+        type: string;
+    } | null;
+    assignee: {
+        id: string;
+        name: string;
+    } | null;
+    children?: {
+        nodes: IssueTreeNode[];
+    };
+}
+export interface GetIssueTreeResponse {
+    issue: IssueTreeNode | null;
+}

package/dist/queries/issue-tree.js

@@ -0,0 +1,67 @@
+/**
+ * Tree-fetch query builder for `issues tree <ID>` (DEV-4480).
+ *
+ * GraphQL has no native depth-N recursion, so the query is generated by
+ * nesting `children { nodes { ... } }` N times at build time. This keeps
+ * the *fetch* to a single round-trip even for deep trees, at the cost of
+ * a larger query string.
+ *
+ * Each level fetches the minimal field set needed to render a tree entry:
+ * id, identifier, title, state.{name,type}, assignee.name. State.type is
+ * present so the renderer can flag terminal states (Done / Canceled) and
+ * the caller's `--include-closed` filter can be applied client-side after
+ * the fetch (Linear doesn't accept a top-level filter that scopes to the
+ * issue subtree — the children connection is filterless).
+ *
+ * Depth bounds: `1` (just the root + its direct children) through `5`.
+ * Above 5 the query string grows too large to be useful as a single call;
+ * callers wanting deeper walks should iterate `tree` on leaf nodes.
+ */
+export const MIN_TREE_DEPTH = 1;
+export const MAX_TREE_DEPTH = 5;
+export const DEFAULT_TREE_DEPTH = 3;
+// Field set per tree node — kept minimal so the depth-N query stays small.
+// `state.type` is required client-side for `--no-include-closed` pruning;
+// `state.name` for the [Done]/[Canceled] suffix on terminal nodes.
+// `priority` was intentionally dropped after cycle-1: the ASCII formatter
+// doesn't render it and including it inflates the query string by ~N nodes.
+const TREE_NODE_FIELDS = `
+	id
+	identifier
+	title
+	state { id name type }
+	assignee { id name }
+`;
+/**
+ * Recursive children fragment generator. `depth=0` emits nothing (no
+ * children fetched at this level — terminal); `depth=1` emits a single
+ * `children { nodes { ...fields } }`; higher depths nest further.
+ */
+function buildChildrenBlock(depth) {
+    if (depth <= 0) {
+        return "";
+    }
+    return `
+		children {
+			nodes {
+				${TREE_NODE_FIELDS}
+				${buildChildrenBlock(depth - 1)}
+			}
+		}
+	`;
+}
+export function buildIssueTreeQuery(depth) {
+    if (!Number.isInteger(depth) ||
+        depth < MIN_TREE_DEPTH ||
+        depth > MAX_TREE_DEPTH) {
+        throw new Error(`Tree depth must be an integer in [${MIN_TREE_DEPTH}, ${MAX_TREE_DEPTH}]; got ${depth}`);
+    }
+    return `
+		query GetIssueTree($id: String!) {
+			issue(id: $id) {
+				${TREE_NODE_FIELDS}
+				${buildChildrenBlock(depth)}
+			}
+		}
+	`;
+}

package/dist/queries/issues-types.d.ts

@@ -25,6 +25,12 @@ import type { LinearPriority } from "../types/linear.js";
 interface IdNameRef {
     id: string;
     name: string;
+    /**
+     * Workflow-state type — selected only on state fragments. Optional so
+     * non-state IdNameRef users (project, team, assignee, etc.) stay valid.
+     * DEV-4478.
+     */
+    type?: string;
 }
 interface IdKeyNameRef {
     id: string;
@@ -134,6 +140,12 @@ export interface GetIssueByIdentifierResponse {
         nodes: IssueWithCommentsNode[];
     };
 }
+/** Response shape for `BATCH_GET_ISSUES_QUERY` (DEV-4477). */
+export interface BatchGetIssuesResponse {
+    issues: {
+        nodes: IssueWithCommentsNode[];
+    };
+}
 /** Response shape for `GET_ISSUES_QUERY`. */
 export interface GetIssuesResponse {
     issues: {