feat(labels): add issue label CRUD commands

Refs DBL-191

Author: doublerebel

graphql/mutations/labels.graphql

@@ -0,0 +1,28 @@
+# ------------------------------------------------------------
+# GraphQL mutations for Linear issue labels
+# ------------------------------------------------------------
+
+mutation CreateIssueLabel($input: IssueLabelCreateInput!) {
+  issueLabelCreate(input: $input) {
+    success
+    issueLabel {
+      ...LabelFields
+    }
+  }
+}
+
+mutation UpdateIssueLabel($id: String!, $input: IssueLabelUpdateInput!) {
+  issueLabelUpdate(id: $id, input: $input) {
+    success
+    issueLabel {
+      ...LabelFields
+    }
+  }
+}
+
+mutation DeleteIssueLabel($id: String!) {
+  issueLabelDelete(id: $id) {
+    success
+    entityId
+  }
+}

graphql/queries/labels.graphql

@@ -29,6 +29,12 @@ fragment ProjectLabelFields on ProjectLabel {
   description
 }
 
+query GetIssueLabel($id: String!) {
+  issueLabel(id: $id) {
+    ...LabelFields
+  }
+}
+
 # List labels in the workspace
 #
 # Fetches a list of issue labels with optional team filtering.

src/commands/labels.ts

@@ -7,12 +7,24 @@ import {
 import { invalidParameterError } from "../common/errors.js";
 import { handleCommand, outputSuccess, parseLimit } from "../common/output.js";
 import { type DomainMeta, formatDomainUsage } from "../common/usage.js";
+import type {
+  IssueLabelCreateInput,
+  IssueLabelUpdateInput,
+} from "../gql/graphql.js";
+import {
+  type LabelResolverScope,
+  resolveLabelId,
+} from "../resolvers/label-resolver.js";
 import { resolveTeamId } from "../resolvers/team-resolver.js";
 import {
+  createLabel,
+  deleteLabel,
+  getLabel,
   type LabelScope,
   type LabelType,
   listLabels,
   listProjectLabels,
+  updateLabel,
 } from "../services/label-service.js";
 
 interface ListLabelsOptions extends CommandOptions {
@@ -23,6 +35,23 @@ interface ListLabelsOptions extends CommandOptions {
   after?: string;
 }
 
+interface LabelLookupOptions extends CommandOptions {
+  team?: string;
+  scope?: string;
+}
+
+interface CreateLabelOptions extends CommandOptions {
+  team?: string;
+  color?: string;
+  description?: string;
+}
+
+interface UpdateLabelOptions extends LabelLookupOptions {
+  name?: string;
+  color?: string;
+  description?: string;
+}
+
 function parseLabelType(value?: string): LabelType {
   if (value === undefined || value === "issue" || value === "project") {
     return value ?? "issue";
@@ -42,16 +71,89 @@ function parseLabelScope(value?: string): LabelScope | undefined {
   );
 }
 
+function parseLabelColor(value?: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!/^#[0-9a-fA-F]{6}$/.test(value)) {
+    throw invalidParameterError("--color", "must be a hex color like #B45309");
+  }
+
+  return value;
+}
+
+async function resolveIssueLabelLookup(
+  command: Command,
+  label: string,
+  options: LabelLookupOptions,
+): Promise<{ ctx: ReturnType<typeof createContext>; labelId: string }> {
+  const ctx = createContext(getRootOpts(command));
+  const scope = parseLabelScope(options.scope);
+
+  if (scope === "team" && !options.team) {
+    throw invalidParameterError("--scope", "team scope requires --team");
+  }
+
+  if (scope === "workspace" && options.team) {
+    throw invalidParameterError(
+      "--team",
+      "cannot be used with --scope workspace",
+    );
+  }
+
+  const teamId = options.team
+    ? await resolveTeamId(ctx.sdk, options.team)
+    : undefined;
+  const labelId = await resolveLabelId(ctx.sdk, label, {
+    teamId,
+    scope: scope as LabelResolverScope | undefined,
+  });
+
+  return { ctx, labelId };
+}
+
+function buildUpdateInput(options: UpdateLabelOptions): IssueLabelUpdateInput {
+  const input: IssueLabelUpdateInput = {};
+  const color = parseLabelColor(options.color);
+
+  if (options.name) {
+    input.name = options.name;
+  }
+
+  if (color) {
+    input.color = color;
+  }
+
+  if (options.description) {
+    input.description = options.description;
+  }
+
+  if (Object.keys(input).length === 0) {
+    throw invalidParameterError(
+      "label update",
+      "at least one option must be provided",
+    );
+  }
+
+  return input;
+}
+
 export const LABELS_META: DomainMeta = {
   name: "labels",
   summary: "categorization tags for issues and projects",
   context: [
     "issue labels can exist at workspace level or be scoped to a specific",
-    "team. project labels are workspace-level only. use with issues",
-    "create/update --labels and projects create/update --labels.",
+    "team. project labels are workspace-level only. use labels list to",
+    "inspect existing labels, labels create/read/update/delete for issue",
+    "labels, and issues/projects create/update --labels to apply them.",
   ].join("\n"),
-  arguments: {},
+  arguments: { name: "label name or UUID" },
   seeAlso: [
+    "labels create <name>",
+    "labels read <label>",
+    "labels update <label>",
+    "labels delete <label>",
     "issues create --labels",
     "issues update --labels",
     "projects create --labels",
@@ -122,6 +224,119 @@ export function setupLabelsCommands(program: Command): void {
       }),
     );
 
+  labels
+    .command("create <name>")
+    .description("create an issue label")
+    .option("--team <team>", "create a team-scoped label (key, name, or UUID)")
+    .option("--color <hex>", "label color as a hex code (for example #B45309)")
+    .option("--description <text>", "label description")
+    .action(
+      handleCommand(async (...args: unknown[]) => {
+        const [name, options, command] = args as [
+          string,
+          CreateLabelOptions,
+          Command,
+        ];
+        const ctx = createContext(getRootOpts(command));
+
+        const input: IssueLabelCreateInput = { name };
+        const color = parseLabelColor(options.color);
+
+        if (options.team) {
+          input.teamId = await resolveTeamId(ctx.sdk, options.team);
+        }
+
+        if (color) {
+          input.color = color;
+        }
+
+        if (options.description) {
+          input.description = options.description;
+        }
+
+        outputSuccess(await createLabel(ctx.gql, input));
+      }),
+    );
+
+  labels
+    .command("read <label>")
+    .description("read an issue label")
+    .option(
+      "--team <team>",
+      "resolve a team-scoped label by team (key, name, or UUID)",
+    )
+    .option("--scope <scope>", "resolve within workspace or team scope")
+    .action(
+      handleCommand(async (...args: unknown[]) => {
+        const [label, options, command] = args as [
+          string,
+          LabelLookupOptions,
+          Command,
+        ];
+        const { ctx, labelId } = await resolveIssueLabelLookup(
+          command,
+          label,
+          options,
+        );
+
+        outputSuccess(await getLabel(ctx.gql, labelId));
+      }),
+    );
+
+  labels
+    .command("update <label>")
+    .description("update an issue label")
+    .option(
+      "--team <team>",
+      "resolve a team-scoped label by team (key, name, or UUID)",
+    )
+    .option("--scope <scope>", "resolve within workspace or team scope")
+    .option("--name <name>", "new label name")
+    .option("--color <hex>", "new label color as a hex code")
+    .option("--description <text>", "new label description")
+    .action(
+      handleCommand(async (...args: unknown[]) => {
+        const [label, options, command] = args as [
+          string,
+          UpdateLabelOptions,
+          Command,
+        ];
+        const input = buildUpdateInput(options);
+        const { ctx, labelId } = await resolveIssueLabelLookup(
+          command,
+          label,
+          options,
+        );
+
+        outputSuccess(await updateLabel(ctx.gql, labelId, input));
+      }),
+    );
+
+  labels
+    .command("delete <label>")
+    .description("delete an issue label")
+    .option(
+      "--team <team>",
+      "resolve a team-scoped label by team (key, name, or UUID)",
+    )
+    .option("--scope <scope>", "resolve within workspace or team scope")
+    .action(
+      handleCommand(async (...args: unknown[]) => {
+        const [label, options, command] = args as [
+          string,
+          LabelLookupOptions,
+          Command,
+        ];
+        const { ctx, labelId } = await resolveIssueLabelLookup(
+          command,
+          label,
+          options,
+        );
+
+        outputSuccess(await deleteLabel(ctx.gql, labelId));
+      }),
+    );
+
   labels
     .command("usage")
     .description("show detailed usage for labels")

src/resolvers/label-resolver.ts

@@ -2,14 +2,50 @@ import type { LinearSdkClient } from "../client/linear-client.js";
 import { notFoundError } from "../common/errors.js";
 import { isUuid } from "../common/identifier.js";
 
+export type LabelResolverScope = "workspace" | "team";
+
+export interface ResolveLabelOptions {
+  teamId?: string;
+  scope?: LabelResolverScope;
+}
+
+function buildLabelFilter(
+  nameOrId: string,
+  options: ResolveLabelOptions,
+): Record<string, unknown> {
+  if (options.scope === "workspace") {
+    return {
+      name: { eqIgnoreCase: nameOrId },
+      team: { null: true },
+    };
+  }
+
+  if (options.scope === "team" && options.teamId) {
+    return {
+      name: { eqIgnoreCase: nameOrId },
+      team: { id: { eq: options.teamId }, null: false },
+    };
+  }
+
+  if (options.teamId) {
+    return {
+      name: { eqIgnoreCase: nameOrId },
+      team: { id: { eq: options.teamId } },
+    };
+  }
+
+  return { name: { eqIgnoreCase: nameOrId } };
+}
+
 export async function resolveLabelId(
   client: LinearSdkClient,
   nameOrId: string,
+  options: ResolveLabelOptions = {},
 ): Promise<string> {
   if (isUuid(nameOrId)) return nameOrId;
 
   const result = await client.sdk.issueLabels({
-    filter: { name: { eqIgnoreCase: nameOrId } },
+    filter: buildLabelFilter(nameOrId, options),
     first: 1,
   });