linear-sdk-cli 0.5.3 → 0.7.0

package/src/lib/options.ts

@@ -399,6 +399,10 @@ export const FIELDS_COMMANDS: ReadonlySet<string> = new Set([
   "project list",
   "project view",
   "project milestones",
+  "project-status list",
+  "project-status view",
+  "project-label list",
+  "project-label view",
   "project-update list",
   "roadmap list",
   "roadmap view",
@@ -418,8 +422,9 @@ export const FIELDS_COMMANDS: ReadonlySet<string> = new Set([
   "webhook view",
 ]);
 
-/** Commands that page through a query: `--limit <n>` caps them, `--all` (or `--limit 0`) exhausts them. */
+/** Commands with bounded lists: `--limit <n>` caps them, `--all` (or `--limit 0`) exhausts them. */
 export const LIMIT_COMMANDS: ReadonlySet<string> = new Set([
+  "changelog",
   "attachment list",
   "comment list",
   "cycle list",
@@ -444,6 +449,8 @@ export const LIMIT_COMMANDS: ReadonlySet<string> = new Set([
   "organization invites",
   "project list",
   "project milestones",
+  "project-status list",
+  "project-label list",
   "project-update list",
   "roadmap list",
   "state list",
@@ -510,7 +517,10 @@ export const YES_COMMANDS: ReadonlySet<string> = new Set([
   "milestone delete",
   "notification archive",
   "project archive",
+  "project-status archive",
   "project delete",
+  "project-label retire",
+  "project-label delete",
   "roadmap delete",
   "team delete",
   "webhook delete",

package/src/lib/output-shapes.ts

@@ -51,6 +51,11 @@ import {
   PROJECT_MILESTONE_ROW_SHAPE,
   PROJECT_ROW_SHAPE,
 } from "../services/project.js";
+import {
+  PROJECT_STATUS_DETAIL_SHAPE,
+  PROJECT_STATUS_ROW_SHAPE,
+} from "../services/project-status.js";
+import { PROJECT_LABEL_DETAIL_SHAPE, PROJECT_LABEL_ROW_SHAPE } from "../services/project-label.js";
 import { ROADMAP_DETAIL_SHAPE, ROADMAP_ROW_SHAPE } from "../services/roadmap.js";
 import { STATE_DETAIL_SHAPE, STATE_ROW_SHAPE } from "../services/state.js";
 import {
@@ -140,6 +145,14 @@ const UPDATE_RECEIPT_SHAPE = shape<UpdateRow & { url: string }>({
   url: "string",
 });
 
+const AUTHORIZATION_CAPABILITIES: ObjectFields = {
+  credentialType: "string|null",
+  scopeVisibility: "string",
+  scopes: { nullable: ["string"] },
+  adminScope: "boolean|null",
+  note: "string",
+};
+
 /** `whoami` / `auth whoami`. */
 const WHOAMI_SHAPE: ObjectFields = {
   id: "string",
@@ -147,6 +160,7 @@ const WHOAMI_SHAPE: ObjectFields = {
   displayName: "string",
   email: "string",
   admin: "boolean",
+  authorization: AUTHORIZATION_CAPABILITIES,
   organization: { id: "string", name: "string", urlKey: "string" },
 };
 
@@ -299,6 +313,13 @@ const RAW_API: OutputShape = {
 export const OUTPUT_SHAPES: Record<string, OutputShape | null> = {
   api: RAW_API,
 
+  changelog: list({
+    version: "string",
+    date: "string",
+    url: "string",
+    sections: [{ title: "string", items: ["string"] }],
+  }),
+
   attachment: null,
   "attachment create": receipt({ id: "string", title: "string", url: "string" }),
   "attachment delete": receipt({ id: "string", title: "string", deleted: "boolean" }),
@@ -348,6 +369,9 @@ export const OUTPUT_SHAPES: Record<string, OutputShape | null> = {
     keyring: "string|null",
     scopes: { nullable: ["string"] },
     expiresAt: "string|null",
+    scopeVisibility: "string",
+    adminScope: "boolean|null",
+    scopeNote: "string",
   }),
   "auth token": object({ apiKey: "string", workspace: "string|null" }),
   "auth whoami": WHOAMI,
@@ -620,6 +644,31 @@ export const OUTPUT_SHAPES: Record<string, OutputShape | null> = {
   "project update": receipt(NAMED_URL_RECEIPT),
   "project view": object(PROJECT_DETAIL_SHAPE),
 
+  "project-status": null,
+  "project-status archive": receipt({ id: "string", name: "string", archived: "boolean" }),
+  "project-status create": receipt({
+    id: "string",
+    name: "string",
+    type: "string",
+  }),
+  "project-status list": list(PROJECT_STATUS_ROW_SHAPE),
+  "project-status unarchive": receipt({ id: "string", name: "string", archived: "boolean" }),
+  "project-status update": receipt({
+    id: "string",
+    name: "string",
+    type: "string",
+  }),
+  "project-status view": object(PROJECT_STATUS_DETAIL_SHAPE),
+
+  "project-label": null,
+  "project-label create": receipt({ id: "string", name: "string", color: "string" }),
+  "project-label delete": receipt(NAMED_DELETED),
+  "project-label list": list(PROJECT_LABEL_ROW_SHAPE),
+  "project-label restore": receipt({ id: "string", name: "string", restored: "boolean" }),
+  "project-label retire": receipt({ id: "string", name: "string", retired: "boolean" }),
+  "project-label update": receipt({ id: "string", name: "string", color: "string" }),
+  "project-label view": object(PROJECT_LABEL_DETAIL_SHAPE),
+
   "project-update": null,
   "project-update create": receipt(UPDATE_RECEIPT_SHAPE),
   "project-update list": list(UPDATE_ROW_SHAPE),

package/src/lib/resolve.ts

@@ -315,10 +315,15 @@ export async function resolveProjectLabelIds(
   client: LinearClient,
   names: string[],
 ): Promise<string[]> {
-  const ids: string[] = [];
+  const labels: any[] = [];
   for (const name of names) {
     if (isUuid(name)) {
-      ids.push(name);
+      const label: any = await withRetry(() => (client as any).projectLabel(name));
+      if (label.isGroup)
+        throw usageError(`Project label '${label.name}' is a group and cannot be assigned.`);
+      if (label.retiredAt || label.retiredById)
+        throw usageError(`Project label '${label.name}' is retired and cannot be assigned.`);
+      labels.push(label);
       continue;
     }
     const conn: any = await withRetry(() =>
@@ -327,21 +332,33 @@ export async function resolveProjectLabelIds(
         first: RESOLVE_PAGE,
       }),
     );
-    const nodes = await scanAll<any>(conn, "project labels", "linear project label list");
-    const candidates = nodes.filter((l) => !l.isGroup);
+    const nodes = await scanAll<any>(conn, "project labels", "linear project-label list");
+    const candidates = nodes.filter((l) => !l.isGroup && !l.retiredAt && !l.retiredById);
     if (candidates.length === 0)
       throw notFound(
-        `No project label matching '${name}'. Run 'linear project label list' to see the options.`,
+        `No project label matching '${name}'. Run 'linear project-label list' to see the options.`,
       );
 
     const exact = candidates.filter((l) => l.name === name);
     const finalists = exact.length ? exact : candidates;
     if (finalists.length > 1)
       throw ambiguous(`Multiple project labels named '${name}'; pass the label id instead.`);
-    ids.push(finalists[0]!.id);
+    labels.push(finalists[0]!);
+  }
+  const byParent = new Map<string, any>();
+  for (const label of labels) {
+    const parentId = label.parentId;
+    if (!parentId) continue;
+    const other = byParent.get(parentId);
+    if (other && other.id !== label.id) {
+      throw usageError(
+        `Project labels '${other.name}' and '${label.name}' belong to the same mutually exclusive group; choose one.`,
+      );
+    }
+    byParent.set(parentId, label);
   }
   // The same label named twice (or by name and id) must not be sent twice.
-  return [...new Set(ids)];
+  return [...new Set(labels.map((label) => label.id))];
 }
 
 /** First workflow state of a given type (lowest position) within a team. */

package/src/output/format.ts

@@ -217,6 +217,7 @@ export class Output {
       // absent entirely without --debug.
       const error: Record<string, unknown> = { message: err.message, code: err.code };
       if (err.suggestion !== undefined) error.suggestion = err.suggestion;
+      if (err.details !== undefined) error.details = err.details;
       if (showDetail) error.detail = err.detail;
       process.stderr.write(JSON.stringify({ error }) + "\n");
       return;

package/src/services/project-label.ts

@@ -0,0 +1,238 @@
+/** First-class project-label access. Project labels are distinct from issue labels. */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { ambiguous, notFound, usageError } from "../lib/errors.js";
+import { assertMutation, unwrapMutation } from "../lib/mutation.js";
+import { collectRawQuery } from "../lib/pagination.js";
+import { shape } from "../lib/shape.js";
+import { isUuid } from "../lib/resolve.js";
+
+export interface ProjectLabelRow {
+  id: string;
+  name: string;
+  color: string;
+  description: string | null;
+  isGroup: boolean;
+  parent: { id: string; name: string } | null;
+  retiredAt: string | null;
+}
+
+export interface ProjectLabelDetail extends ProjectLabelRow {
+  children: Array<{ id: string; name: string; color: string; retiredAt: string | null }>;
+}
+
+export const PROJECT_LABEL_ROW_SHAPE = shape<ProjectLabelRow>({
+  id: "string",
+  name: "string",
+  color: "string",
+  description: "string|null",
+  isGroup: "boolean",
+  parent: { nullable: { id: "string", name: "string" } },
+  retiredAt: "string|null",
+});
+
+export const PROJECT_LABEL_DETAIL_SHAPE = shape<ProjectLabelDetail>({
+  ...PROJECT_LABEL_ROW_SHAPE,
+  children: [{ id: "string", name: "string", color: "string", retiredAt: "string|null" }],
+});
+
+const FIELDS = `
+  id name color description isGroup retiredAt
+  parent { id name }
+`;
+
+const LIST_QUERY = `
+query CliProjectLabels($filter: ProjectLabelFilter, $first: Int!, $after: String, $includeArchived: Boolean) {
+  projectLabels(filter: $filter, first: $first, after: $after, includeArchived: $includeArchived) {
+    nodes { ${FIELDS} }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+
+const VIEW_QUERY = `
+query CliProjectLabel($id: String!) {
+  projectLabel(id: $id) {
+    ${FIELDS}
+    children(first: 250, includeArchived: true) {
+      nodes { id name color retiredAt }
+    }
+  }
+}`;
+
+function row(node: any): ProjectLabelRow {
+  return {
+    id: node.id,
+    name: node.name,
+    color: node.color,
+    description: node.description ?? null,
+    isGroup: !!node.isGroup,
+    parent: node.parent ?? null,
+    retiredAt: node.retiredAt ?? null,
+  };
+}
+
+export async function listProjectLabels(
+  client: LinearClient,
+  limit: number,
+  includeRetired = false,
+): Promise<ProjectLabelRow[]> {
+  return collectRawQuery<ProjectLabelRow>(
+    client as any,
+    LIST_QUERY,
+    { includeArchived: includeRetired },
+    "projectLabels",
+    limit,
+    row,
+  );
+}
+
+async function resolveProjectLabelId(
+  client: LinearClient,
+  input: string,
+  groupsOnly = false,
+): Promise<string> {
+  if (isUuid(input)) return input;
+  const matches = await collectRawQuery<ProjectLabelRow>(
+    client as any,
+    LIST_QUERY,
+    {
+      filter: {
+        name: { eqIgnoreCase: input },
+        ...(groupsOnly ? { isGroup: { eq: true } } : {}),
+      },
+      includeArchived: true,
+    },
+    "projectLabels",
+    Infinity,
+    row,
+  );
+  const eligible = groupsOnly ? matches.filter((label) => !label.retiredAt) : matches;
+  if (eligible.length === 0)
+    throw notFound(
+      `No project label matching '${input}'. Run 'linear project-label list --include-retired' to see the options.`,
+    );
+  const exact = eligible.filter((label) => label.name === input);
+  const finalists = exact.length ? exact : eligible;
+  if (finalists.length > 1)
+    throw ambiguous(`Multiple project labels named '${input}'; pass the project label id instead.`);
+  return finalists[0]!.id;
+}
+
+export async function getProjectLabel(
+  client: LinearClient,
+  input: string,
+  groupsOnly = false,
+): Promise<ProjectLabelDetail> {
+  const id = await resolveProjectLabelId(client, input, groupsOnly);
+  const response: any = await withRetry(() =>
+    (client as any).client.rawRequest(VIEW_QUERY, { id }),
+  );
+  const label = response.data?.projectLabel;
+  if (!label) throw notFound(`No project label matching '${input}'.`);
+  return { ...row(label), children: label.children?.nodes ?? [] };
+}
+
+function validateName(name: string | undefined): void {
+  if (name !== undefined && name.trim().length === 0)
+    throw usageError("Label name cannot be empty.");
+}
+
+function validateColor(color: string | undefined): void {
+  if (color !== undefined && !/^#[0-9a-f]{6}$/i.test(color))
+    throw usageError("Label color must be a six-digit hex value such as #5E6AD2.");
+}
+
+async function resolveParent(client: LinearClient, input: string): Promise<ProjectLabelDetail> {
+  const parent = await getProjectLabel(client, input, true);
+  if (!parent.isGroup) throw usageError(`Project label '${parent.name}' is not a label group.`);
+  if (parent.retiredAt) throw usageError(`Project label group '${parent.name}' is retired.`);
+  return parent;
+}
+
+export interface CreateOptions {
+  name: string;
+  color?: string;
+  description?: string;
+  group?: boolean;
+  parent?: string;
+}
+
+export async function createProjectLabel(client: LinearClient, opts: CreateOptions) {
+  validateName(opts.name);
+  validateColor(opts.color);
+  if (opts.group && opts.parent)
+    throw usageError("A project label group cannot itself belong to another group.");
+  const input: Record<string, unknown> = { name: opts.name.trim() };
+  if (opts.color !== undefined) input.color = opts.color;
+  if (opts.description !== undefined) input.description = opts.description;
+  if (opts.group) input.isGroup = true;
+  if (opts.parent) input.parentId = (await resolveParent(client, opts.parent)).id;
+  return unwrapMutation(
+    withRetry(() => client.createProjectLabel(input as any)),
+    "projectLabel",
+    "Project label creation",
+  );
+}
+
+export interface UpdateOptions {
+  name?: string;
+  color?: string;
+  description?: string;
+  parent?: string;
+  clearParent?: boolean;
+}
+
+export async function updateProjectLabel(client: LinearClient, input: string, opts: UpdateOptions) {
+  validateName(opts.name);
+  validateColor(opts.color);
+  if (opts.parent && opts.clearParent)
+    throw usageError("Pass either --parent or --clear-parent, not both.");
+  const current = await getProjectLabel(client, input);
+  if (current.isGroup && opts.parent)
+    throw usageError("A project label group cannot itself belong to another group.");
+  const update: Record<string, unknown> = {};
+  if (opts.name !== undefined) update.name = opts.name.trim();
+  if (opts.color !== undefined) update.color = opts.color;
+  if (opts.description !== undefined) update.description = opts.description;
+  if (opts.parent) update.parentId = (await resolveParent(client, opts.parent)).id;
+  if (opts.clearParent) update.parentId = null;
+  if (Object.keys(update).length === 0)
+    throw usageError(
+      "Nothing to update; pass at least one of --name, --color, --description, --parent, --clear-parent.",
+    );
+  return unwrapMutation(
+    withRetry(() => client.updateProjectLabel(current.id, update as any)),
+    "projectLabel",
+    "Project label update",
+  );
+}
+
+export async function retireProjectLabel(client: LinearClient, input: string) {
+  const label = await getProjectLabel(client, input);
+  if (label.retiredAt) throw usageError(`Project label '${label.name}' is already retired.`);
+  return unwrapMutation(
+    withRetry(() => client.projectLabelRetire(label.id)),
+    "projectLabel",
+    "Project label retirement",
+  );
+}
+
+export async function restoreProjectLabel(client: LinearClient, input: string) {
+  const label = await getProjectLabel(client, input);
+  if (!label.retiredAt) throw usageError(`Project label '${label.name}' is not retired.`);
+  return unwrapMutation(
+    withRetry(() => client.projectLabelRestore(label.id)),
+    "projectLabel",
+    "Project label restoration",
+  );
+}
+
+export async function deleteProjectLabel(client: LinearClient, input: string) {
+  const label = await getProjectLabel(client, input);
+  await assertMutation(
+    withRetry(() => client.deleteProjectLabel(label.id)),
+    "Project label deletion",
+  );
+  return label;
+}

package/src/services/project-status.ts

@@ -0,0 +1,225 @@
+/** Workspace project-status definitions. */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { ambiguous, notFound, usageError } from "../lib/errors.js";
+import { assertMutation, unwrapMutation } from "../lib/mutation.js";
+import { collect, inheritPaginationMetadata, pageSize } from "../lib/pagination.js";
+import { isUuid } from "../lib/resolve.js";
+import { shape } from "../lib/shape.js";
+
+export const PROJECT_STATUS_TYPES = [
+  "backlog",
+  "planned",
+  "started",
+  "paused",
+  "completed",
+  "canceled",
+] as const;
+export type ProjectStatusType = (typeof PROJECT_STATUS_TYPES)[number];
+
+export interface ProjectStatusRow {
+  id: string;
+  name: string;
+  description: string | null;
+  color: string;
+  position: number;
+  type: string;
+  indefinite: boolean;
+  archivedAt: string | null;
+}
+
+export const PROJECT_STATUS_ROW_SHAPE = shape<ProjectStatusRow>({
+  id: "string",
+  name: "string",
+  description: "string|null",
+  color: "string",
+  position: "number",
+  type: "string",
+  indefinite: "boolean",
+  archivedAt: "string|null",
+});
+
+export interface ProjectStatusDetail extends ProjectStatusRow {
+  createdAt: string;
+  updatedAt: string;
+}
+
+export const PROJECT_STATUS_DETAIL_SHAPE = shape<ProjectStatusDetail>({
+  ...PROJECT_STATUS_ROW_SHAPE,
+  createdAt: "string",
+  updatedAt: "string",
+});
+
+export async function listProjectStatuses(
+  client: LinearClient,
+  limit: number,
+  includeArchived = false,
+): Promise<ProjectStatusRow[]> {
+  const conn = await withRetry(() =>
+    client.projectStatuses({ first: pageSize(limit), includeArchived }),
+  );
+  const nodes = await collect(conn as any, limit);
+  return inheritPaginationMetadata(nodes.map(toRow).sort(compareStatuses), nodes);
+}
+
+export async function getProjectStatusDetail(
+  client: LinearClient,
+  input: string,
+): Promise<ProjectStatusDetail> {
+  const id = await resolveProjectStatusId(client, input, { includeArchived: true });
+  const status = await withRetry(() => client.projectStatus(id));
+  return {
+    ...toRow(status),
+    createdAt: toIso(status.createdAt),
+    updatedAt: toIso(status.updatedAt),
+  };
+}
+
+export interface ProjectStatusInput {
+  name?: string;
+  description?: string;
+  color?: string;
+  position?: number;
+  type?: string;
+  indefinite?: boolean;
+}
+
+export async function createProjectStatus(client: LinearClient, opts: ProjectStatusInput) {
+  const input = buildInput(opts, true);
+  return unwrapMutation(
+    withRetry(() => client.createProjectStatus(input as any)),
+    "status",
+    "Project status creation",
+  );
+}
+
+export async function updateProjectStatus(
+  client: LinearClient,
+  input: string,
+  opts: ProjectStatusInput,
+) {
+  const id = await resolveProjectStatusId(client, input);
+  const update = buildInput(opts, false);
+  if (Object.keys(update).length === 0)
+    throw usageError("Nothing to update; pass at least one project-status field.");
+  return unwrapMutation(
+    withRetry(() => client.updateProjectStatus(id, update as any)),
+    "status",
+    "Project status update",
+  );
+}
+
+export async function archiveProjectStatus(client: LinearClient, input: string) {
+  const id = await resolveProjectStatusId(client, input);
+  const status = await withRetry(() => client.projectStatus(id));
+  await assertMutation(
+    withRetry(() => client.archiveProjectStatus(id)),
+    "Project status archive",
+  );
+  return status;
+}
+
+export async function unarchiveProjectStatus(client: LinearClient, input: string) {
+  const id = await resolveProjectStatusId(client, input, { includeArchived: true });
+  const status = await withRetry(() => client.projectStatus(id));
+  await assertMutation(
+    withRetry(() => client.unarchiveProjectStatus(id)),
+    "Project status unarchive",
+  );
+  return status;
+}
+
+/** Shared by project-status commands and project create/update --state. */
+export async function resolveProjectStatusId(
+  client: LinearClient,
+  input: string,
+  opts: { includeArchived?: boolean; allowType?: boolean } = {},
+): Promise<string> {
+  if (isUuid(input)) return input;
+  const conn = await withRetry(() =>
+    client.projectStatuses({ first: 250, includeArchived: opts.includeArchived === true }),
+  );
+  const statuses = (await collect(conn as any, Infinity)) as Array<{
+    id: string;
+    name: string;
+    type: string;
+    archivedAt?: unknown;
+  }>;
+  const exact = statuses.filter((s) => s.name === input);
+  const insensitive = statuses.filter((s) => s.name.toLowerCase() === input.toLowerCase());
+  let matches = exact.length ? exact : insensitive;
+  if (matches.length === 0 && opts.allowType) {
+    matches = statuses.filter((s) => s.type.toLowerCase() === input.toLowerCase());
+  }
+  if (matches.length === 0)
+    throw notFound(
+      `No project status matching '${input}'. Run 'linear project-status list${opts.includeArchived ? " --include-archived" : ""}' to see the options.`,
+    );
+  if (matches.length > 1)
+    throw ambiguous(
+      `Multiple project statuses match '${input}': ${matches.map((s) => `${s.name} (${s.id})`).join(", ")}. Pass the project status id instead.`,
+    );
+  return matches[0]!.id;
+}
+
+function buildInput(opts: ProjectStatusInput, create: boolean): Record<string, unknown> {
+  const input: Record<string, unknown> = {};
+  if (opts.name !== undefined) {
+    if (!opts.name.trim()) throw usageError("Project status name must not be empty.");
+    input.name = opts.name;
+  }
+  if (opts.description !== undefined) input.description = opts.description;
+  if (opts.color !== undefined) {
+    if (!/^#[0-9a-f]{6}$/i.test(opts.color))
+      throw usageError(
+        `Invalid color '${opts.color}'. Expected a six-digit hex color such as #5E6AD2.`,
+      );
+    input.color = opts.color;
+  }
+  if (opts.position !== undefined) {
+    if (!Number.isFinite(opts.position) || opts.position < 0)
+      throw usageError("Project status position must be a non-negative number.");
+    input.position = opts.position;
+  }
+  if (opts.type !== undefined) {
+    if (!PROJECT_STATUS_TYPES.includes(opts.type as ProjectStatusType))
+      throw usageError(
+        `Invalid project status type '${opts.type}'. Valid: ${PROJECT_STATUS_TYPES.join(", ")}.`,
+      );
+    input.type = opts.type;
+  }
+  if (opts.indefinite !== undefined) input.indefinite = opts.indefinite;
+  if (create) {
+    const missing = ["name", "color", "position", "type"].filter((key) => !(key in input));
+    if (missing.length)
+      throw usageError(
+        `Missing required project-status fields: ${missing.map((k) => `--${k}`).join(", ")}.`,
+      );
+  }
+  return input;
+}
+
+function toRow(status: any): ProjectStatusRow {
+  return {
+    id: status.id,
+    name: status.name,
+    description: status.description ?? null,
+    color: status.color,
+    position: status.position,
+    type: status.type,
+    indefinite: status.indefinite === true,
+    archivedAt: status.archivedAt ? toIso(status.archivedAt) : null,
+  };
+}
+
+function toIso(value: Date | string): string {
+  return value instanceof Date ? value.toISOString() : String(value);
+}
+
+function compareStatuses(a: ProjectStatusRow, b: ProjectStatusRow): number {
+  const type =
+    PROJECT_STATUS_TYPES.indexOf(a.type as ProjectStatusType) -
+    PROJECT_STATUS_TYPES.indexOf(b.type as ProjectStatusType);
+  return type || a.position - b.position || a.name.localeCompare(b.name);
+}