@enrichlayer/el-linear 1.9.0 → 1.15.0

package/dist/utils/graphql-service.d.ts

@@ -1,20 +1,18 @@
+import type { LinearCredential } from "../auth/linear-credential.js";
 import type { GraphQLResponseData, GraphQLVariables } from "../types/linear.js";
 import type { AuthOptions } from "./auth.js";
 /**
- * Constructor arg shapes for `GraphQLService`. Three variants:
- *   - `string` → personal API token (legacy; sent without `Bearer` prefix).
- *   - `{apiKey: string}` → personal API token (explicit).
- *   - `{oauthToken: string}` → OAuth access token (sent as
- *     `Authorization: Bearer <token>` via the SDK's accessToken option).
+ * Constructor arg for `GraphQLService`. Re-exported alias of the shared
+ * `LinearCredential` union (`{ apiKey } | { oauthToken }`). Kept as a
+ * named local export so call sites that already import
+ * `GraphQLServiceAuth` keep compiling — the alias collapses through to
+ * the shared shape.
  *
- * The string variant exists because hundreds of call sites and tests pass
- * a plain string. We continue to support it indefinitely.
+ * The bare-string legacy arm was dropped in DEV-4068 T7. Tests now
+ * construct with `{ apiKey: "test-token" }` (mechanical rewrite, no
+ * semantic change — same `Authorization: <token>` header is emitted).
  */
-export type GraphQLServiceAuth = string | {
-    apiKey: string;
-} | {
-    oauthToken: string;
-};
+export type GraphQLServiceAuth = LinearCredential;
 export declare class GraphQLService {
     private readonly graphQLClient;
     constructor(auth: GraphQLServiceAuth);

package/dist/utils/graphql-service.js

@@ -2,9 +2,6 @@ import { LinearClient } from "@linear/sdk";
 import { getActiveAuth } from "../auth/token-resolver.js";
 function buildLinearClient(auth) {
     const baseHeaders = { "public-file-urls-expire-in": "3600" };
-    if (typeof auth === "string") {
-        return new LinearClient({ apiKey: auth, headers: baseHeaders });
-    }
     if ("oauthToken" in auth) {
         // Linear's SDK natively supports OAuth via the `accessToken` option,
         // which causes the underlying graphql-request client to send

package/dist/utils/issue-reference-extractor.d.ts

@@ -5,6 +5,13 @@ export interface IssueReference {
     reverse: boolean;
     type: IssueRelationType;
 }
+/**
+ * Specificity ranking — used when the same identifier appears more than once
+ * in the text with different qualifiers. The strongest non-default inference
+ * wins. Exported because `auto-link-references` does the same merge over its
+ * own description+comments fan-in (DEV-4070 deduplication).
+ */
+export declare function specificity(ref: IssueReference): number;
 /**
  * Extract issue identifiers from text along with the inferred relation type.
  *

package/dist/utils/issue-reference-extractor.js

@@ -45,10 +45,12 @@ function inferRelation(textBefore) {
     return { type: "related", reverse: false };
 }
 /**
- * Specificity ranking — used when the same identifier appears more than once in the text
- * with different qualifiers. The strongest non-default inference wins.
+ * Specificity ranking — used when the same identifier appears more than once
+ * in the text with different qualifiers. The strongest non-default inference
+ * wins. Exported because `auto-link-references` does the same merge over its
+ * own description+comments fan-in (DEV-4070 deduplication).
  */
-function specificity(ref) {
+export function specificity(ref) {
     if (ref.type === "duplicate") {
         return 3;
     }

package/dist/utils/issues-service-bootstrap.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Service-trio bootstrap helper.
+ *
+ * The 3-line incantation
+ *
+ * ```ts
+ * const graphQLService = await createGraphQLService(rootOpts);
+ * const linearService = await createLinearService(rootOpts);
+ * const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+ * ```
+ *
+ * repeats verbatim across ~13 issue/batch command handlers. This helper
+ * collapses it to a single line; callers destructure only what they use.
+ *
+ * Sites that need just `graphQLService` + `linearService` (no `issuesService`)
+ * can keep their direct calls — there's no benefit to routing through a
+ * helper that constructs an unused third service.
+ */
+import type { AuthOptions } from "./auth.js";
+import { GraphQLIssuesService } from "./graphql-issues-service.js";
+import { type GraphQLService } from "./graphql-service.js";
+import { type LinearService } from "./linear-service.js";
+export interface IssuesServiceTrio {
+    graphQLService: GraphQLService;
+    linearService: LinearService;
+    issuesService: GraphQLIssuesService;
+}
+export declare function createIssuesService(options: AuthOptions): Promise<IssuesServiceTrio>;

package/dist/utils/issues-service-bootstrap.js

@@ -0,0 +1,27 @@
+/**
+ * Service-trio bootstrap helper.
+ *
+ * The 3-line incantation
+ *
+ * ```ts
+ * const graphQLService = await createGraphQLService(rootOpts);
+ * const linearService = await createLinearService(rootOpts);
+ * const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+ * ```
+ *
+ * repeats verbatim across ~13 issue/batch command handlers. This helper
+ * collapses it to a single line; callers destructure only what they use.
+ *
+ * Sites that need just `graphQLService` + `linearService` (no `issuesService`)
+ * can keep their direct calls — there's no benefit to routing through a
+ * helper that constructs an unused third service.
+ */
+import { GraphQLIssuesService } from "./graphql-issues-service.js";
+import { createGraphQLService, } from "./graphql-service.js";
+import { createLinearService } from "./linear-service.js";
+export async function createIssuesService(options) {
+    const graphQLService = await createGraphQLService(options);
+    const linearService = await createLinearService(options);
+    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    return { graphQLService, linearService, issuesService };
+}

package/dist/utils/linear-service.d.ts

@@ -1,20 +1,13 @@
+import type { LinearCredential } from "../auth/linear-credential.js";
 import type { LinearComment, LinearCycleDetail, LinearCycleSummary, LinearLabel, LinearProject, LinearTeam, LinearUser } from "../types/linear.js";
 import type { AuthOptions } from "./auth.js";
 /**
- * Constructor arg shapes for `LinearService`. Three variants:
- *   - `string` → personal API token (legacy; sent without `Bearer` prefix).
- *   - `{apiKey: string}` → personal API token (explicit).
- *   - `{oauthToken: string}` → OAuth access token (sent as
- *     `Authorization: Bearer <token>` via the SDK's accessToken option).
- *
- * The string variant exists because hundreds of call sites and tests pass
- * a plain string. We continue to support it indefinitely.
+ * Constructor arg for `LinearService`. Re-exported alias of the shared
+ * `LinearCredential` union (`{ apiKey } | { oauthToken }`). See
+ * `src/auth/linear-credential.ts` for the contract. The bare-string
+ * legacy arm was dropped in DEV-4068 T7.
  */
-export type LinearServiceAuth = string | {
-    apiKey: string;
-} | {
-    oauthToken: string;
-};
+export type LinearServiceAuth = LinearCredential;
 export declare class LinearService {
     private readonly client;
     constructor(auth: LinearServiceAuth);
@@ -26,6 +19,8 @@ export declare class LinearService {
         nameFilter?: string;
         states?: string[];
         excludeStates?: string[];
+        /** Resolved team UUID — applied as a server-side filter before pagination. */
+        teamId?: string;
     }): Promise<LinearProject[]>;
     resolveTeamId(teamKeyOrNameOrId: string): Promise<string>;
     resolveStatusId(statusName: string, teamId?: string): Promise<string>;
@@ -40,6 +35,18 @@ export declare class LinearService {
     getCycles(teamFilter?: string, activeOnly?: boolean, limit?: number): Promise<LinearCycleSummary[]>;
     getCycleById(cycleId: string, issuesLimit?: number): Promise<LinearCycleDetail>;
     resolveCycleId(cycleNameOrId: string, teamFilter?: string): Promise<string>;
-    resolveProjectId(projectNameOrId: string): Promise<string>;
+    resolveProjectId(projectInput: string): Promise<string>;
+    /**
+     * Normalize a user-supplied project input to a UUID when the input is
+     * a URL or slug-id form. Pass-through for UUIDs and plain names — the
+     * latter stays a name so downstream batch-resolve queries can fold the
+     * lookup into their single round-trip.
+     *
+     * Used by callers that route project resolution through a separate
+     * batch-resolve step (e.g. `GraphqlIssuesService.createIssue`) — they
+     * can pre-normalize URL/slug inputs to UUIDs so the batch query's
+     * `name eqIgnoreCase` filter doesn't have to learn the URL/slug shape.
+     */
+    normalizeProjectInput(projectInput: string): Promise<string>;
 }
 export declare function createLinearService(options: AuthOptions): Promise<LinearService>;

package/dist/utils/linear-service.js

@@ -4,6 +4,7 @@ import { resolveUserDisplayName } from "../config/resolver.js";
 import { toISOStringOrNow, toISOStringOrUndefined } from "./date-format.js";
 import { multipleMatchesError, notFoundError } from "./error-messages.js";
 import { parseIssueIdentifier } from "./identifier-parser.js";
+import { parseProjectSlugId } from "./project-slug.js";
 import { isUuid } from "./uuid.js";
 const DEFAULT_CYCLE_PAGINATION_LIMIT = 250;
 // The Linear SDK types don't accept string orderBy values, but the API does.
@@ -22,9 +23,6 @@ function nonEmptyFilter(filter) {
     return Object.keys(filter).length > 0 ? filter : undefined;
 }
 function buildLinearClient(auth) {
-    if (typeof auth === "string") {
-        return new LinearClient({ apiKey: auth });
-    }
     if ("oauthToken" in auth) {
         // Linear's SDK natively supports OAuth via the `accessToken` option,
         // which causes the underlying transport to send
@@ -133,13 +131,28 @@ export class LinearService {
         else if (options.excludeStates && options.excludeStates.length > 0) {
             filter.state = { nin: options.excludeStates };
         }
-        const projects = await this.client.projects({
+        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: limit,
+            first: unlimited ? 250 : limit,
             orderBy: sdkOrderBy("updatedAt"),
             includeArchived: false,
         });
-        const projectsWithData = await Promise.all(projects.nodes.map(async (project) => {
+        const projectNodes = [...page.nodes];
+        if (unlimited) {
+            while (page.pageInfo.hasNextPage) {
+                page = await page.fetchNext();
+                projectNodes.push(...page.nodes);
+            }
+        }
+        const projectsWithData = await Promise.all(projectNodes.map(async (project) => {
             const [teams, lead] = await Promise.all([
                 project.teams(),
                 project.lead,
@@ -373,6 +386,9 @@ export class LinearService {
                 url: issue.url,
                 title: issue.title,
                 description: issue.description || undefined,
+                // Linear SDK types `priority` as `number`; the GraphQL schema only
+                // emits 0-4, so the cast is safe and the runtime range is
+                // guaranteed by Linear's server-side schema.
                 priority: issue.priority,
                 estimate: issue.estimate || undefined,
                 state: state ? { id: state.id, name: state.name } : undefined,
@@ -455,20 +471,66 @@ export class LinearService {
         }
         return chosen.id;
     }
-    async resolveProjectId(projectNameOrId) {
-        if (isUuid(projectNameOrId)) {
-            return projectNameOrId;
+    async resolveProjectId(projectInput) {
+        if (isUuid(projectInput)) {
+            return projectInput;
+        }
+        const slugId = parseProjectSlugId(projectInput);
+        if (slugId) {
+            // `as Record<string, unknown>` — `@linear/sdk`'s typed ProjectFilter
+            // lags Linear's schema and doesn't yet expose `slugId`. The field is
+            // present on the server; the cast is here until the SDK ships the
+            // typing. Don't "clean up" without verifying the typed shape exists.
+            //
+            // `includeArchived: true` — URLs in the wild often point at archived
+            // projects (someone digs up an old link); silently 404-ing them is
+            // worse than resolving to an archived project, which the caller can
+            // inspect via the returned UUID. Name resolution stays active-only
+            // because names collide more readily than slug-ids do.
+            const bySlug = await this.client.projects({
+                filter: { slugId: { eq: slugId } },
+                first: 1,
+                includeArchived: true,
+            });
+            if (bySlug.nodes.length > 0) {
+                return bySlug.nodes[0].id;
+            }
+            // Slug-id form was syntactically valid but didn't match a project
+            // — fall through to name resolution would be misleading (the user
+            // clearly pasted a URL/slug, not a name). Throw the same shape of
+            // not-found error as the name path.
+            throw notFoundError("Project", projectInput);
         }
-        const filter = { name: { eqIgnoreCase: projectNameOrId } };
+        const filter = { name: { eqIgnoreCase: projectInput } };
         const projectsConnection = await this.client.projects({
             filter,
             first: 1,
         });
         if (projectsConnection.nodes.length === 0) {
-            throw notFoundError("Project", projectNameOrId);
+            throw notFoundError("Project", projectInput);
         }
         return projectsConnection.nodes[0].id;
     }
+    /**
+     * Normalize a user-supplied project input to a UUID when the input is
+     * a URL or slug-id form. Pass-through for UUIDs and plain names — the
+     * latter stays a name so downstream batch-resolve queries can fold the
+     * lookup into their single round-trip.
+     *
+     * Used by callers that route project resolution through a separate
+     * batch-resolve step (e.g. `GraphqlIssuesService.createIssue`) — they
+     * can pre-normalize URL/slug inputs to UUIDs so the batch query's
+     * `name eqIgnoreCase` filter doesn't have to learn the URL/slug shape.
+     */
+    async normalizeProjectInput(projectInput) {
+        if (isUuid(projectInput)) {
+            return projectInput;
+        }
+        if (parseProjectSlugId(projectInput)) {
+            return this.resolveProjectId(projectInput);
+        }
+        return projectInput;
+    }
 }
 export async function createLinearService(options) {
     const auth = await getActiveAuth(options);

package/dist/utils/markdown-prosemirror.js

@@ -88,7 +88,7 @@ function parseFencedCodeBlock(state, line) {
         attrs.language = language;
     }
     state.content.push({
-        type: "codeBlock",
+        type: "code_block",
         ...(Object.keys(attrs).length > 0 ? { attrs } : {}),
         content: codeLines.length > 0
             ? [{ type: "text", text: codeLines.join("\n") }]
@@ -100,7 +100,7 @@ function parseHorizontalRule(state, line) {
     if (!HR_RE.test(line)) {
         return false;
     }
-    state.content.push({ type: "horizontalRule" });
+    state.content.push({ type: "horizontal_rule" });
     state.i++;
     return true;
 }
@@ -128,12 +128,12 @@ function parseBulletList(state, line) {
             break;
         }
         items.push({
-            type: "listItem",
+            type: "list_item",
             content: [{ type: "paragraph", content: parseInline(m[1]) }],
         });
         state.i++;
     }
-    state.content.push({ type: "bulletList", content: items });
+    state.content.push({ type: "bullet_list", content: items });
     return true;
 }
 function parseOrderedList(state, line) {
@@ -147,12 +147,12 @@ function parseOrderedList(state, line) {
             break;
         }
         items.push({
-            type: "listItem",
+            type: "list_item",
             content: [{ type: "paragraph", content: parseInline(m[1]) }],
         });
         state.i++;
     }
-    state.content.push({ type: "orderedList", content: items });
+    state.content.push({ type: "ordered_list", content: items });
     return true;
 }
 function parseBlockquote(state) {
@@ -217,9 +217,9 @@ function parseTable(state, line) {
     const headerCells = splitTableRow(rowMatch[1]);
     const cols = headerCells.length;
     rows.push({
-        type: "tableRow",
+        type: "table_row",
         content: headerCells.map((cell) => ({
-            type: "tableHeader",
+            type: "table_header",
             content: [{ type: "paragraph", content: cellContent(cell) }],
         })),
     });
@@ -238,9 +238,9 @@ function parseTable(state, line) {
         }
         cells.length = cols;
         rows.push({
-            type: "tableRow",
+            type: "table_row",
             content: cells.map((cell) => ({
-                type: "tableCell",
+                type: "table_cell",
                 content: [{ type: "paragraph", content: cellContent(cell) }],
             })),
         });
@@ -327,7 +327,7 @@ function findEarliestInlineMatch(text) {
             index: boldMatch.index ?? 0,
             length: boldMatch[0].length,
             innerText: boldMatch[1] ?? boldMatch[2],
-            marks: [{ type: "bold" }],
+            marks: [{ type: "strong" }],
         });
     }
     const italicMatch = text.match(INLINE_ITALIC_RE);
@@ -336,7 +336,7 @@ function findEarliestInlineMatch(text) {
             index: italicMatch.index ?? 0,
             length: italicMatch[0].length,
             innerText: italicMatch[1] ?? italicMatch[2],
-            marks: [{ type: "italic" }],
+            marks: [{ type: "em" }],
         });
     }
     if (candidates.length === 0) {

package/dist/utils/mention-resolver.js

@@ -146,7 +146,7 @@ function injectMentions(doc, explicit, bare) {
     return {
         ...doc,
         content: doc.content.map((node) => {
-            if (node.content && node.type !== "codeBlock") {
+            if (node.content && node.type !== "code_block") {
                 const processed = injectMentions(node, explicit, bare);
                 if (node.type === "paragraph" || node.type === "heading") {
                     return {

package/dist/utils/output.d.ts

@@ -1,11 +1,91 @@
-export type OutputFormat = "json" | "summary";
+type OutputFormat = "json" | "summary";
 export declare function setRawMode(enabled: boolean): void;
 export declare function setJqFilter(filter: string | null): void;
 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;
+/**
+ * Resource-specific extra metadata that may be added to a list response
+ * alongside the canonical `count` (e.g. `query` on search, `team` on
+ * filtered list). Excludes `count` at the type level — callers can't
+ * accidentally pass a string `count` and have it silently overridden;
+ * the only way to set `count` is via `data.length` inside `outputList`.
+ *
+ * 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> & {
+    count?: never;
+};
+/**
+ * Metadata envelope for list responses. Always includes `count`; resources
+ * may add their own keys (e.g. `query` on search, `team` on filtered list).
+ *
+ * `meta.count` is the cardinality of `data[]` — downstream `jq` pipelines
+ * 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.
+ */
+export interface ListMeta extends Record<string, unknown> {
+    count: number;
+}
+/**
+ * Canonical JSON envelope for a list response. Pre-DEV-4068 T6, every
+ * call site built this object literal inline and `outputSuccess(data:
+ * unknown)` accepted it without type-checking. Use `outputList<T>` to
+ * route a list through the same emit path with a real per-element type
+ * (so e.g. `data: T[]` and `--fields` consumers stay in lock-step).
+ */
+export interface CliListEnvelope<T> {
+    data: T[];
+    meta: ListMeta;
+}
+/**
+ * Typed wrapper around `outputSuccess` for list responses — builds the
+ * `{ data, meta: { count, ...extraMeta } }` envelope and emits it. The
+ * 81 existing inline `outputSuccess({ data, meta: { count, ... } })`
+ * call sites can migrate to this incrementally; both go through the
+ * same `outputSuccess` emit path so JSON / summary / --raw / --fields /
+ * --jq behavior is identical.
+ *
+ * @param data    The array payload.
+ * @param extraMeta Optional resource-specific meta keys (e.g. `query`,
+ *                  `team`). The type excludes `count` — `count` is
+ *                  always computed from `data.length` to preserve the
+ *                  wire-contract invariant.
+ */
+export declare function outputList<T>(data: T[], extraMeta?: ListExtraMeta): void;
+/**
+ * Typed wrapper around `outputSuccess` for a single-resource response.
+ * Pure passthrough — the envelope contract for single resources is just
+ * the resource object itself (no `data`/`meta` wrapping). Same emit
+ * path as `outputSuccess` and `outputList`; this overload exists so
+ * call sites can document their intent at the type level.
+ *
+ * The conditional return type rejects array inputs at the type level —
+ * a caller that meant `outputList` and passed an array gets a compile
+ * error pointing them at the right helper. Runtime behavior on an array
+ * is unchanged (it'd still emit JSON), but the type catches the foot-gun.
+ */
+export declare function outputSingle<T>(data: T extends readonly unknown[] ? "outputSingle does not accept arrays — use outputList(data) instead" : T): void;
 export declare function outputSuccess(data: unknown): void;
+/**
+ * Emit a `results_truncated` warning when a list command's result count
+ * equals the requested `--limit`, signaling to the caller (typically an
+ * AI agent) that more results may exist beyond the page. Heuristic, not
+ * exact — `length === limit` has a false-positive when the workspace
+ * happens to hold exactly `limit` matching items. Accurate `hasNextPage`
+ * would require widening every list-service return type; deferred until
+ * a caller cares about the false-positive rate.
+ *
+ * Message includes a concrete next-step (suggested `--limit` is 2× the
+ * current limit) so the agent doesn't have to derive it.
+ */
+export declare function warnIfTruncated(count: number, limit: number): void;
 export declare function outputWarning(message: string | string[]): void;
 export declare function resetWarnings(): void;
-export declare function resetOutputFormat(): void;
 export declare function handleAsyncCommand<TArgs extends unknown[]>(asyncFn: (...args: TArgs) => Promise<void>): (...args: TArgs) => Promise<void>;
+export {};

package/dist/utils/output.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { dispatch as dispatchSummary, inferKindFromPayload, } from "./formatters/summary.js";
 import { logger } from "./logger.js";
+import { sanitizeForLog } from "./sanitize-for-log.js";
 const warningBuffer = [];
 let rawMode = false;
 let jqFilter = null;
@@ -18,6 +19,7 @@ export function setFieldsFilter(fields) {
 export function setOutputFormat(format) {
     outputFormat = format;
 }
+/** @internal Test seam — consumers should not depend on the format state. */
 export function getOutputFormat() {
     return outputFormat;
 }
@@ -38,14 +40,51 @@ function filterFields(obj, fields) {
     return obj;
 }
 /**
- * Emit a summary-format render to stdout for the given payload. The
- * caller (`outputSuccess`) has already applied `--raw` and `--fields`,
- * so the value here is post-filter — no need to unwrap again.
+ * Emit a summary-format render to stdout for the given payload.
+ *
+ * `kind` is captured upstream from the **pre-filter** payload — if we
+ * inferred here, `--fields identifier,url` would strip `title` and
+ * the heuristic would fall through to "generic", silently breaking
+ * the issue-list table. Caching the pre-filter shape keeps the
+ * formatter accurate regardless of how the user pared the JSON.
  */
-function emitSummary(payload) {
-    const kind = inferKindFromPayload(payload);
+function emitSummary(payload, kind) {
     logger.info(dispatchSummary(kind, payload));
 }
+/**
+ * Typed wrapper around `outputSuccess` for list responses — builds the
+ * `{ data, meta: { count, ...extraMeta } }` envelope and emits it. The
+ * 81 existing inline `outputSuccess({ data, meta: { count, ... } })`
+ * call sites can migrate to this incrementally; both go through the
+ * same `outputSuccess` emit path so JSON / summary / --raw / --fields /
+ * --jq behavior is identical.
+ *
+ * @param data    The array payload.
+ * @param extraMeta Optional resource-specific meta keys (e.g. `query`,
+ *                  `team`). The type excludes `count` — `count` is
+ *                  always computed from `data.length` to preserve the
+ *                  wire-contract invariant.
+ */
+export function outputList(data, extraMeta) {
+    const meta = { ...extraMeta, count: data.length };
+    const envelope = { data, meta };
+    outputSuccess(envelope);
+}
+/**
+ * Typed wrapper around `outputSuccess` for a single-resource response.
+ * Pure passthrough — the envelope contract for single resources is just
+ * the resource object itself (no `data`/`meta` wrapping). Same emit
+ * path as `outputSuccess` and `outputList`; this overload exists so
+ * call sites can document their intent at the type level.
+ *
+ * The conditional return type rejects array inputs at the type level —
+ * a caller that meant `outputList` and passed an array gets a compile
+ * error pointing them at the right helper. Runtime behavior on an array
+ * is unchanged (it'd still emit JSON), but the type catches the foot-gun.
+ */
+export function outputSingle(data) {
+    outputSuccess(data);
+}
 export function outputSuccess(data) {
     const warnings = drainWarnings();
     let output;
@@ -58,6 +97,11 @@ export function outputSuccess(data) {
     else {
         output = data;
     }
+    // Capture the kind from the original envelope shape BEFORE --raw /
+    // --fields stripping. Otherwise filtering away signature fields (e.g.
+    // `title` on an issue) breaks shape inference and the summary
+    // formatter falls back to the generic key-value dump.
+    const inferredKind = outputFormat === "summary" ? inferKindFromPayload(output) : "generic";
     // --raw: unwrap { data: [...] } to just the array
     if (rawMode &&
         output !== null &&
@@ -87,7 +131,7 @@ export function outputSuccess(data) {
     // as a human-readable block. We bypass the jq path because jq is a
     // JSON-shape filter — it doesn't compose with text output.
     if (outputFormat === "summary") {
-        emitSummary(output);
+        emitSummary(output, inferredKind);
         return;
     }
     if (jqFilter) {
@@ -111,6 +155,25 @@ export function outputSuccess(data) {
         logger.info(JSON.stringify(output, null, 2));
     }
 }
+/**
+ * Emit a `results_truncated` warning when a list command's result count
+ * equals the requested `--limit`, signaling to the caller (typically an
+ * AI agent) that more results may exist beyond the page. Heuristic, not
+ * exact — `length === limit` has a false-positive when the workspace
+ * happens to hold exactly `limit` matching items. Accurate `hasNextPage`
+ * would require widening every list-service return type; deferred until
+ * a caller cares about the false-positive rate.
+ *
+ * Message includes a concrete next-step (suggested `--limit` is 2× the
+ * current limit) so the agent doesn't have to derive it.
+ */
+export function warnIfTruncated(count, limit) {
+    if (count !== limit) {
+        return;
+    }
+    outputWarning(`results_truncated: returned ${count} matching --limit ${limit}; more results may exist. ` +
+        `Re-run with --limit ${limit * 2} (or narrow via filters like --name, --state, --team) to verify.`);
+}
 export function outputWarning(message) {
     const messages = Array.isArray(message) ? message : [message];
     for (const msg of messages) {
@@ -127,16 +190,18 @@ function drainWarnings() {
 export function resetWarnings() {
     warningBuffer.length = 0;
 }
-export function resetOutputFormat() {
-    outputFormat = "json";
-}
 function outputError(error) {
-    const payload = JSON.stringify({ error: error.message }, null, 2);
+    // Run the message and stack through sanitizeForLog so a future SDK
+    // upgrade (or proxy/MITM error body) that embeds `lin_api_…` /
+    // `lin_oauth_…` / `Bearer <payload>` in error text can't leak a token
+    // into stdout, shell history, or CI logs. The wizard already sanitizes
+    // its own log paths; this is the central error path on every command.
+    const payload = JSON.stringify({ error: sanitizeForLog(error.message) }, null, 2);
     // Write to stdout (same channel as success) so machine callers always
     // receive exactly one parseable JSON object regardless of stream capture.
     logger.info(payload);
     if (process.env.EL_LINEAR_DEBUG ?? process.env.LINCTL_DEBUG) {
-        logger.error(error.stack ?? "");
+        logger.error(sanitizeForLog(error.stack ?? ""));
     }
     process.exit(1);
 }