@enrichlayer/el-linear 1.22.0 → 1.24.0

package/README.md

@@ -533,6 +533,50 @@ global `summary` value works on every read/list command.
 `--raw` together with `--format summary` to render a list envelope as a
 bare item-list rather than an envelope.
 
+### Windowed metadata (`WindowedMeta`)
+
+When a command returns less than its complete result set — because it
+windowed by time, paginated, filtered, or hit a `--limit` — it should make
+that visible in the envelope's `meta` rather than leaving the consumer to
+guess. The shared output package (`@enrichlayer/el-linear/output`) exports a
+canonical `WindowedMeta` type for exactly these fields, so every CLI built on
+it uses one set of names instead of ad-hoc `_window` / `_total` / `truncated`
+keys:
+
+| Field            | Populate when…                                                        |
+| ---------------- | --------------------------------------------------------------------- |
+| `_window`        | a time/scope window was applied — `"30d"`, `"since 2026-06-01"`.      |
+| `_limit_applied` | a cap is in effect — the caller's value, or the default when omitted. |
+| `_query`         | a search / filter expression produced `data`.                         |
+| `_total`         | the total matching rows *before* windowing / limiting / filtering.    |
+| `_fetched`       | rows in *this* response (equals `meta.count` for list envelopes).     |
+| `truncated`      | `_fetched` hit `_limit_applied` and more rows exist beyond this page. |
+| `availability`   | `{status: "complete" \| "partial" \| "degraded", detail?}` — emit `degraded` when a sub-source failed, never an empty result that reads as "no hits". |
+
+All fields are optional; a command populates only the ones that apply. The
+`meta` object still admits CLI-specific counters (`_total_hits`,
+`_source_users_total`, …) alongside these, but prefer the generic field where
+one fits so cross-CLI tooling and skills can read a single shape. Skill output
+templates that show counts MUST consume `_total` / `truncated` from `meta`
+rather than counting returned rows.
+
+This convention comes from the output-transparency audit's **"Standard
+Convention"** section (`docs/output-transparency-audit-report.md` in the
+`vertical-int/tools` repo, DEV-3810); `WindowedMeta` is the shared type that
+audit recommends promoting into the envelope (DEV-4668).
+
+```ts
+import type { WindowedMeta } from "@enrichlayer/el-linear/output";
+
+// A list command echoing what it windowed and whether it clipped:
+outputList(rows, {
+  _window: "30d",
+  _limit_applied: 100,
+  _total: 247,
+  truncated: rows.length === 100,
+} satisfies WindowedMeta);
+```
+
 ### Extract a single description section: `--field`
 
 `issues read --field <name>` extracts one named section from an issue's

package/dist/commands/projects.js

@@ -1,6 +1,6 @@
 import { loadConfig } from "../config/config.js";
 import { resolveTeam } from "../config/resolver.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 { ARCHIVE_PROJECT_MUTATION, CREATE_PROJECT_MUTATION, DELETE_PROJECT_MUTATION, GET_PROJECT_QUERY, GET_PROJECT_TEAM_ISSUES_QUERY, PROJECT_BY_ID_QUERY, PROJECT_READ_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";
@@ -413,6 +413,30 @@ async function handleDeleteProject(projectNameOrId, _options, command) {
         lastSyncId: payload.lastSyncId,
     });
 }
+/**
+ * Read a single project (DEV-4610). Resolves the identifier through the same
+ * `resolveProjectId` path the `--project` flags use (UUID / slug / URL / name),
+ * fetches the full project, and emits it. `teams.nodes` is flattened to a plain
+ * array so the `--format summary` project renderer (and the JSON shape) match
+ * `projects list` — the formatter expects a flat team list, not a `{ nodes }`
+ * connection. Replaces the raw-`graphql` workaround for grabbing a project's
+ * url / content / lead.
+ */
+async function handleReadProject(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(PROJECT_READ_QUERY, { id: projectId });
+    if (!result.project) {
+        throw new Error(`Project "${projectNameOrId}" not found`);
+    }
+    const { teams, ...rest } = result.project;
+    outputSuccess({
+        ...rest,
+        teams: teams.nodes.map((t) => ({ id: t.id, key: t.key, name: t.name })),
+    });
+}
 export function setupProjectsCommands(program) {
     const projects = program
         .command("projects")
@@ -435,6 +459,10 @@ export function setupProjectsCommands(program) {
         .command("delete <project>")
         .description("Delete (trash) a project (resolves names)")
         .action(handleAsyncCommand(handleDeleteProject));
+    projects
+        .command("read <project>")
+        .description("Read one project's full details (resolves name/slug/URL/ID). `--format summary` shows state, lead, teams, target, progress, url; JSON includes description/content.")
+        .action(handleAsyncCommand(handleReadProject));
     projects
         .command("list")
         .description("List projects")

package/dist/output.d.ts

@@ -79,4 +79,4 @@
  *   redactor of its own; coupling token redaction to the output layer
  *   would make this API surface stickier than it needs to be.
  */
-export { type CliListEnvelope, getOutputFormat, handleAsyncCommand, type ListExtraMeta, type ListMeta, outputList, outputSingle, outputSuccess, outputWarning, resetWarnings, setFieldsFilter, setJqFilter, setOutputFormat, setRawMode, warnIfTruncated, } from "./utils/output.js";
+export { type CliListEnvelope, getOutputFormat, handleAsyncCommand, type ListExtraMeta, type ListMeta, outputList, outputSingle, outputSuccess, outputWarning, resetWarnings, setFieldsFilter, setJqFilter, setOutputFormat, setRawMode, type WindowedMeta, warnIfTruncated, } from "./utils/output.js";

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

@@ -34,6 +34,24 @@ interface ProjectWithIssuesNode extends ProjectBaseNode {
 export interface ProjectByIdResponse {
     project: ProjectBaseNode | null;
 }
+/** Full project read (`PROJECT_READ_QUERY`) — base fields + summary/JSON fields. */
+interface ProjectReadNode extends ProjectBaseNode {
+    state: string;
+    progress: number;
+    url: string;
+    startDate: string | null;
+    targetDate: string | null;
+    description: string | null;
+    content: string | null;
+    lead: {
+        id: string;
+        name: string;
+        displayName: string;
+    } | null;
+}
+export interface ProjectReadResponse {
+    project: ProjectReadNode | null;
+}
 export interface GetProjectResponse {
     projects: {
         nodes: ProjectBaseNode[];

package/dist/queries/projects.d.ts

@@ -1,5 +1,14 @@
 export declare const TEAM_LOOKUP_QUERY = "\n  query TeamLookup($key: String) {\n    teams(filter: { or: [{ key: { eq: $key } }, { name: { eq: $key } }] }, first: 1) {\n      nodes { id key name }\n    }\n  }\n";
 export declare const PROJECT_BY_ID_QUERY = "\n  query ProjectById($id: String!) {\n    project(id: $id) {\n      id\n      name\n      teams {\n        nodes { id key name }\n      }\n    }\n  }\n";
+/**
+ * Full single-project read for `el-linear projects read` (DEV-4610). Carries
+ * everything the `--format summary` project renderer shows (name, state, lead,
+ * teams, target, progress, url) plus the long-form `description`/`content` the
+ * JSON envelope exposes — so callers no longer fall back to a raw `graphql`
+ * query for a project URL or its content. The `progress` + `teams` fields also
+ * make the payload self-describing to the summary kind-inference.
+ */
+export declare const PROJECT_READ_QUERY = "\n  query ProjectRead($id: String!) {\n    project(id: $id) {\n      id\n      name\n      state\n      progress\n      url\n      startDate\n      targetDate\n      description\n      content\n      lead { id name displayName }\n      teams {\n        nodes { id key name }\n      }\n    }\n  }\n";
 export declare const GET_PROJECT_QUERY = "\n  query GetProject($name: String!) {\n    projects(filter: { name: { eqIgnoreCase: $name } }, first: 1) {\n      nodes {\n        id\n        name\n        teams {\n          nodes {\n            id\n            key\n            name\n          }\n        }\n      }\n    }\n  }\n";
 export declare const GET_PROJECT_TEAM_ISSUES_QUERY = "\n  query GetProjectTeamIssues($projectId: String!, $teamId: String!) {\n    project(id: $projectId) {\n      id\n      name\n      teams {\n        nodes {\n          id\n          key\n          name\n        }\n      }\n      issues(filter: { team: { id: { eq: $teamId } } }, first: 50) {\n        nodes {\n          id\n          identifier\n          title\n        }\n      }\n    }\n  }\n";
 export declare const SEARCH_PROJECTS_BY_NAME_QUERY = "\n  query SearchProjectsByName($name: String!) {\n    projects(filter: { name: { containsIgnoreCase: $name } }, first: 10) {\n      nodes {\n        id\n        name\n        state\n        teams {\n          nodes { id key name }\n        }\n      }\n    }\n  }\n";

package/dist/queries/projects.js

@@ -16,6 +16,33 @@ export const PROJECT_BY_ID_QUERY = `
     }
   }
 `;
+/**
+ * Full single-project read for `el-linear projects read` (DEV-4610). Carries
+ * everything the `--format summary` project renderer shows (name, state, lead,
+ * teams, target, progress, url) plus the long-form `description`/`content` the
+ * JSON envelope exposes — so callers no longer fall back to a raw `graphql`
+ * query for a project URL or its content. The `progress` + `teams` fields also
+ * make the payload self-describing to the summary kind-inference.
+ */
+export const PROJECT_READ_QUERY = `
+  query ProjectRead($id: String!) {
+    project(id: $id) {
+      id
+      name
+      state
+      progress
+      url
+      startDate
+      targetDate
+      description
+      content
+      lead { id name displayName }
+      teams {
+        nodes { id key name }
+      }
+    }
+  }
+`;
 export const GET_PROJECT_QUERY = `
   query GetProject($name: String!) {
     projects(filter: { name: { eqIgnoreCase: $name } }, first: 1) {

package/dist/utils/output.d.ts

@@ -11,6 +11,65 @@ export declare function setFieldsFilter(fields: string[] | null): void;
 export declare function setOutputFormat(format: OutputFormat): void;
 /** @internal Test seam — consumers should not depend on the format state. */
 export declare function getOutputFormat(): OutputFormat;
+/**
+ * Standard windowing / pagination / truncation metadata for any command
+ * that does not return its complete result set in one response.
+ *
+ * This is the canonical `WindowedMeta` type referenced by the
+ * output-transparency audit (DEV-3810 → DEV-4668). It promotes the
+ * `el-user usage` reference convention into the shared envelope so every
+ * consuming CLI uses the same field names instead of inventing ad-hoc
+ * `_window` / `_total` / `truncated` keys. The motivating principle:
+ * **every piece of data between a database and a decision-maker (human or
+ * LLM) should make its scope, limits, and assumptions visible in the
+ * output** — a consumer should never have to read source to interpret
+ * data correctly.
+ *
+ * All fields are optional: a command populates only the ones that apply.
+ * Because `ListMeta` / `ListExtraMeta` still carry an open
+ * `Record<string, unknown>` index, a CLI may also add its own
+ * domain-specific counters (`_total_hits`, `_indices_queried`,
+ * `_source_users_total`, …) alongside these — but where a generic field
+ * fits, prefer it so cross-CLI tooling and skills can read one shape.
+ *
+ * When to populate each field:
+ * - `_window` — the time/scope window applied, e.g. `"30d"`, `"12 months"`,
+ *   `"since 2026-06-01"`.
+ * - `_limit_applied` — the cap actually in effect (the value the caller
+ *   passed, or the command's default when they passed nothing).
+ * - `_query` — the search / filter expression applied to produce `data`.
+ * - `_total` — total matching rows *before* windowing / limiting /
+ *   filtering. Lets a consumer report "showing N of `_total`".
+ * - `_fetched` — how many rows are in *this* response (distinct from
+ *   `_total`). For list envelopes this equals `meta.count`.
+ * - `truncated` — `true` when `_fetched` hit `_limit_applied` and more
+ *   rows exist beyond this page. Skills MUST consume this rather than
+ *   counting returned rows to decide whether output is complete.
+ * - `availability` — per-response (or per-source) completeness signal.
+ *   Emit `{status: "degraded", detail}` when a sub-source failed (e.g. a
+ *   Slack timeout in an aggregator) rather than collapsing to an empty
+ *   result indistinguishable from "no hits".
+ */
+export interface WindowedMeta {
+    /** Time/scope window applied, e.g. `"30d"`, `"since 2026-06-01"`. */
+    _window?: string;
+    /** The cap actually in effect (caller's value, or the default). */
+    _limit_applied?: number;
+    /** The search / filter expression applied to produce `data`. */
+    _query?: string;
+    /** Total matching rows before windowing / limiting / filtering. */
+    _total?: number;
+    /** Rows in this response (equals `meta.count` for list envelopes). */
+    _fetched?: number;
+    /** `true` when `_fetched` hit `_limit_applied` — more rows exist. */
+    truncated?: boolean;
+    /** Per-response completeness signal; mirrors the `el-user` convention. */
+    availability?: {
+        status: "complete" | "partial" | "degraded";
+        /** Human-readable reason, e.g. `"result reached row cap 100"`. */
+        detail?: string;
+    };
+}
 /**
  * Resource-specific extra metadata that may be added to a list response
  * alongside the canonical `count` (e.g. `query` on search, `team` on
@@ -18,12 +77,16 @@ export declare function getOutputFormat(): OutputFormat;
  * accidentally pass a string `count` and have it silently overridden;
  * the only way to set `count` is via `data.length` inside `outputList`.
  *
+ * Intersected with {@link WindowedMeta} so the standard windowing fields
+ * (`_total`, `truncated`, `_window`, …) are typed when present, while the
+ * open `Record<string, unknown>` index still admits CLI-specific keys.
+ *
  * Implementation note: `count?: never` together with `Record<string, unknown>`
  * lets TypeScript accept any other key while disallowing the literal
  * `count` key. The `never`-typed property is impossible to assign, which
  * is what we want for the "no count here" contract.
  */
-export type ListExtraMeta = Record<string, unknown> & {
+export type ListExtraMeta = Record<string, unknown> & WindowedMeta & {
     count?: never;
 };
 /**
@@ -34,6 +97,10 @@ export type ListExtraMeta = Record<string, unknown> & {
  * read it both for emptiness checks (`.meta.count == 0`) and for the
  * actual magnitude (e.g. logging "found N issues"). A boolean isEmpty
  * would lose the magnitude signal, so `count: number` stays.
+ *
+ * The open `Record<string, unknown>` index admits the {@link WindowedMeta}
+ * fields a windowed list echoes (`_total`, `truncated`, `_window`, …);
+ * those are typed at the write site via {@link ListExtraMeta}.
  */
 export interface ListMeta extends Record<string, unknown> {
     count: number;

package/package.json

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