@enrichlayer/el-linear 1.34.0 → 1.35.0

package/README.md

@@ -445,6 +445,7 @@ el-linear <command> --help       # detailed help for one command
 | Comments | `comments {list, read, create, update, delete}` |
 | Labels | `labels {list, create, retire, restore}` |
 | Projects | `projects {list, add-team, remove-team}` |
+| Project updates | `project-updates {create, list, read}` (post a status update to a project's Updates feed) |
 | Cycles | `cycles {list, read}` |
 | Documents | `documents {list, read, create, update, delete}` |
 | Releases | `releases {list, read, create, pipelines}` |
@@ -578,7 +579,7 @@ el-linear projects list --format summary --fields name,state,progress,lead,teams
 # ...
 ```
 
-Unrecognized field names are reported as a `_warnings:` line appended after the summary block (`fields_unprojectable: --format summary on issues list does not project foo, bar; ...`) — same signal scripts get on the JSON path. Resources whose summary formatter doesn't yet wire `--fields` (cycles, milestones, comments, teams, labels, users, documents, templates, attachments, releases, search results) emit the same warning and render their default summary.
+Unrecognized field names are reported as a `_warnings:` line appended after the summary block (`fields_unprojectable: --format summary on issues list does not project foo, bar; ...`) — same signal scripts get on the JSON path. Resources whose summary formatter doesn't yet wire `--fields` (cycles, milestones, project updates, comments, teams, labels, users, documents, templates, attachments, releases, search results) emit the same warning and render their default summary.
 
 ### Windowed metadata (`WindowedMeta`)
 

package/dist/commands/issue-id.js

@@ -22,11 +22,12 @@ import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 // elsewhere in the workspace. Any addition here is the single point of
 // truth that all skills rely on.
 //
-// Accepted prefixes (DEV-4777 adds bug/spike; DEV-4660 added codex; both
-// mirror tools-repo DEV-4417):
-//   feature | fix | chore | refactor | dev   — SOP-canonical + Linear-CLI direct
+// Accepted prefixes (DEV-4777 adds bug/spike; DEV-4660 added codex; DEV-5342
+// adds the feat short-form alias; all mirror tools-repo DEV-4417/DEV-5334):
+//   feature | feat | fix | chore | refactor | dev — SOP-canonical + Linear-CLI direct
 //   bug | spike                              — sanctioned Linear type labels
 //   codex                                    — Codex-authored branches (codex/<TEAM>-<N>-slug)
+//   feat                                     — short-form alias for feature (DEV-5342)
 // New authoring surfaces (Codex, future agent prefixes) and sanctioned Linear
 // type labels (bug, spike) get first-class issue detection so commit guards,
 // MR descriptions, and session handoff don't go dark on a branch a human
@@ -34,7 +35,7 @@ import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 //
 // Mirror of cli/el-git/src/commands/context.ts:BRANCH_RE in the
 // vertical-int/tools repo. If you change one, change the other.
-const BRANCH_RE = /^(?:feature|fix|chore|refactor|bug|spike|dev|codex)[-/]([A-Z]{2,4})-(\d+)(?:[-/](.*))?$/i;
+const BRANCH_RE = /^(?:feature|feat|fix|chore|refactor|bug|spike|dev|codex)[-/]([A-Z]{2,4})-(\d+)(?:[-/](.*))?$/i;
 export function parseBranchName(branch) {
     const m = branch.match(BRANCH_RE);
     if (!m) {

package/dist/commands/project-updates.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function setupProjectUpdatesCommands(program: Command): void;

package/dist/commands/project-updates.js

@@ -0,0 +1,116 @@
+import { readFileSync } from "node:fs";
+import { CREATE_PROJECT_UPDATE_MUTATION, GET_PROJECT_UPDATE_BY_ID_QUERY, LIST_PROJECT_UPDATES_QUERY, } from "../queries/project-updates.js";
+import { notFoundError } from "../utils/error-messages.js";
+import { createGraphQLService } from "../utils/graphql-service.js";
+import { createLinearService } from "../utils/linear-service.js";
+import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
+import { parsePositiveInt } from "../utils/validators.js";
+const VALID_HEALTH = [
+    "onTrack",
+    "atRisk",
+    "offTrack",
+];
+/**
+ * Resolve the update body from `--body` / `--body-file` (mutually exclusive,
+ * exactly one required) — mirrors the comments-command contract so file-sourced
+ * bodies sidestep shell-quoting traps for markdown/tables/backticks.
+ */
+function resolveBody(options) {
+    if (options.body && options.bodyFile) {
+        throw new Error("--body and --body-file are mutually exclusive — pass one or the other");
+    }
+    if (options.bodyFile) {
+        return readFileSync(options.bodyFile, "utf-8");
+    }
+    if (options.body) {
+        return options.body;
+    }
+    throw new Error("Either --body or --body-file is required");
+}
+/**
+ * Validate an optional `--health` value against Linear's
+ * `ProjectUpdateHealthType` enum. Returns undefined when the flag is omitted
+ * (Linear then defaults the health), throws on an unknown value.
+ */
+function resolveHealth(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!VALID_HEALTH.includes(value)) {
+        throw new Error(`Invalid --health "${value}" — expected one of: ${VALID_HEALTH.join(", ")}`);
+    }
+    return value;
+}
+async function handleCreateProjectUpdate(options, command) {
+    // Validate local input first so bad --body/--health fails with zero network.
+    const body = resolveBody(options);
+    const health = resolveHealth(options.health);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
+    const projectId = await linearService.resolveProjectId(options.project);
+    const input = { projectId, body };
+    if (health !== undefined) {
+        input.health = health;
+    }
+    if (options.diffHidden) {
+        input.isDiffHidden = true;
+    }
+    const result = await graphQLService.rawRequest(CREATE_PROJECT_UPDATE_MUTATION, { input });
+    if (!result.projectUpdateCreate.success ||
+        !result.projectUpdateCreate.projectUpdate) {
+        throw new Error(`Failed to create project update on project "${options.project}"`);
+    }
+    outputSuccess(result.projectUpdateCreate.projectUpdate);
+}
+async function handleListProjectUpdates(options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
+    const projectId = await linearService.resolveProjectId(options.project);
+    const result = await graphQLService.rawRequest(LIST_PROJECT_UPDATES_QUERY, {
+        projectId,
+        first: parsePositiveInt(options.limit, "--limit"),
+    });
+    if (!result.project) {
+        throw notFoundError("Project", options.project);
+    }
+    const nodes = result.project.projectUpdates.nodes;
+    outputSuccess({ data: nodes, meta: { count: nodes.length } });
+}
+async function handleReadProjectUpdate(updateId, _options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const result = await graphQLService.rawRequest(GET_PROJECT_UPDATE_BY_ID_QUERY, { id: updateId });
+    if (!result.projectUpdate) {
+        throw notFoundError("Project update", updateId);
+    }
+    outputSuccess(result.projectUpdate);
+}
+export function setupProjectUpdatesCommands(program) {
+    const projectUpdates = program
+        .command("project-updates")
+        .description("Project update (status post) operations");
+    projectUpdates.action(() => projectUpdates.help());
+    projectUpdates
+        .command("create")
+        .description("Post a status update to a project (appears in the project's Updates feed).")
+        .requiredOption("--project <project>", "project name or ID")
+        .option("--body <body>", "update body markdown (inline)")
+        .option("--body-file <path>", "read update body from file")
+        .option("--health <health>", "project health: onTrack | atRisk | offTrack (omit to leave unset)")
+        .option("--diff-hidden", "hide the progress diff on the update")
+        .option("-q, --quiet", "print one confirmation line (health url) instead of the full JSON")
+        .action(handleAsyncCommand(handleCreateProjectUpdate));
+    projectUpdates
+        .command("list")
+        .description("List status updates posted to a project (newest first).")
+        .requiredOption("--project <project>", "project name or ID")
+        .option("-l, --limit <number>", "limit results", "50")
+        .action(handleAsyncCommand(handleListProjectUpdates));
+    projectUpdates
+        .command("read <updateId>")
+        .description("Get a single project update by its ID.")
+        .action(handleAsyncCommand(handleReadProjectUpdate));
+}

package/dist/main.js

@@ -20,6 +20,7 @@ import { setupIssuesCommands } from "./commands/issues.js";
 import { setupLabelsCommands } from "./commands/labels.js";
 import { setupProfileCommands } from "./commands/profile.js";
 import { setupProjectMilestonesCommands } from "./commands/project-milestones.js";
+import { setupProjectUpdatesCommands } from "./commands/project-updates.js";
 import { setupProjectsCommands } from "./commands/projects.js";
 import { setupReadShortcut } from "./commands/read-shortcut.js";
 import { setupRefsCommands } from "./commands/refs.js";
@@ -65,9 +66,13 @@ program
     .option("--profile <name>", "named profile (under ~/.config/el-linear/profiles/<name>/) for this invocation. Overrides EL_LINEAR_PROFILE env + the on-disk active-profile marker.")
     .option("--json", "output as JSON (default, accepted for compatibility)")
     .option("--format <kind>", "output format: json (default, structured envelope) or summary (human-readable)", "json")
-    .option("--raw", "strip { data, meta } wrapper from list output — emit the array directly")
+    .option("--raw", "strip { data, meta } wrapper from list output — emit the array directly. " +
+    "Warnings (e.g. --fields fields_unresolved) can't ride on a bare array, so " +
+    "they are written to stderr prefixed `_warnings: `, keeping stdout a pure JSON array")
     .option("--jq <filter>", "apply a jq filter to the JSON output")
-    .option("--fields <fields>", "filter output to specific fields (comma-separated)")
+    .option("--fields <fields>", "filter output to specific fields (comma-separated). Unresolved fields are " +
+    "emitted as null plus a `fields_unresolved:` warning — in the JSON " +
+    "envelope's `_warnings`, or on stderr when output is a bare array (with --raw)")
     .option("--no-cache", "bypass the on-disk cache for `teams list` / `labels list` / `projects list`");
 program.hook("preAction", (_thisCommand, actionCommand) => {
     const rootOpts = actionCommand.optsWithGlobals();
@@ -143,6 +148,7 @@ setupReleasesCommands(program);
 setupProjectsCommands(program);
 setupCyclesCommands(program);
 setupProjectMilestonesCommands(program);
+setupProjectUpdatesCommands(program);
 setupEmbedsCommands(program);
 setupTeamsCommands(program);
 setupTemplatesCommands(program);

package/dist/queries/project-updates-types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Typed response shapes for the queries in `./project-updates.ts`.
+ * See `./issues-types.ts` for the rationale (ALL-937).
+ *
+ * All three queries (create / list / read) select the same
+ * `PROJECT_UPDATE_FRAGMENT`, so one node shape covers every consumer.
+ */
+export type ProjectUpdateHealth = "onTrack" | "atRisk" | "offTrack";
+interface ProjectUpdateProjectRef {
+    id: string;
+    name: string;
+}
+interface ProjectUpdateUserRef {
+    id: string;
+    name: string;
+    displayName: string | null;
+}
+/**
+ * Mirrors `PROJECT_UPDATE_FRAGMENT` — the full selection set shared by the
+ * create mutation, the project-scoped list, and the by-id read.
+ */
+export interface ProjectUpdateNode {
+    id: string;
+    body: string | null;
+    health: ProjectUpdateHealth | null;
+    url: string | null;
+    slugId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    editedAt: string | null;
+    user: ProjectUpdateUserRef | null;
+    project: ProjectUpdateProjectRef | null;
+}
+export interface CreateProjectUpdateResponse {
+    projectUpdateCreate: {
+        success: boolean;
+        projectUpdate: ProjectUpdateNode | null;
+    };
+}
+export interface ListProjectUpdatesResponse {
+    project: {
+        id: string;
+        name: string;
+        projectUpdates: {
+            nodes: ProjectUpdateNode[];
+        };
+    } | null;
+}
+export interface GetProjectUpdateByIdResponse {
+    projectUpdate: ProjectUpdateNode | null;
+}
+export {};

package/dist/queries/project-updates-types.js

@@ -0,0 +1,8 @@
+/**
+ * Typed response shapes for the queries in `./project-updates.ts`.
+ * See `./issues-types.ts` for the rationale (ALL-937).
+ *
+ * All three queries (create / list / read) select the same
+ * `PROJECT_UPDATE_FRAGMENT`, so one node shape covers every consumer.
+ */
+export {};

package/dist/queries/project-updates.d.ts

@@ -0,0 +1,3 @@
+export declare const CREATE_PROJECT_UPDATE_MUTATION = "\n  mutation ProjectUpdateCreate($input: ProjectUpdateCreateInput!) {\n    projectUpdateCreate(input: $input) {\n      success\n      projectUpdate {\n        \n  id\n  body\n  health\n  url\n  slugId\n  createdAt\n  updatedAt\n  editedAt\n  user {\n    id\n    name\n    displayName\n  }\n  project {\n    id\n    name\n  }\n\n      }\n    }\n  }\n";
+export declare const LIST_PROJECT_UPDATES_QUERY = "\n  query ListProjectUpdates($projectId: String!, $first: Int!) {\n    project(id: $projectId) {\n      id\n      name\n      projectUpdates(first: $first, orderBy: createdAt) {\n        nodes {\n          \n  id\n  body\n  health\n  url\n  slugId\n  createdAt\n  updatedAt\n  editedAt\n  user {\n    id\n    name\n    displayName\n  }\n  project {\n    id\n    name\n  }\n\n        }\n      }\n    }\n  }\n";
+export declare const GET_PROJECT_UPDATE_BY_ID_QUERY = "\n  query GetProjectUpdate($id: String!) {\n    projectUpdate(id: $id) {\n      \n  id\n  body\n  health\n  url\n  slugId\n  createdAt\n  updatedAt\n  editedAt\n  user {\n    id\n    name\n    displayName\n  }\n  project {\n    id\n    name\n  }\n\n    }\n  }\n";

package/dist/queries/project-updates.js

@@ -0,0 +1,49 @@
+const PROJECT_UPDATE_FRAGMENT = `
+  id
+  body
+  health
+  url
+  slugId
+  createdAt
+  updatedAt
+  editedAt
+  user {
+    id
+    name
+    displayName
+  }
+  project {
+    id
+    name
+  }
+`;
+export const CREATE_PROJECT_UPDATE_MUTATION = `
+  mutation ProjectUpdateCreate($input: ProjectUpdateCreateInput!) {
+    projectUpdateCreate(input: $input) {
+      success
+      projectUpdate {
+        ${PROJECT_UPDATE_FRAGMENT}
+      }
+    }
+  }
+`;
+export const LIST_PROJECT_UPDATES_QUERY = `
+  query ListProjectUpdates($projectId: String!, $first: Int!) {
+    project(id: $projectId) {
+      id
+      name
+      projectUpdates(first: $first, orderBy: createdAt) {
+        nodes {
+          ${PROJECT_UPDATE_FRAGMENT}
+        }
+      }
+    }
+  }
+`;
+export const GET_PROJECT_UPDATE_BY_ID_QUERY = `
+  query GetProjectUpdate($id: String!) {
+    projectUpdate(id: $id) {
+      ${PROJECT_UPDATE_FRAGMENT}
+    }
+  }
+`;

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

@@ -30,6 +30,8 @@ export declare function formatCycleSummary(cycle: Record<string, unknown>): stri
 export declare function formatCycleList(cycles: unknown[]): string;
 export declare function formatMilestoneSummary(milestone: Record<string, unknown>): string;
 export declare function formatMilestoneList(milestones: unknown[]): string;
+export declare function formatProjectUpdateSummary(update: Record<string, unknown>): string;
+export declare function formatProjectUpdateList(updates: unknown[]): string;
 export declare function formatTeamList(teams: unknown[]): string;
 export declare function formatLabelList(labels: unknown[]): string;
 /**
@@ -68,7 +70,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" | "issue-relation-list" | "empty-list" | "generic";
+export type ResourceKind = "issue" | "issue-list" | "project" | "project-list" | "comment" | "comment-list" | "cycle" | "cycle-list" | "milestone" | "milestone-list" | "project-update" | "project-update-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

@@ -655,6 +655,35 @@ export function formatMilestoneList(milestones) {
         { header: "PROJECT", minWidth: 7, extract: (m) => getName(m.project) },
     ], { emptyText: "(no milestones)", itemNoun: "milestone" });
 }
+// ── project updates ────────────────────────────────────────────
+export function formatProjectUpdateSummary(update) {
+    const headerLine = `project-update ${s(update.id)}`;
+    const fields = [
+        { label: "Health", value: s(update.health) },
+        { label: "Project", value: getName(update.project) },
+        { label: "Author", value: getName(update.user) },
+        { label: "Created", value: s(update.createdAt) },
+        { label: "URL", value: s(update.url) },
+    ];
+    const header = renderHeader(fields);
+    const body = clipDescription(update.body);
+    const parts = [headerLine, header];
+    if (body)
+        parts.push("", body);
+    return parts.filter((p) => p !== "").join("\n");
+}
+export function formatProjectUpdateList(updates) {
+    return renderTable(updates.map((raw) => asObj(raw) ?? {}), [
+        { header: "HEALTH", minWidth: 6, extract: (u) => s(u.health) },
+        { header: "AUTHOR", minWidth: 6, extract: (u) => getName(u.user) },
+        {
+            header: "CREATED",
+            minWidth: 7,
+            extract: (u) => s(u.createdAt).slice(0, 10),
+        },
+        { header: "URL", minWidth: 3, maxWidth: 60, extract: (u) => s(u.url) },
+    ], { emptyText: "(no project updates)", itemNoun: "project update" });
+}
 // ── teams ──────────────────────────────────────────────────────
 export function formatTeamList(teams) {
     return renderTable(teams.map((raw) => asObj(raw) ?? {}), [
@@ -1036,6 +1065,10 @@ export function inferKindFromPayload(value) {
         "progress" in obj &&
         ("state" in obj || "lead" in obj || "teams" in obj))
         return "project";
+    // Project updates carry body + createdAt + user like comments; `health` is
+    // the distinguishing field, so this must precede the comment check.
+    if ("body" in obj && "health" in obj)
+        return "project-update";
     if ("body" in obj && "createdAt" in obj && "user" in obj)
         return "comment";
     if (("number" in obj || "isActive" in obj) &&
@@ -1079,6 +1112,10 @@ function inferListKind(items) {
         }
         return "issue-list";
     }
+    // Project-update rows carry body + createdAt like comments; `health` is the
+    // distinguishing field, so this must precede the comment-list check.
+    if ("body" in sample && "health" in sample)
+        return "project-update-list";
     if ("body" in sample && "createdAt" in sample)
         return "comment-list";
     if ("progress" in sample && "name" in sample) {
@@ -1168,6 +1205,10 @@ export function dispatch(kind, payload, fields) {
             return formatMilestoneSummary((obj ?? {}));
         case "milestone-list":
             return formatMilestoneList(list ?? []);
+        case "project-update":
+            return formatProjectUpdateSummary((obj ?? {}));
+        case "project-update-list":
+            return formatProjectUpdateList(list ?? []);
         case "team-list":
             return formatTeamList(list ?? []);
         case "label-list":
@@ -1230,6 +1271,11 @@ export function formatLine(payload) {
     if (kind === "comment" && obj) {
         return `comment ${s(obj.id)}`;
     }
+    if (kind === "project-update" && obj) {
+        // create doesn't carry an identifier/title — health + url are the
+        // stable handles a caller needs (matches the summary header style).
+        return `${s(obj.health)}  ${s(obj.url)}`;
+    }
     if (kind === "relation-list") {
         return formatRelationLine(payload);
     }

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,64 @@ 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) {
+                // A primitive item short-circuits: filterFields returns it
+                // unchanged and records NOTHING in perItem, so every field counts
+                // as resolved here — a mixed array holding one primitive suppresses
+                // the unresolved warning for all fields. Acceptable: a primitive
+                // item can't meaningfully be projected, and heterogeneous lists
+                // legitimately have per-item gaps.
+                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 +105,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 +208,40 @@ 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) };
+            if (obj.data !== null &&
+                obj.data !== undefined &&
+                typeof obj.data === "object") {
+                // Envelope with a `data` payload — project inside `data`,
+                // whether it's an array (list envelope) or an object (e.g.
+                // el-git context). Arrays ARE objects, so this single
+                // `typeof === "object"` check subsumes the former separate
+                // `Array.isArray(obj.data)` arm (DEV-5339 collapsed the two
+                // byte-identical branches); `filterFields` dispatches on
+                // array-vs-object internally. Paths are relative to `data` for
+                // every envelope shape. Before DEV-5323 the object case fell
+                // through to root filtering, so `--fields branch,issueId` on an
+                // envelope returned `{}`.
+                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
@@ -179,11 +266,31 @@ export function outputSuccess(data) {
     // fields_unprojectable surfaced from a prior dispatch) and embed
     // them as `_warnings` on the envelope.
     const warnings = [...drainWarnings(), ...drainSummaryFieldWarnings()];
-    if (warnings.length > 0 &&
-        output !== null &&
-        typeof output === "object" &&
-        !Array.isArray(output)) {
-        output = { ...output, _warnings: warnings };
+    if (warnings.length > 0) {
+        if (output !== null &&
+            typeof output === "object" &&
+            !Array.isArray(output)) {
+            output = { ...output, _warnings: warnings };
+        }
+        else {
+            // Bare-array (or primitive / null) output has no envelope object to
+            // carry `_warnings`. This is the DEV-5339 fix: previously the buffer
+            // was drained above but only re-embedded for object output, so a
+            // warning was silently dropped on a top-level array payload AND on
+            // `--raw` (which unwraps { data: [...] } to a bare array *before*
+            // this point) — losing exactly the DEV-5323 `fields_unresolved:`
+            // fail-visible signal on the `--raw` form our own CLAUDE.md
+            // recommends to agents. Route each warning to STDERR prefixed
+            // `_warnings: ` so the signal always reaches the consumer while
+            // stdout stays a pure JSON array (safe to pipe to `jq`). Mirrors the
+            // summary path's `_warnings:` line convention — that path uses
+            // logger.info because its stdout is already human text; here stdout
+            // must remain machine-parseable JSON, so we use logger.error
+            // (stderr).
+            for (const w of warnings) {
+                logger.error(`_warnings: ${w}`);
+            }
+        }
     }
     if (jqFilter) {
         const json = JSON.stringify(output);

package/package.json

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