linear-sdk-cli 0.5.2 → 0.6.0

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);
+}

package/src/services/project.ts

@@ -23,6 +23,7 @@ import {
   resolveProjectLabelIds,
   isUuid,
 } from "../lib/resolve.js";
+import { resolveProjectStatusId } from "./project-status.js";
 
 export interface ProjectRow {
   id: string;
@@ -291,7 +292,8 @@ export async function createProject(
   const input: Record<string, any> = { name: opts.name, teamIds };
   if (opts.description !== undefined) input.description = opts.description;
   if (opts.content !== undefined) input.content = opts.content;
-  if (opts.state) input.statusId = await resolveStatusId(client, opts.state);
+  if (opts.state)
+    input.statusId = await resolveProjectStatusId(client, opts.state, { allowType: true });
   if (opts.lead) input.leadId = await resolveUserId(client, opts.lead);
   if (opts.startDate) input.startDate = opts.startDate;
   if (opts.targetDate) input.targetDate = opts.targetDate;
@@ -335,7 +337,8 @@ export async function updateProject(client: LinearClient, idArg: string, opts: U
   if (opts.content !== undefined) input.content = opts.content;
   if (opts.team?.length) input.teamIds = await resolveTeamIds(client, opts.team, undefined);
   if (opts.lead) input.leadId = await resolveUserId(client, opts.lead);
-  if (opts.state) input.statusId = await resolveStatusId(client, opts.state);
+  if (opts.state)
+    input.statusId = await resolveProjectStatusId(client, opts.state, { allowType: true });
   if (opts.startDate) input.startDate = opts.startDate;
   if (opts.targetDate) input.targetDate = opts.targetDate;
   if (opts.priority !== undefined) input.priority = resolvePriority(opts.priority);
@@ -480,26 +483,3 @@ async function resolveTeamIds(
   }
   return ids;
 }
-
-/** Resolve a project status (by name or type) to a status id. */
-async function resolveStatusId(client: LinearClient, input: string): Promise<string> {
-  if (isUuid(input)) return input;
-  const conn = await withRetry(() => client.projectStatuses({ first: 250 }));
-  const statuses = (await collect(conn as any, Infinity)) as Array<{
-    id: string;
-    name: string;
-    type: string;
-  }>;
-  const lower = input.toLowerCase();
-  const byName = statuses.filter((s) => s.name.toLowerCase() === lower);
-  const matches = byName.length ? byName : statuses.filter((s) => s.type.toLowerCase() === lower);
-  if (matches.length === 0)
-    throw notFound(
-      `No project status '${input}'. Available: ${statuses.map((s) => s.name).join(", ")}`,
-    );
-  if (matches.length > 1)
-    throw ambiguous(
-      `Multiple project statuses match '${input}': ${matches.map((s) => s.name).join(", ")}`,
-    );
-  return matches[0]!.id;
-}