From 80a2c57afb82ed296e3478d74c48d9b668d39486 Mon Sep 17 00:00:00 2001
From: Peter Schilling <code@schpet.com>
Date: Mon, 13 Jul 2026 21:20:33 -0700
Subject: [PATCH] feat(project): add --label to project update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a repeatable `--label` flag to `linear project update`, mirroring the
existing `project create --label`: names resolve case-insensitively and an
unknown label raises NotFoundError (no auto-create).

The flag uses replace semantics — the supplied labels become the project's
complete label set — consistent with `project update --team` and
`issue update --label`. Empty/whitespace labels are rejected up front, and
case-insensitive duplicates collapse to a single ID.

The project-label lookup is extracted from project-create into a shared
getProjectLabelIdByName helper in utils/linear.ts so create and update stay
identical.

This reshapes the update half of #226 to the repo's existing label
conventions; the create half of #226 already shipped in #216, and the PR's
auto-create/interactive-create behavior is intentionally dropped.

Co-authored-by: KinomotoMio <200703522+KinomotoMio@users.noreply.github.com>
---
 skills/linear-cli/references/project.md       |   3 +-
 src/commands/project/project-create.ts        |  22 +-
 src/commands/project/project-update.ts        |  44 ++-
 src/utils/linear.ts                           |  20 ++
 .../__snapshots__/project-update.test.ts.snap |  10 +
 test/commands/project/project-create.test.ts  |   6 +-
 test/commands/project/project-update.test.ts  | 332 ++++++++++++++++++
 7 files changed, 410 insertions(+), 27 deletions(-)

diff --git a/skills/linear-cli/references/project.md b/skills/linear-cli/references/project.md
index 4dad294e..7ac54ec6 100644
--- a/skills/linear-cli/references/project.md
+++ b/skills/linear-cli/references/project.md
@@ -125,7 +125,8 @@ Options:
   -l, --lead              <lead>         - Project lead (username, email, or @me)                                             
   --start-date            <startDate>    - Start date (YYYY-MM-DD)                                                            
   --target-date           <targetDate>   - Target date (YYYY-MM-DD)                                                           
-  -t, --team              <team>         - Team key (can be repeated for multiple teams)
+  -t, --team              <team>         - Team key (can be repeated for multiple teams)                                      
+  --label                 <label>        - Replace the project's labels. May be repeated to set multiple labels.
 ```
 
 ### view
diff --git a/src/commands/project/project-create.ts b/src/commands/project/project-create.ts
index 5e650381..a376f8a8 100644
--- a/src/commands/project/project-create.ts
+++ b/src/commands/project/project-create.ts
@@ -6,6 +6,7 @@ import { getGraphQLClient } from "../../utils/graphql.ts"
 import type { GraphQLClient } from "graphql-request"
 import {
   getAllTeams,
+  getProjectLabelIdByName,
   getTeamIdByKey,
   getTeamKey,
   lookupUserId,
@@ -56,17 +57,6 @@ const AddProjectToInitiative = gql(`
   }
 `)
 
-const GetProjectLabelIdByName = gql(`
-  query GetProjectLabelIdByNameForCreate($name: String!) {
-    projectLabels(filter: { name: { eqIgnoreCase: $name } }) {
-      nodes {
-        id
-        name
-      }
-    }
-  }
-`)
-
 const PRIORITY_MAPPING: Record<string, number> = {
   "none": 0,
   "urgent": 1,
@@ -168,14 +158,6 @@ export async function resolveProjectContent(
   }
 }
 
-async function lookupProjectLabelId(
-  client: GraphQLClient,
-  label: string,
-): Promise<string | undefined> {
-  const result = await client.request(GetProjectLabelIdByName, { name: label })
-  return result.projectLabels?.nodes[0]?.id
-}
-
 export const createCommand = new Command()
   .name("create")
   .description("Create a new Linear project")
@@ -459,7 +441,7 @@ export const createCommand = new Command()
 
         const labelIds: string[] = []
         for (const label of labels) {
-          const labelId = await lookupProjectLabelId(client, label)
+          const labelId = await getProjectLabelIdByName(label)
           if (!labelId) {
             throw new NotFoundError("Project label", label)
           }
diff --git a/src/commands/project/project-update.ts b/src/commands/project/project-update.ts
index 697a9ab4..209ff695 100644
--- a/src/commands/project/project-update.ts
+++ b/src/commands/project/project-update.ts
@@ -1,7 +1,9 @@
 import { Command } from "@cliffy/command"
 import { gql } from "../../__codegen__/gql.ts"
+import type { ProjectUpdateInput } from "../../__codegen__/graphql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import {
+  getProjectLabelIdByName,
   getTeamIdByKey,
   lookupUserId,
   resolveProjectId,
@@ -81,6 +83,11 @@ export const updateCommand = new Command()
     "Team key (can be repeated for multiple teams)",
     { collect: true },
   )
+  .option(
+    "--label <label:string>",
+    "Replace the project's labels. May be repeated to set multiple labels.",
+    { collect: true },
+  )
   .action(
     async (
       {
@@ -92,6 +99,7 @@ export const updateCommand = new Command()
         startDate,
         targetDate,
         team: teams,
+        label: labels,
       },
       projectId,
     ) => {
@@ -102,17 +110,28 @@ export const updateCommand = new Command()
       try {
         if (
           !name && description == null && descriptionFile == null && !status &&
-          !lead && !startDate && !targetDate && (!teams || teams.length === 0)
+          !lead && !startDate && !targetDate &&
+          (!teams || teams.length === 0) && (!labels || labels.length === 0)
         ) {
           throw new ValidationError(
             "At least one update option must be provided",
             {
               suggestion:
-                "Use --name, --description, --description-file, --status, --lead, --start-date, --target-date, or --team",
+                "Use --name, --description, --description-file, --status, --lead, --start-date, --target-date, --team, or --label",
             },
           )
         }
 
+        if (labels) {
+          for (const label of labels) {
+            if (label.trim() === "") {
+              throw new ValidationError("Project label cannot be empty", {
+                suggestion: 'Provide a label name, e.g. --label "My Label".',
+              })
+            }
+          }
+        }
+
         const resolvedDescription = await resolveProjectDescription(
           description,
           descriptionFile,
@@ -130,7 +149,7 @@ export const updateCommand = new Command()
         const client = getGraphQLClient()
         const resolvedId = await resolveProjectId(projectId)
 
-        const input: Record<string, unknown> = {}
+        const input: ProjectUpdateInput = {}
 
         if (name) input.name = name
         if (resolvedDescription != null) input.description = resolvedDescription
@@ -181,6 +200,25 @@ export const updateCommand = new Command()
           input.teamIds = teamIds
         }
 
+        if (labels && labels.length > 0) {
+          // Replace the project's labels with exactly the resolved set,
+          // matching `project update --team` and `issue update --label`.
+          const labelIds: string[] = []
+          const seen = new Set<string>()
+          for (const label of labels) {
+            const labelId = await getProjectLabelIdByName(label)
+            if (!labelId) {
+              spinner?.stop()
+              throw new NotFoundError("Project label", label)
+            }
+            if (!seen.has(labelId)) {
+              seen.add(labelId)
+              labelIds.push(labelId)
+            }
+          }
+          input.labelIds = labelIds
+        }
+
         const result = await client.request(UpdateProject, {
           id: resolvedId,
           input,
diff --git a/src/utils/linear.ts b/src/utils/linear.ts
index 665b3f4b..81f1350b 100644
--- a/src/utils/linear.ts
+++ b/src/utils/linear.ts
@@ -1460,6 +1460,26 @@ export async function getIssueLabelIdByNameForTeam(
   return data.issueLabels?.nodes[0]?.id
 }
 
+export async function getProjectLabelIdByName(
+  name: string,
+): Promise<string | undefined> {
+  const client = getGraphQLClient()
+  const query = gql(/* GraphQL */ `
+    query GetProjectLabelIdByName($name: String!) {
+      projectLabels(
+        filter: { name: { eqIgnoreCase: $name }, isGroup: { eq: false } }
+      ) {
+        nodes {
+          id
+          name
+        }
+      }
+    }
+  `)
+  const data = await client.request(query, { name })
+  return data.projectLabels?.nodes[0]?.id
+}
+
 export async function getIssueLabelOptionsByNameForTeam(
   name: string,
   teamKey: string,
diff --git a/test/commands/project/__snapshots__/project-update.test.ts.snap b/test/commands/project/__snapshots__/project-update.test.ts.snap
index 409243f7..4f2f3aa5 100644
--- a/test/commands/project/__snapshots__/project-update.test.ts.snap
+++ b/test/commands/project/__snapshots__/project-update.test.ts.snap
@@ -21,6 +21,7 @@ Options:
   --start-date            <startDate>    - Start date (YYYY-MM-DD)                                                     
   --target-date           <targetDate>   - Target date (YYYY-MM-DD)                                                    
   -t, --team              <team>         - Team key (can be repeated for multiple teams)                               
+  --label                 <label>        - Replace the project's labels. May be repeated to set multiple labels.       
 
 "
 stderr:
@@ -53,3 +54,12 @@ https://linear.app/test/project/proj-status
 stderr:
 ""
 `;
+
+snapshot[`Project Update Command - Replace Labels 1`] = `
+stdout:
+"✓ Updated project: Test Project
+https://linear.app/test/project/proj-labels
+"
+stderr:
+""
+`;
diff --git a/test/commands/project/project-create.test.ts b/test/commands/project/project-create.test.ts
index 22593616..adb47803 100644
--- a/test/commands/project/project-create.test.ts
+++ b/test/commands/project/project-create.test.ts
@@ -212,7 +212,7 @@ await cliffySnapshotTest({
         },
       },
       {
-        queryName: "GetProjectLabelIdByNameForCreate",
+        queryName: "GetProjectLabelIdByName",
         variables: { name: "Frontend" },
         response: {
           data: {
@@ -223,7 +223,7 @@ await cliffySnapshotTest({
         },
       },
       {
-        queryName: "GetProjectLabelIdByNameForCreate",
+        queryName: "GetProjectLabelIdByName",
         variables: { name: "Backend" },
         response: {
           data: {
@@ -462,7 +462,7 @@ Deno.test("Project Create Command - rejects an unknown project label", async ()
       response: { data: { teams: { nodes: [{ id: "team-eng-123" }] } } },
     },
     {
-      queryName: "GetProjectLabelIdByNameForCreate",
+      queryName: "GetProjectLabelIdByName",
       variables: { name: "Nonexistent" },
       response: { data: { projectLabels: { nodes: [] } } },
     },
diff --git a/test/commands/project/project-update.test.ts b/test/commands/project/project-update.test.ts
index d23a74de..6dfe7049 100644
--- a/test/commands/project/project-update.test.ts
+++ b/test/commands/project/project-update.test.ts
@@ -1,4 +1,6 @@
 import { snapshotTest as cliffySnapshotTest } from "@cliffy/testing"
+import { assertEquals } from "@std/assert"
+import { stub } from "@std/testing/mock"
 import { updateCommand } from "../../../src/commands/project/project-update.ts"
 import { commonDenoArgs } from "../../utils/test-helpers.ts"
 import { MockLinearServer } from "../../utils/mock_linear_server.ts"
@@ -171,3 +173,333 @@ await cliffySnapshotTest({
     }
   },
 })
+
+// Test project update - replace labels.
+// The UpdateProject mock pins `input.labelIds` to exactly the resolved set, so
+// an additive implementation (or a wrong set) would fail to match the mock.
+await cliffySnapshotTest({
+  name: "Project Update Command - Replace Labels",
+  meta: import.meta,
+  colors: false,
+  args: [
+    "550e8400-e29b-41d4-a716-446655440003",
+    "--label",
+    "Frontend",
+    "--label",
+    "Backend",
+  ],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const server = new MockLinearServer([
+      {
+        queryName: "GetProjectLabelIdByName",
+        variables: { name: "Frontend" },
+        response: {
+          data: {
+            projectLabels: {
+              nodes: [{ id: "project-label-frontend", name: "Frontend" }],
+            },
+          },
+        },
+      },
+      {
+        queryName: "GetProjectLabelIdByName",
+        variables: { name: "Backend" },
+        response: {
+          data: {
+            projectLabels: {
+              nodes: [{ id: "project-label-backend", name: "Backend" }],
+            },
+          },
+        },
+      },
+      {
+        queryName: "UpdateProject",
+        variables: {
+          id: "550e8400-e29b-41d4-a716-446655440003",
+          input: {
+            labelIds: ["project-label-frontend", "project-label-backend"],
+          },
+        },
+        response: {
+          data: {
+            projectUpdate: {
+              success: true,
+              project: {
+                id: "550e8400-e29b-41d4-a716-446655440003",
+                slugId: "proj-labels",
+                name: "Test Project",
+                description: null,
+                url: "https://linear.app/test/project/proj-labels",
+                updatedAt: "2024-01-20T15:30:00Z",
+              },
+            },
+          },
+        },
+      },
+    ])
+
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+
+      await updateCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
+
+// Case-insensitive duplicate label names collapse to a single ID.
+Deno.test("Project Update Command - dedups case-insensitive labels", async () => {
+  const server = new MockLinearServer([
+    {
+      // No `variables` → matches both "Frontend" and "frontend" lookups.
+      queryName: "GetProjectLabelIdByName",
+      response: {
+        data: {
+          projectLabels: {
+            nodes: [{ id: "project-label-frontend", name: "Frontend" }],
+          },
+        },
+      },
+    },
+    {
+      queryName: "UpdateProject",
+      variables: {
+        id: "550e8400-e29b-41d4-a716-446655440004",
+        input: { labelIds: ["project-label-frontend"] },
+      },
+      response: {
+        data: {
+          projectUpdate: {
+            success: true,
+            project: {
+              id: "550e8400-e29b-41d4-a716-446655440004",
+              slugId: "proj-dedup",
+              name: "Test Project",
+              description: null,
+              url: "https://linear.app/test/project/proj-dedup",
+              updatedAt: "2024-01-20T15:30:00Z",
+            },
+          },
+        },
+      },
+    },
+  ])
+
+  const logs: string[] = []
+  const logStub = stub(console, "log", (...args: unknown[]) => {
+    logs.push(args.map(String).join(" "))
+  })
+
+  try {
+    await server.start()
+    Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+    Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+    await updateCommand.parse([
+      "550e8400-e29b-41d4-a716-446655440004",
+      "--label",
+      "Frontend",
+      "--label",
+      "frontend",
+    ])
+  } finally {
+    logStub.restore()
+    await server.stop()
+    Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+    Deno.env.delete("LINEAR_API_KEY")
+  }
+
+  // Success message only appears if the UpdateProject mock matched the deduped set.
+  assertEquals(logs.some((l) => l.includes("✓ Updated project")), true)
+})
+
+// An unknown --label fails before the update mutation (no UpdateProject mock is
+// configured, so a mutation attempt would surface a different error).
+Deno.test("Project Update Command - rejects an unknown label before mutating", async () => {
+  const server = new MockLinearServer([
+    {
+      queryName: "GetProjectLabelIdByName",
+      variables: { name: "Existing" },
+      response: {
+        data: {
+          projectLabels: {
+            nodes: [{ id: "project-label-existing", name: "Existing" }],
+          },
+        },
+      },
+    },
+    {
+      queryName: "GetProjectLabelIdByName",
+      variables: { name: "Missing" },
+      response: { data: { projectLabels: { nodes: [] } } },
+    },
+  ])
+
+  const errorLogs: string[] = []
+  const errorStub = stub(console, "error", (...args: unknown[]) => {
+    errorLogs.push(args.map(String).join(" "))
+  })
+  const exitStub = stub(Deno, "exit", (_code?: number) => {
+    throw new Error("EXIT")
+  })
+
+  let exited = false
+  try {
+    await server.start()
+    Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+    Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+    await updateCommand.parse([
+      "550e8400-e29b-41d4-a716-446655440005",
+      "--label",
+      "Existing",
+      "--label",
+      "Missing",
+    ])
+  } catch (e) {
+    if (!(e instanceof Error) || e.message !== "EXIT") throw e
+    exited = true
+  } finally {
+    errorStub.restore()
+    exitStub.restore()
+    await server.stop()
+    Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+    Deno.env.delete("LINEAR_API_KEY")
+  }
+
+  assertEquals(exited, true)
+  assertEquals(
+    errorLogs.some((l) => l.includes("Project label not found: Missing")),
+    true,
+  )
+})
+
+// An empty/whitespace label is rejected as a validation error, not treated as
+// a request to clear labels.
+Deno.test("Project Update Command - rejects an empty label", async () => {
+  const errorLogs: string[] = []
+  const errorStub = stub(console, "error", (...args: unknown[]) => {
+    errorLogs.push(args.map(String).join(" "))
+  })
+  const exitStub = stub(Deno, "exit", (_code?: number) => {
+    throw new Error("EXIT")
+  })
+
+  let exited = false
+  try {
+    await updateCommand.parse([
+      "550e8400-e29b-41d4-a716-446655440006",
+      "--label",
+      "   ",
+    ])
+  } catch (e) {
+    if (!(e instanceof Error) || e.message !== "EXIT") throw e
+    exited = true
+  } finally {
+    errorStub.restore()
+    exitStub.restore()
+  }
+
+  assertEquals(exited, true)
+  assertEquals(
+    errorLogs.some((l) => l.includes("Project label cannot be empty")),
+    true,
+  )
+})
+
+// --label alone satisfies the "at least one update option" requirement.
+Deno.test("Project Update Command - label alone is a valid update", async () => {
+  const server = new MockLinearServer([
+    {
+      queryName: "GetProjectLabelIdByName",
+      variables: { name: "Frontend" },
+      response: {
+        data: {
+          projectLabels: {
+            nodes: [{ id: "project-label-frontend", name: "Frontend" }],
+          },
+        },
+      },
+    },
+    {
+      queryName: "UpdateProject",
+      variables: {
+        id: "550e8400-e29b-41d4-a716-446655440007",
+        input: { labelIds: ["project-label-frontend"] },
+      },
+      response: {
+        data: {
+          projectUpdate: {
+            success: true,
+            project: {
+              id: "550e8400-e29b-41d4-a716-446655440007",
+              slugId: "proj-label-only",
+              name: "Test Project",
+              description: null,
+              url: "https://linear.app/test/project/proj-label-only",
+              updatedAt: "2024-01-20T15:30:00Z",
+            },
+          },
+        },
+      },
+    },
+  ])
+
+  const logs: string[] = []
+  const logStub = stub(console, "log", (...args: unknown[]) => {
+    logs.push(args.map(String).join(" "))
+  })
+
+  try {
+    await server.start()
+    Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+    Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+    await updateCommand.parse([
+      "550e8400-e29b-41d4-a716-446655440007",
+      "--label",
+      "Frontend",
+    ])
+  } finally {
+    logStub.restore()
+    await server.stop()
+    Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+    Deno.env.delete("LINEAR_API_KEY")
+  }
+
+  assertEquals(logs.some((l) => l.includes("✓ Updated project")), true)
+})
+
+// No options at all still fails, and the suggestion now mentions --label.
+Deno.test("Project Update Command - requires at least one option", async () => {
+  const errorLogs: string[] = []
+  const errorStub = stub(console, "error", (...args: unknown[]) => {
+    errorLogs.push(args.map(String).join(" "))
+  })
+  const exitStub = stub(Deno, "exit", (_code?: number) => {
+    throw new Error("EXIT")
+  })
+
+  let exited = false
+  try {
+    await updateCommand.parse(["550e8400-e29b-41d4-a716-446655440008"])
+  } catch (e) {
+    if (!(e instanceof Error) || e.message !== "EXIT") throw e
+    exited = true
+  } finally {
+    errorStub.restore()
+    exitStub.restore()
+  }
+
+  assertEquals(exited, true)
+  assertEquals(
+    errorLogs.some((l) =>
+      l.includes("At least one update option must be provided")
+    ),
+    true,
+  )
+  assertEquals(errorLogs.some((l) => l.includes("--label")), true)
+})