@enrichlayer/el-linear 1.9.0 → 1.15.0

package/dist/commands/labels.js

@@ -4,9 +4,9 @@ import { CREATE_LABEL_MUTATION, FIND_PARENT_LABEL_QUERY, RESTORE_LABEL_MUTATION,
 import { cached, resolveCacheTTL } from "../utils/disk-cache.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { createLinearService } from "../utils/linear-service.js";
-import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { handleAsyncCommand, outputSuccess, warnIfTruncated, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
-import { validateHexColor } from "../utils/validators.js";
+import { parsePositiveInt, validateHexColor } from "../utils/validators.js";
 async function handleCreateLabel(name, options, command) {
     const rootOpts = getRootOpts(command);
     const teamId = resolveTeam(options.team);
@@ -23,45 +23,35 @@ async function handleCreateLabel(name, options, command) {
             name: options.parent,
             teamId,
         });
-        const issueLabels = parentResult.issueLabels;
-        const nodes = issueLabels?.nodes;
-        const parentLabel = nodes?.[0];
+        const parentLabel = parentResult.issueLabels.nodes[0];
         if (parentLabel) {
             input.parentId = parentLabel.id;
         }
     }
-    const result = await graphQLService.rawRequest(CREATE_LABEL_MUTATION, {
-        input,
-    });
-    const createResult = result.issueLabelCreate;
-    if (!createResult?.success) {
+    const result = await graphQLService.rawRequest(CREATE_LABEL_MUTATION, { input });
+    if (!result.issueLabelCreate.success || !result.issueLabelCreate.issueLabel) {
         throw new Error(`Failed to create label "${name}"`);
     }
-    outputSuccess(createResult.issueLabel);
+    outputSuccess(result.issueLabelCreate.issueLabel);
 }
 async function handleRetireLabel(labelId, _options, command) {
     const rootOpts = getRootOpts(command);
     const graphQLService = await createGraphQLService(rootOpts);
-    const result = await graphQLService.rawRequest(RETIRE_LABEL_MUTATION, {
-        id: labelId,
-    });
-    const retireResult = result.issueLabelRetire;
-    if (!retireResult?.success) {
+    const result = await graphQLService.rawRequest(RETIRE_LABEL_MUTATION, { id: labelId });
+    if (!result.issueLabelRetire.success || !result.issueLabelRetire.issueLabel) {
         throw new Error(`Failed to retire label "${labelId}"`);
     }
-    outputSuccess(retireResult.issueLabel);
+    outputSuccess(result.issueLabelRetire.issueLabel);
 }
 async function handleRestoreLabel(labelId, _options, command) {
     const rootOpts = getRootOpts(command);
     const graphQLService = await createGraphQLService(rootOpts);
-    const result = await graphQLService.rawRequest(RESTORE_LABEL_MUTATION, {
-        id: labelId,
-    });
-    const restoreResult = result.issueLabelRestore;
-    if (!restoreResult?.success) {
+    const result = await graphQLService.rawRequest(RESTORE_LABEL_MUTATION, { id: labelId });
+    if (!result.issueLabelRestore.success ||
+        !result.issueLabelRestore.issueLabel) {
         throw new Error(`Failed to restore label "${labelId}"`);
     }
-    outputSuccess(restoreResult.issueLabel);
+    outputSuccess(result.issueLabelRestore.issueLabel);
 }
 export function setupLabelsCommands(program) {
     const labels = program
@@ -79,7 +69,7 @@ export function setupLabelsCommands(program) {
         const rootOpts = getRootOpts(command);
         const teamFilter = options.team ? resolveTeam(options.team) : undefined;
         const nameFilter = options.name;
-        const limit = Number.parseInt(options.limit, 10);
+        const limit = parsePositiveInt(options.limit, "--limit");
         const ttl = resolveCacheTTL({
             configTTL: loadConfig().cacheTTLSeconds,
             noCacheFlag: rootOpts.cache === false,
@@ -92,6 +82,7 @@ export function setupLabelsCommands(program) {
             const service = await createLinearService(rootOpts);
             return service.getLabels(teamFilter, limit, nameFilter);
         });
+        warnIfTruncated(result.labels.length, limit);
         outputSuccess({
             data: result.labels,
             meta: { count: result.labels.length },

package/dist/commands/profile.js

@@ -48,6 +48,7 @@ export function setupProfileCommands(program) {
             data: {
                 name: active.name ?? "<default>",
                 configPath: active.configPath,
+                localConfigPath: active.localConfigPath,
                 tokenPath: active.tokenPath,
             },
         });

package/dist/commands/project-milestones.js

@@ -5,7 +5,7 @@ import { createLinearService, } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { isUuid } from "../utils/uuid.js";
-import { validateIsoDate } from "../utils/validators.js";
+import { parsePositiveInt, validateIsoDate } from "../utils/validators.js";
 async function resolveMilestoneId(milestoneNameOrId, graphQLService, linearService, projectNameOrId) {
     if (isUuid(milestoneNameOrId)) {
         return milestoneNameOrId;
@@ -17,22 +17,17 @@ async function resolveMilestoneId(milestoneNameOrId, graphQLService, linearServi
             name: milestoneNameOrId,
             projectId,
         });
-        const projectData = findRes.project;
-        const milestonesData = projectData?.projectMilestones;
-        nodes = milestonesData?.nodes || [];
+        nodes = findRes.project?.projectMilestones.nodes ?? [];
     }
     if (nodes.length === 0) {
-        const globalRes = await graphQLService.rawRequest(FIND_PROJECT_MILESTONE_BY_NAME_GLOBAL, {
-            name: milestoneNameOrId,
-        });
-        const globalMilestones = globalRes.projectMilestones;
-        nodes = globalMilestones?.nodes || [];
+        const globalRes = await graphQLService.rawRequest(FIND_PROJECT_MILESTONE_BY_NAME_GLOBAL, { name: milestoneNameOrId });
+        nodes = globalRes.projectMilestones.nodes;
     }
     if (nodes.length === 0) {
         throw notFoundError("Milestone", milestoneNameOrId);
     }
     if (nodes.length > 1) {
-        const matches = nodes.map((m) => `"${m.name}" in project "${m.project?.name}"`);
+        const matches = nodes.map((m) => `"${m.name}" in project "${m.project.name}"`);
         throw multipleMatchesError("milestone", milestoneNameOrId, matches, "specify --project or use the milestone ID");
     }
     return nodes[0].id;
@@ -44,11 +39,9 @@ async function handleListMilestones(options, command) {
     const projectId = await linearService.resolveProjectId(options.project);
     const result = await graphQLService.rawRequest(LIST_PROJECT_MILESTONES_QUERY, {
         projectId,
-        first: Number.parseInt(options.limit || "50", 10),
+        first: parsePositiveInt(options.limit || "50", "--limit"),
     });
-    const projectData = result.project;
-    const milestonesData = projectData?.projectMilestones;
-    const nodes = milestonesData?.nodes || [];
+    const nodes = result.project?.projectMilestones.nodes ?? [];
     outputSuccess({ data: nodes, meta: { count: nodes.length } });
 }
 async function handleReadMilestone(milestoneIdOrName, options, command) {
@@ -76,11 +69,11 @@ async function handleCreateMilestone(name, options, command) {
         description: options.description,
         targetDate: options.targetDate,
     });
-    const createData = result.projectMilestoneCreate;
-    if (!createData?.success) {
+    if (!result.projectMilestoneCreate.success ||
+        !result.projectMilestoneCreate.projectMilestone) {
         throw new Error("Failed to create project milestone");
     }
-    outputSuccess(createData.projectMilestone);
+    outputSuccess(result.projectMilestoneCreate.projectMilestone);
 }
 async function handleUpdateMilestone(milestoneIdOrName, options, command) {
     const rootOpts = getRootOpts(command);
@@ -102,11 +95,11 @@ async function handleUpdateMilestone(milestoneIdOrName, options, command) {
         updateVars.sortOrder = Number.parseFloat(options.sortOrder);
     }
     const result = await graphQLService.rawRequest(UPDATE_PROJECT_MILESTONE_MUTATION, updateVars);
-    const updateData = result.projectMilestoneUpdate;
-    if (!updateData?.success) {
+    if (!result.projectMilestoneUpdate.success ||
+        !result.projectMilestoneUpdate.projectMilestone) {
         throw new Error("Failed to update project milestone");
     }
-    outputSuccess(updateData.projectMilestone);
+    outputSuccess(result.projectMilestoneUpdate.projectMilestone);
 }
 export function setupProjectMilestonesCommands(program) {
     const projectMilestones = program

package/dist/commands/projects.d.ts

@@ -1,4 +1,6 @@
 import type { Command, OptionValues } from "commander";
+import type { LinearProject } from "../types/linear.js";
+export declare function sortActiveFirst(projects: LinearProject[]): LinearProject[];
 export declare function resolveProjectStateFilter(options: OptionValues): {
     states?: string[];
     excludeStates?: string[];

package/dist/commands/projects.js

@@ -1,15 +1,15 @@
 import { loadConfig } from "../config/config.js";
 import { resolveTeam } from "../config/resolver.js";
-import { CREATE_PROJECT_MUTATION, GET_PROJECT_QUERY, GET_PROJECT_TEAM_ISSUES_QUERY, PROJECT_BY_ID_QUERY, SEARCH_PROJECTS_BY_NAME_QUERY, UPDATE_PROJECT_MUTATION, } from "../queries/projects.js";
+import { ARCHIVE_PROJECT_MUTATION, CREATE_PROJECT_MUTATION, DELETE_PROJECT_MUTATION, GET_PROJECT_QUERY, GET_PROJECT_TEAM_ISSUES_QUERY, PROJECT_BY_ID_QUERY, SEARCH_PROJECTS_BY_NAME_QUERY, UPDATE_PROJECT_MUTATION, } from "../queries/projects.js";
 import { cached, resolveCacheTTL } from "../utils/disk-cache.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { createLinearService } from "../utils/linear-service.js";
 import { logger } from "../utils/logger.js";
-import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { renderCsv, renderFixedWidthTable, renderMarkdownTable, } from "../utils/table-formatter.js";
 import { isUuid } from "../utils/uuid.js";
-import { splitList } from "../utils/validators.js";
+import { parsePositiveInt, splitList } from "../utils/validators.js";
 const VALID_PROJECT_STATES = new Set([
     "backlog",
     "planned",
@@ -18,6 +18,58 @@ const VALID_PROJECT_STATES = new Set([
     "completed",
     "canceled",
 ]);
+/**
+ * Display ordering for `projects list`: active work first, terminal states
+ * last. Without this, the SDK's `updatedAt` order surfaces recently-touched
+ * completed/canceled projects ahead of in-progress ones — so an active project
+ * can fall past the `--limit` window and an agent concludes it does not exist
+ * (the DEV-4175 silent-truncation failure). Stable sort preserves `updatedAt`
+ * within each rank.
+ *
+ * `Linear` exposes additional internal states (e.g. archived) that we don't
+ * enumerate here; anything not in this table sorts to the end via
+ * `UNRANKED_STATE`.
+ */
+const PROJECT_STATE_RANK = {
+    started: 0,
+    planned: 1,
+    paused: 2,
+    backlog: 3,
+    completed: 4,
+    canceled: 5,
+};
+// Sentinel for any state Linear surfaces that isn't in the rank table above
+// (e.g. `archived`, future additions). Number.MAX_SAFE_INTEGER reads more
+// deliberately than a magic `9` and stays correct if PROJECT_STATE_RANK grows.
+const UNRANKED_STATE = Number.MAX_SAFE_INTEGER;
+export function sortActiveFirst(projects) {
+    return [...projects].sort((a, b) => (PROJECT_STATE_RANK[a.state ?? ""] ?? UNRANKED_STATE) -
+        (PROJECT_STATE_RANK[b.state ?? ""] ?? UNRANKED_STATE));
+}
+/**
+ * Emit a truncation warning when `projects list` returned exactly `--limit`
+ * rows (the same `count === limit` heuristic as `warnIfTruncated` in
+ * `output.ts`). JSON buffers it into `_warnings` so the payload stays a single
+ * parseable object; every human-facing format prints to stderr so it can't be
+ * silently scrolled past. DEV-4175.
+ *
+ * The exact total is deliberately omitted from the message. Returning it would
+ * require a second `client.projects({ first: 0 })` round-trip (the SDK has no
+ * `count`-only helper) or a full pagination walk — both negate the cheap-page
+ * default. `--all` in the hint gives the caller a deterministic way to learn
+ * the real total without us guessing, so the absence is a feature, not a gap.
+ */
+function warnProjectsTruncated(count, limit, format) {
+    const msg = `results_truncated: returned ${count} projects matching --limit ${limit}; ` +
+        "more may exist. Re-run with --all to fetch every project " +
+        `(or --limit ${limit * 2}, or narrow with --name / --state / --team).`;
+    if (format === "json") {
+        outputWarning(msg);
+    }
+    else {
+        logger.error(msg);
+    }
+}
 function parseStateList(value, flagName) {
     const states = splitList(value).map((s) => s.toLowerCase());
     for (const s of states) {
@@ -133,37 +185,29 @@ function formatProjectsOutput(projects, format, fieldNames) {
 }
 async function resolveProjectWithTeams(graphQLService, projectNameOrId) {
     if (isUuid(projectNameOrId)) {
-        const result = await graphQLService.rawRequest(PROJECT_BY_ID_QUERY, {
-            id: projectNameOrId,
-        });
-        const project = result.project;
-        if (!project) {
+        const result = await graphQLService.rawRequest(PROJECT_BY_ID_QUERY, { id: projectNameOrId });
+        if (!result.project) {
             throw new Error(`Project "${projectNameOrId}" not found`);
         }
-        const teams = project.teams;
         return {
-            projectId: project.id,
-            projectName: project.name,
-            currentTeams: (teams?.nodes || []).map((t) => ({
+            projectId: result.project.id,
+            projectName: result.project.name,
+            currentTeams: result.project.teams.nodes.map((t) => ({
                 id: t.id,
                 key: t.key,
                 name: t.name,
             })),
         };
     }
-    const result = await graphQLService.rawRequest(GET_PROJECT_QUERY, {
-        name: projectNameOrId,
-    });
-    const projectNodes = result.projects?.nodes;
-    if (!projectNodes?.length) {
+    const result = await graphQLService.rawRequest(GET_PROJECT_QUERY, { name: projectNameOrId });
+    const project = result.projects.nodes[0];
+    if (!project) {
         throw new Error(`Project "${projectNameOrId}" not found`);
     }
-    const project = projectNodes[0];
-    const teams = project.teams;
     return {
         projectId: project.id,
         projectName: project.name,
-        currentTeams: (teams?.nodes || []).map((t) => ({
+        currentTeams: project.teams.nodes.map((t) => ({
             id: t.id,
             key: t.key,
             name: t.name,
@@ -171,12 +215,14 @@ async function resolveProjectWithTeams(graphQLService, projectNameOrId) {
     };
 }
 function formatTeamsOutput(projectUpdate) {
+    if (!projectUpdate.project) {
+        throw new Error("Failed to update project");
+    }
     const updatedProject = projectUpdate.project;
-    const updatedTeams = updatedProject.teams;
     return {
         id: updatedProject.id,
         name: updatedProject.name,
-        teams: (updatedTeams.nodes || []).map((t) => ({
+        teams: updatedProject.teams.nodes.map((t) => ({
             id: t.id,
             key: t.key,
             name: t.name,
@@ -255,9 +301,7 @@ async function handleRemoveTeam(projectNameOrId, teamInput, options, command) {
             projectId,
             teamId: finalTeamId,
         });
-        const project = issueCheck.project;
-        const issues = project.issues;
-        const issueNodes = issues.nodes || [];
+        const issueNodes = issueCheck.project?.issues.nodes ?? [];
         if (issueNodes.length > 0) {
             const examples = issueNodes
                 .slice(0, 5)
@@ -285,14 +329,10 @@ async function handleCreateProject(name, options, command) {
     const graphQLService = await createGraphQLService(rootOpts);
     // Step 1: Check for duplicate projects (case-insensitive)
     const searchResult = await graphQLService.rawRequest(SEARCH_PROJECTS_BY_NAME_QUERY, { name });
-    const existing = (searchResult.projects
-        ?.nodes ?? []).filter((p) => p.name.toLowerCase() === name.toLowerCase());
+    const existing = searchResult.projects.nodes.filter((p) => p.name.toLowerCase() === name.toLowerCase());
     if (existing.length > 0 && !options.force) {
         const match = existing[0];
-        const teams = (match.teams?.nodes ??
-            [])
-            .map((t) => t.key)
-            .join(", ");
+        const teams = match.teams.nodes.map((t) => t.key).join(", ");
         throw new Error(`Project "${match.name}" already exists (state: ${match.state}, teams: ${teams}). ` +
             `Use --force to create anyway, or use the existing project.`);
     }
@@ -310,11 +350,11 @@ async function handleCreateProject(name, options, command) {
         ...(teamIds.length > 0 ? { teamIds } : {}),
     };
     const createResult = await graphQLService.rawRequest(CREATE_PROJECT_MUTATION, { input });
-    const created = createResult.projectCreate;
-    if (!created?.success) {
+    if (!createResult.projectCreate.success ||
+        !createResult.projectCreate.project) {
         throw new Error("Failed to create project");
     }
-    const project = created.project;
+    const project = createResult.projectCreate.project;
     // Step 4: Set content if provided (separate mutation — Linear API quirk)
     if (options.content) {
         await graphQLService.rawRequest(UPDATE_PROJECT_MUTATION, {
@@ -322,10 +362,7 @@ async function handleCreateProject(name, options, command) {
             input: { content: options.content },
         });
     }
-    const teamList = (project.teams?.nodes ??
-        [])
-        .map((t) => t.key)
-        .join(", ");
+    const teamList = project.teams.nodes.map((t) => t.key).join(", ");
     outputSuccess({
         id: project.id,
         name: project.name,
@@ -340,6 +377,42 @@ async function handleCreateProject(name, options, command) {
             : {}),
     });
 }
+async function handleArchiveProject(projectNameOrId, _options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
+    const projectId = await linearService.resolveProjectId(projectNameOrId);
+    const result = await graphQLService.rawRequest(ARCHIVE_PROJECT_MUTATION, { id: projectId });
+    const payload = result.projectArchive;
+    if (!payload.success) {
+        throw new Error(`Failed to archive project "${projectNameOrId}"`);
+    }
+    outputSuccess({
+        success: true,
+        archived: true,
+        id: projectId,
+        entity: payload.entity ?? undefined,
+        lastSyncId: payload.lastSyncId,
+    });
+}
+async function handleDeleteProject(projectNameOrId, _options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
+    const projectId = await linearService.resolveProjectId(projectNameOrId);
+    const result = await graphQLService.rawRequest(DELETE_PROJECT_MUTATION, { id: projectId });
+    const payload = result.projectDelete;
+    if (!payload.success) {
+        throw new Error(`Failed to delete project "${projectNameOrId}"`);
+    }
+    outputSuccess({
+        success: true,
+        deleted: true,
+        id: projectId,
+        entity: payload.entity ?? undefined,
+        lastSyncId: payload.lastSyncId,
+    });
+}
 export function setupProjectsCommands(program) {
     const projects = program
         .command("projects")
@@ -354,6 +427,14 @@ export function setupProjectsCommands(program) {
         .option("--content <markdown>", "full markdown body (shown in project panel)")
         .option("--force", "create even if a project with the same name exists")
         .action(handleAsyncCommand(handleCreateProject));
+    projects
+        .command("archive <project>")
+        .description("Archive a project (resolves names)")
+        .action(handleAsyncCommand(handleArchiveProject));
+    projects
+        .command("delete <project>")
+        .description("Delete (trash) a project (resolves names)")
+        .action(handleAsyncCommand(handleDeleteProject));
     projects
         .command("list")
         .description("List projects")
@@ -361,13 +442,22 @@ export function setupProjectsCommands(program) {
         .option("--format <format>", "output format (json, summary, table, md, csv)", "json")
         .option("--fields <fields>", "columns for table/csv (comma-separated: name,state,progress,teams,lead,targetDate)")
         .option("--name <substring>", "filter by case-insensitive substring on project name")
+        .option("--team <key|name>", "filter to projects belonging to a specific team (e.g. DEV, FE)")
         .option("--state <names>", "include only projects in these states (comma-separated: backlog, planned, started, paused, completed, canceled)")
         .option("--exclude-state <names>", "exclude projects in these states (comma-separated). Mutually exclusive with --state.")
         .option("--active", "shorthand for --exclude-state completed,canceled (mutually exclusive with --state / --exclude-state)")
+        .option("--all", "fetch every project (paginates fully). Equivalent to --limit 0; overrides --limit when both are given.")
         .action(handleAsyncCommand(async (options, command) => {
         const rootOpts = getRootOpts(command);
-        const limit = Number.parseInt(options.limit, 10);
+        // `--all` / `--limit 0` mean unlimited. Stored as `limit = 0`,
+        // which `LinearService.getProjects` interprets as "paginate
+        // fully". DEV-4175.
+        const unlimited = options.all === true || options.limit === "0";
+        const limit = unlimited
+            ? 0
+            : parsePositiveInt(options.limit, "--limit");
         const nameFilter = options.name;
+        const teamFilter = options.team;
         const stateFilter = resolveProjectStateFilter(options);
         const ttl = resolveCacheTTL({
             configTTL: loadConfig().cacheTTLSeconds,
@@ -377,31 +467,54 @@ export function setupProjectsCommands(program) {
         // don't collide.
         const cacheKey = `projects-list-limit:${limit}` +
             `-name:${nameFilter ?? "_all"}` +
+            `-team:${teamFilter ?? "_all"}` +
             `-states:${stateFilter.states?.join(",") ?? "_any"}` +
             `-excl:${stateFilter.excludeStates?.join(",") ?? "_none"}`;
         const result = await cached(cacheKey, ttl, async () => {
             const service = await createLinearService(rootOpts);
+            let teamId;
+            if (teamFilter) {
+                const resolved = resolveTeam(teamFilter);
+                teamId = await service.resolveTeamId(resolved);
+            }
             return service.getProjects(limit, {
                 nameFilter,
+                teamId,
                 states: stateFilter.states,
                 excludeStates: stateFilter.excludeStates,
             });
         });
+        // Active-first sort: keeps started/planned/paused/backlog
+        // ahead of completed/canceled in every format, so the active
+        // set always fits within `--limit`. DEV-4175.
+        const sorted = sortActiveFirst(result);
         const format = options.format;
-        if (format === "table" ||
+        const isTabular = format === "table" ||
             format === "md" ||
             format === "markdown" ||
-            format === "csv") {
+            format === "csv";
+        // Emit the truncation warning BEFORE outputting: the JSON
+        // branch buffers into `_warnings`, which the next
+        // `outputSuccess()` call drains. All other formats route to
+        // stderr via `logger.error` so the visible payload (table,
+        // markdown, summary) stays clean.
+        if (!unlimited && sorted.length === limit) {
+            warnProjectsTruncated(sorted.length, limit, format);
+        }
+        if (isTabular) {
             const fieldList = options.fields
                 ? splitList(options.fields)
                 : undefined;
-            formatProjectsOutput(result, format, fieldList);
+            formatProjectsOutput(sorted, format, fieldList);
             if (format === "table") {
-                logger.info(`\n${result.length} projects`);
+                logger.info(`\n${sorted.length} projects`);
             }
         }
         else {
-            outputSuccess({ data: result, meta: { count: result.length } });
+            outputSuccess({
+                data: sorted,
+                meta: { count: sorted.length },
+            });
         }
     }));
     projects

package/dist/commands/read-shortcut.d.ts

@@ -9,4 +9,4 @@ export declare function setupReadShortcut(program: Command): void;
  * `issues read` (in `commands/issues.ts`) both call one implementation
  * instead of carrying byte-equivalent duplicates. ALL-938 cleanup.
  */
-export declare function readIssues(issueIds: string[], _options: Record<string, unknown>, command: Command): Promise<void>;
+export declare function readIssues(issueIds: string[], options: Record<string, unknown>, command: Command): Promise<void>;

package/dist/commands/read-shortcut.js

@@ -1,8 +1,7 @@
 import { downloadLinearUploads } from "../utils/download-uploads.js";
+import { extractField } from "../utils/extract-field.js";
 import { createFileService } from "../utils/file-service.js";
-import { GraphQLIssuesService } from "../utils/graphql-issues-service.js";
-import { createGraphQLService } from "../utils/graphql-service.js";
-import { createLinearService } from "../utils/linear-service.js";
+import { createIssuesService } from "../utils/issues-service-bootstrap.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 /**
@@ -21,7 +20,10 @@ export function setupReadShortcut(program) {
         .alias("view")
         .alias("show")
         .description("Shortcut for `issues read`. Get issue details by identifier.")
-        .addHelpText("after", "\nExamples:\n  el-linear read ADM-652\n  el-linear get DEV-123 DEV-456\n  el-linear ADM-652          (auto-detected)")
+        .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)')
         .action(handleAsyncCommand(readIssues));
     // Catch-all: if argv looks like `el-linear ADM-652 [DEV-123 ...]`, run read
     const originalParse = program.parse.bind(program);
@@ -54,15 +56,33 @@ export function setupReadShortcut(program) {
  * `issues read` (in `commands/issues.ts`) both call one implementation
  * instead of carrying byte-equivalent duplicates. ALL-938 cleanup.
  */
-export async function readIssues(issueIds, _options, command) {
+export async function readIssues(issueIds, options, command) {
     const rootOpts = getRootOpts(command);
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    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.");
+    }
     if (issueIds.length === 1) {
         const issue = await issuesService.getIssueById(issueIds[0]);
         const resolved = await downloadLinearUploads(issue, fileService);
+        if (fieldName) {
+            const section = extractField(resolved.description ?? "", fieldName);
+            if (section === null) {
+                // Print nothing to stdout, exit non-zero with a stderr hint.
+                // Mirrors `grep` semantics for "not found" — scripts can
+                // branch on the exit code.
+                process.stderr.write(`el-linear: section "${fieldName}" not found in ${resolved.identifier}'s description\n`);
+                process.exit(1);
+            }
+            process.stdout.write(`${section}\n`);
+            return;
+        }
         outputSuccess(resolved);
     }
     else {