nulab
diff --git a/‎AGENTS.md‎
Lines changed: 24 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎apps/cli/src/commands/api.test.ts‎
Lines changed: 18 additions & 24 deletions b/‎apps/cli/src/commands/api.test.ts‎
Lines changed: 18 additions & 24 deletions
diff --git a/‎apps/cli/src/commands/auth/login.test.ts‎
Lines changed: 15 additions & 23 deletions b/‎apps/cli/src/commands/auth/login.test.ts‎
Lines changed: 15 additions & 23 deletions
diff --git a/‎apps/cli/src/commands/auth/logout.test.ts‎
Lines changed: 5 additions & 8 deletions b/‎apps/cli/src/commands/auth/logout.test.ts‎
Lines changed: 5 additions & 8 deletions
diff --git a/‎apps/cli/src/commands/auth/refresh.test.ts‎
Lines changed: 7 additions & 12 deletions b/‎apps/cli/src/commands/auth/refresh.test.ts‎
Lines changed: 7 additions & 12 deletions
@@ -352,6 +352,30 @@ All list commands use the pattern: `consola.info("No <plural> found.")` (e.g., `
 - **Error path tests must exercise actual branching logic** — test explicit `throw`, `consola.error()`, or early `return` branches in the implementation. Do not write tests that only verify default error propagation (e.g., testing that an `await` without `try/catch` propagates a rejection is testing JavaScript, not the command).
 - **Extract shared mock setup into helper functions** — when multiple tests in the same `describe` need the same mock state, use a named setup function (e.g., `setupOAuthMocks()`).
 
+### What to test vs. what not to test
+
+Following [CLI Guidelines (clig.dev)](https://clig.dev/), command tests should focus on **CLI user experience** and **application-specific logic**, not on verifying that libraries work correctly.
+
+**DO test (application logic):**
+
+- Custom value resolution (`@me` → user ID, issue key → issue ID, status name → status ID)
+- Conditional display logic (`null` → `"Unassigned"`, `archived` → `"Archived"`)
+- API payload construction with correct defaults and field composition
+- Success/error message content and format (correct verb, resource identifier, URL)
+- Output routing (correct `consola` method: `consola.log` for data, `consola.success` for actions, `consola.info` for informational, `consola.error` for errors)
+- Confirmation prompts for destructive actions (`confirmOrExit` is called, `--yes` bypasses it)
+- Null/undefined resilience in API response display (optional chaining for nullable fields)
+
+**DO NOT test (library/framework responsibility):**
+
+- citty/Commander option parsing (e.g., `--keyword "x"` → `keyword: "x"`)
+- `splitArg` / `collect` / `collectNum` array collection behavior
+- Boolean flag parsing (`--archived` → `true`)
+- Simple option forwarding where the handler passes the parsed value to the API unchanged
+- Default error propagation through `await` without `try/catch` (this tests JavaScript, not the command)
+
+**Guiding principle:** If removing the test wouldn't reduce confidence in _your own code_, the test is verifying the library, not the application.
+
 ## Code Conventions (enforced by oxlint)
 
 - **Named exports only** — no default exports (`import/no-default-export`)
 
@@ -1,27 +1,28 @@
 import { describe, expect, it, vi } from "vitest";
-import { expectStdoutContaining } from "@repo/test-utils";
-
-const mockClient = {
+import {
+  expectStdoutContaining,
+  mockGetClient,
+  parseCommand,
+  setupCommandTest,
+} from "@repo/test-utils";
+
+const { mockClient, host } = setupCommandTest({
   get: vi.fn(),
   post: vi.fn(),
   put: vi.fn(),
   patch: vi.fn(),
   delete: vi.fn(),
-};
-
-vi.mock("@repo/backlog-utils", () => ({
-  getClient: vi.fn(() => Promise.resolve({ client: mockClient, host: "example.backlog.com" })),
-}));
+});
 
+vi.mock("@repo/backlog-utils", () => mockGetClient(mockClient, host));
 vi.mock("consola", () => import("@repo/test-utils/mock-consola"));
 
 describe("api", () => {
   it("makes GET request by default", async () => {
     mockClient.get.mockResolvedValue({ id: 1, name: "test" });
 
     await expectStdoutContaining(async () => {
-      const { default: api } = await import("./api");
-      await api.parseAsync(["/users/myself"], { from: "user" });
+      await parseCommand(() => import("./api"), ["/users/myself"]);
 
       expect(mockClient.get).toHaveBeenCalledWith("/users/myself", {});
     }, '"name"');
@@ -32,8 +33,7 @@ describe("api", () => {
 
     const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 
-    const { default: api } = await import("./api");
-    await api.parseAsync(["/projects"], { from: "user" });
+    await parseCommand(() => import("./api"), ["/projects"]);
 
     expect(mockClient.get).toHaveBeenCalledWith("/projects", {});
     writeSpy.mockRestore();
@@ -44,8 +44,7 @@ describe("api", () => {
 
     const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 
-    const { default: api } = await import("./api");
-    await api.parseAsync(["/api/v2/space"], { from: "user" });
+    await parseCommand(() => import("./api"), ["/api/v2/space"]);
 
     expect(mockClient.get).toHaveBeenCalledWith("space", {});
     writeSpy.mockRestore();
@@ -56,8 +55,7 @@ describe("api", () => {
 
     const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 
-    const { default: api } = await import("./api");
-    await api.parseAsync(["/issues", "-X", "POST"], { from: "user" });
+    await parseCommand(() => import("./api"), ["/issues", "-X", "POST"]);
 
     expect(mockClient.post).toHaveBeenCalledWith("/issues", {});
     writeSpy.mockRestore();
@@ -68,8 +66,7 @@ describe("api", () => {
 
     const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 
-    const { default: api } = await import("./api");
-    await api.parseAsync(["/users/myself", "--silent"], { from: "user" });
+    await parseCommand(() => import("./api"), ["/users/myself", "--silent"]);
 
     expect(mockClient.get).toHaveBeenCalled();
     expect(writeSpy).not.toHaveBeenCalled();
@@ -81,8 +78,7 @@ describe("api", () => {
 
     const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 
-    const { default: api } = await import("./api");
-    await api.parseAsync(["/users/myself", "--json", "id,name"], { from: "user" });
+    await parseCommand(() => import("./api"), ["/users/myself", "--json", "id,name"]);
 
     const output = JSON.parse(writeSpy.mock.calls[0][0] as string);
     expect(output).toEqual({ id: 1, name: "Test User" });
@@ -98,8 +94,7 @@ describe("api", () => {
 
     const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 
-    const { default: api } = await import("./api");
-    await api.parseAsync(["/projects", "--json", "id,name"], { from: "user" });
+    await parseCommand(() => import("./api"), ["/projects", "--json", "id,name"]);
 
     const output = JSON.parse(writeSpy.mock.calls[0][0] as string);
     expect(output).toEqual([
@@ -114,8 +109,7 @@ describe("api", () => {
 
     const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 
-    const { default: api } = await import("./api");
-    await api.parseAsync(["/users/myself", "--json"], { from: "user" });
+    await parseCommand(() => import("./api"), ["/users/myself", "--json"]);
 
     const output = JSON.parse(writeSpy.mock.calls[0][0] as string);
     expect(output).toEqual({ id: 1, name: "test" });
 
@@ -4,6 +4,7 @@ import { updateConfig } from "@repo/config";
 import { Backlog, OAuth2 } from "backlog-js";
 import consola from "consola";
 import { describe, expect, it, vi } from "vitest";
+import { parseCommand } from "@repo/test-utils";
 
 const mockGetMyself = vi.fn();
 const mockGetAuthorizationURL = vi.fn(
@@ -48,8 +49,7 @@ describe("auth login", () => {
         updater({ spaces: [], defaultSpace: undefined, aliases: {} }),
       );
 
-      const { default: login } = await import("./login");
-      await login.parseAsync(["--method", "api-key"], { from: "user" });
+      await parseCommand(() => import("./login"), ["--method", "api-key"]);
 
       expect(Backlog).toHaveBeenCalledWith({ host: "example.backlog.com", apiKey: "test-api-key" });
       expect(mockGetMyself).toHaveBeenCalled();
@@ -81,8 +81,7 @@ describe("auth login", () => {
         }),
       );
 
-      const { default: login } = await import("./login");
-      await login.parseAsync(["--method", "api-key"], { from: "user" });
+      await parseCommand(() => import("./login"), ["--method", "api-key"]);
 
       const result = vi.mocked(updateConfig).mock.results[0]?.value;
       expect(result.spaces).toEqual([
@@ -100,8 +99,7 @@ describe("auth login", () => {
         .mockResolvedValueOnce("example.backlog.com")
         .mockResolvedValueOnce("bad-key");
 
-      const { default: login } = await import("./login");
-      await expect(login.parseAsync(["--method", "api-key"], { from: "user" })).rejects.toThrow(
+      await expect(parseCommand(() => import("./login"), ["--method", "api-key"])).rejects.toThrow(
         "Authentication failed. Could not connect to example.backlog.com with the provided API key.",
       );
       expect(updateConfig).not.toHaveBeenCalled();
@@ -110,8 +108,7 @@ describe("auth login", () => {
 
   describe("invalid method", () => {
     it("returns error for invalid method", async () => {
-      const { default: login } = await import("./login");
-      await expect(login.parseAsync(["--method", "invalid"], { from: "user" })).rejects.toThrow(
+      await expect(parseCommand(() => import("./login"), ["--method", "invalid"])).rejects.toThrow(
         'Invalid auth method. Use "api-key" or "oauth".',
       );
     });
@@ -148,10 +145,9 @@ describe("auth login", () => {
         .mockResolvedValueOnce("my-client-id")
         .mockResolvedValueOnce("my-client-secret");
 
-      const { default: login } = await import("./login");
-      await login.parseAsync(
+      await parseCommand(
+        () => import("./login"),
         ["--method", "oauth", "--client-id", "my-client-id", "--client-secret", "my-client-secret"],
-        { from: "user" },
       );
 
       expect(startCallbackServer).toHaveBeenCalled();
@@ -208,9 +204,9 @@ describe("auth login", () => {
         .mockResolvedValueOnce("my-client-id")
         .mockResolvedValueOnce("my-client-secret");
 
-      const { default: login } = await import("./login");
       await expect(
-        login.parseAsync(
+        parseCommand(
+          () => import("./login"),
           [
             "--method",
             "oauth",
@@ -219,7 +215,6 @@ describe("auth login", () => {
             "--client-secret",
             "my-client-secret",
           ],
-          { from: "user" },
         ),
       ).rejects.toThrow("OAuth authorization failed: OAuth callback timed out after 5 minutes");
       expect(mockStop).toHaveBeenCalled();
@@ -233,9 +228,9 @@ describe("auth login", () => {
         .mockResolvedValueOnce("my-client-id")
         .mockResolvedValueOnce("my-client-secret");
 
-      const { default: login } = await import("./login");
       await expect(
-        login.parseAsync(
+        parseCommand(
+          () => import("./login"),
           [
             "--method",
             "oauth",
@@ -244,7 +239,6 @@ describe("auth login", () => {
             "--client-secret",
             "my-client-secret",
           ],
-          { from: "user" },
         ),
       ).rejects.toThrow("Failed to exchange authorization code for tokens.");
     });
@@ -257,9 +251,9 @@ describe("auth login", () => {
         .mockResolvedValueOnce("my-client-id")
         .mockResolvedValueOnce("my-client-secret");
 
-      const { default: login } = await import("./login");
       await expect(
-        login.parseAsync(
+        parseCommand(
+          () => import("./login"),
           [
             "--method",
             "oauth",
@@ -268,7 +262,6 @@ describe("auth login", () => {
             "--client-secret",
             "my-client-secret",
           ],
-          { from: "user" },
         ),
       ).rejects.toThrow("Authentication verification failed.");
     });
@@ -298,10 +291,9 @@ describe("auth login", () => {
         .mockResolvedValueOnce("my-client-id")
         .mockResolvedValueOnce("my-client-secret");
 
-      const { default: login } = await import("./login");
-      await login.parseAsync(
+      await parseCommand(
+        () => import("./login"),
         ["--method", "oauth", "--client-id", "my-client-id", "--client-secret", "my-client-secret"],
-        { from: "user" },
       );
 
       const result = vi.mocked(updateConfig).mock.results[0]?.value;
 
@@ -1,6 +1,7 @@
 import { loadConfig, removeSpace } from "@repo/config";
 import consola from "consola";
 import { describe, expect, it, vi } from "vitest";
+import { parseCommand } from "@repo/test-utils";
 
 vi.mock("@repo/config", () => ({
   loadConfig: vi.fn(),
@@ -22,8 +23,7 @@ describe("auth logout", () => {
       aliases: {},
     });
 
-    const { default: logout } = await import("./logout");
-    await logout.parseAsync(["--space", "example.backlog.com"], { from: "user" });
+    await parseCommand(() => import("./logout"), ["--space", "example.backlog.com"]);
 
     expect(removeSpace).toHaveBeenCalledWith("example.backlog.com");
     expect(consola.success).toHaveBeenCalledWith("Logged out of example.backlog.com.");
@@ -36,8 +36,7 @@ describe("auth logout", () => {
       aliases: {},
     });
 
-    const { default: logout } = await import("./logout");
-    await logout.parseAsync([], { from: "user" });
+    await parseCommand(() => import("./logout"));
 
     expect(consola.info).toHaveBeenCalledWith("No spaces are currently authenticated.");
     expect(removeSpace).not.toHaveBeenCalled();
@@ -53,9 +52,8 @@ describe("auth logout", () => {
       throw new Error("not found");
     });
 
-    const { default: logout } = await import("./logout");
     await expect(
-      logout.parseAsync(["--space", "nonexistent.backlog.com"], { from: "user" }),
+      parseCommand(() => import("./logout"), ["--space", "nonexistent.backlog.com"]),
     ).rejects.toThrow('Space "nonexistent.backlog.com" is not configured.');
   });
 
@@ -72,8 +70,7 @@ describe("auth logout", () => {
     });
     vi.mocked(removeSpace).mockImplementation(() => {});
 
-    const { default: logout } = await import("./logout");
-    await logout.parseAsync([], { from: "user" });
+    await parseCommand(() => import("./logout"));
 
     expect(removeSpace).toHaveBeenCalledWith("only.backlog.com");
     expect(consola.success).toHaveBeenCalledWith("Logged out of only.backlog.com.");
 
@@ -3,6 +3,7 @@ import { findSpace, loadConfig, updateSpaceAuth } from "@repo/config";
 import { Backlog } from "backlog-js";
 import consola from "consola";
 import { describe, expect, it, vi } from "vitest";
+import { parseCommand } from "@repo/test-utils";
 
 const mockGetMyself = vi.fn();
 
@@ -37,8 +38,7 @@ describe("auth refresh", () => {
   it("throws error when no space is configured", async () => {
     mockDefaultSpace(null);
 
-    const { default: refresh } = await import("./refresh");
-    await expect(refresh.parseAsync([], { from: "user" })).rejects.toThrow(
+    await expect(parseCommand(() => import("./refresh"))).rejects.toThrow(
       "No space configured. Run `bee auth login` to authenticate.",
     );
   });
@@ -49,8 +49,7 @@ describe("auth refresh", () => {
       auth: { method: "api-key" as const, apiKey: "key" },
     });
 
-    const { default: refresh } = await import("./refresh");
-    await expect(refresh.parseAsync([], { from: "user" })).rejects.toThrow(
+    await expect(parseCommand(() => import("./refresh"))).rejects.toThrow(
       "Token refresh is only available for OAuth authentication. Current space uses API key.",
     );
   });
@@ -65,8 +64,7 @@ describe("auth refresh", () => {
       },
     });
 
-    const { default: refresh } = await import("./refresh");
-    await expect(refresh.parseAsync([], { from: "user" })).rejects.toThrow(
+    await expect(parseCommand(() => import("./refresh"))).rejects.toThrow(
       "Client ID and Client Secret are missing from the stored OAuth configuration. Please re-authenticate with `bee auth login -m oauth`.",
     );
   });
@@ -90,8 +88,7 @@ describe("auth refresh", () => {
     });
     mockGetMyself.mockResolvedValue({ name: "Test User", userId: "testuser" });
 
-    const { default: refresh } = await import("./refresh");
-    await refresh.parseAsync([], { from: "user" });
+    await parseCommand(() => import("./refresh"));
 
     expect(refreshAccessToken).toHaveBeenCalledWith("example.backlog.com", {
       refreshToken: "old-refresh",
@@ -128,8 +125,7 @@ describe("auth refresh", () => {
     });
     vi.mocked(refreshAccessToken).mockRejectedValue(new Error("invalid_grant"));
 
-    const { default: refresh } = await import("./refresh");
-    await expect(refresh.parseAsync([], { from: "user" })).rejects.toThrow(
+    await expect(parseCommand(() => import("./refresh"))).rejects.toThrow(
       "Failed to refresh OAuth token. Please re-authenticate with `bee auth login -m oauth`.",
     );
   });
@@ -153,8 +149,7 @@ describe("auth refresh", () => {
     });
     mockGetMyself.mockRejectedValue(new Error("Unauthorized"));
 
-    const { default: refresh } = await import("./refresh");
-    await expect(refresh.parseAsync([], { from: "user" })).rejects.toThrow(
+    await expect(parseCommand(() => import("./refresh"))).rejects.toThrow(
       "Token verification failed after refresh.",
     );
   });