github-issue-tower-defence-management 1.60.2 → 1.64.0

package/src/adapter/entry-points/cli/index.ts

@@ -16,6 +16,7 @@ import {
   fetchProjectReadme,
 } from './projectConfig';
 import { StartPreparationUseCase } from '../../../domain/usecases/StartPreparationUseCase';
+import { writeRotationOrderFile } from '../handlers/rotationOrderFileWriter';
 import { ProxyClaudeTokenUsageRepository } from '../../repositories/ProxyClaudeTokenUsageRepository';
 import { NotifyFinishedIssuePreparationUseCase } from '../../../domain/usecases/NotifyFinishedIssuePreparationUseCase';
 import { LocalStorageRepository } from '../../repositories/LocalStorageRepository';
@@ -54,15 +55,10 @@ type NotifyFinishedOptions = {
 
 const buildGithubRepositoryParams = (
   localStorageRepository: LocalStorageRepository,
-  cachePath: string,
   token: string,
 ): ConstructorParameters<typeof BaseGitHubRepository> => [
   localStorageRepository,
-  `${cachePath}/github.com.cookies.json`,
   token,
-  undefined,
-  undefined,
-  undefined,
 ];
 
 interface ScheduleOptions {
@@ -113,7 +109,7 @@ program
   .option('--defaultLlmAgentName <name>', 'Default LLM agent name')
   .option(
     '--maximumPreparingIssuesCount <count>',
-    'Maximum number of issues in preparation status (default: 6)',
+    'Maximum number of issues in preparation status (default: 6 per available Claude OAuth token, otherwise 6)',
   )
   .option(
     '--allowIssueCacheMinutes <minutes>',
@@ -121,7 +117,7 @@ program
   )
   .option(
     '--utilizationPercentageThreshold <percent>',
-    'Claude utilization percentage threshold (default: 90)',
+    'Legacy Claude utilization threshold setting; token process slots decay from 80% utilization to 0 at 95% (default: 90)',
   )
   .option(
     '--allowedIssueAuthors <authors>',
@@ -211,7 +207,7 @@ program
     const allowIssueCacheMinutes = config.allowIssueCacheMinutes ?? 10;
 
     console.log(
-      `maximumPreparingIssuesCount: ${maximumPreparingIssuesCount ?? 'null (default: 6)'}`,
+      `maximumPreparingIssuesCount: ${maximumPreparingIssuesCount ?? 'null (default: 6 per available Claude OAuth token, otherwise 6)'}`,
     );
 
     const projectName = config.projectName ?? 'default';
@@ -223,7 +219,6 @@ program
     );
     const githubRepositoryParams = buildGithubRepositoryParams(
       localStorageRepository,
-      cachePath,
       token,
     );
     const projectRepository = new GraphqlProjectRepository(
@@ -291,7 +286,7 @@ program
         ? config.codexHomeCandidates
         : null;
 
-    await useCase.run({
+    const preparationResult = await useCase.run({
       projectUrl,
       defaultAgentName,
       defaultLlmModelName: config.defaultLlmModelName ?? null,
@@ -304,6 +299,9 @@ program
       codexHomeCandidates,
       allowIssueCacheMinutes,
     });
+    if (preparationResult.rotationOrder !== null) {
+      writeRotationOrderFile(preparationResult.rotationOrder);
+    }
   });
 
 program
@@ -396,7 +394,6 @@ program
     );
     const githubRepositoryParams = buildGithubRepositoryParams(
       localStorageRepository,
-      cachePath,
       token,
     );
     const projectRepository = new GraphqlProjectRepository(

package/src/adapter/entry-points/handlers/GetStoryObjectMapUseCaseHandler.test.ts

@@ -93,43 +93,17 @@ describe('GetStoryObjectMapUseCaseHandler', () => {
     );
   });
 
-  it('should pass bot credentials to repository constructors when provided', async () => {
-    const configWithCredentials = {
-      ...validConfig,
-      credentials: {
-        bot: {
-          github: {
-            token: 'test-token',
-            name: 'bot-user',
-            password: 'bot-pass',
-            authenticatorKey: 'bot-auth-key',
-          },
-        },
-      },
-    };
-    jest
-      .mocked(fs.readFileSync)
-      .mockReturnValue(YAML.stringify(configWithCredentials));
-
+  it('should pass bot token to repository constructors', async () => {
     const handler = new GetStoryObjectMapUseCaseHandler();
     await handler.handle('config.yml', false);
 
-    const expectedCookiePath = `./tmp/cache/${validConfig.projectName}/github.com.cookies.json`;
-
     for (const MockedClass of [
       MockedGraphqlProjectRepository,
       MockedApiV3IssueRepository,
       MockedRestIssueRepository,
       MockedGraphqlProjectItemRepository,
     ]) {
-      expect(MockedClass).toHaveBeenCalledWith(
-        expect.anything(),
-        expectedCookiePath,
-        'test-token',
-        'bot-user',
-        'bot-pass',
-        'bot-auth-key',
-      );
+      expect(MockedClass).toHaveBeenCalledWith(expect.anything(), 'test-token');
     }
 
     expect(MockedApiV3CheerioRestIssueRepository).toHaveBeenCalledWith(
@@ -138,34 +112,7 @@ describe('GetStoryObjectMapUseCaseHandler', () => {
       expect.anything(),
       expect.anything(),
       expect.anything(),
-      expectedCookiePath,
       'test-token',
-      'bot-user',
-      'bot-pass',
-      'bot-auth-key',
     );
   });
-
-  it('should pass undefined credentials when not provided in config', async () => {
-    const handler = new GetStoryObjectMapUseCaseHandler();
-    await handler.handle('config.yml', false);
-
-    const expectedCookiePath = `./tmp/cache/${validConfig.projectName}/github.com.cookies.json`;
-
-    for (const MockedClass of [
-      MockedGraphqlProjectRepository,
-      MockedApiV3IssueRepository,
-      MockedRestIssueRepository,
-      MockedGraphqlProjectItemRepository,
-    ]) {
-      expect(MockedClass).toHaveBeenCalledWith(
-        expect.anything(),
-        expectedCookiePath,
-        'test-token',
-        undefined,
-        undefined,
-        undefined,
-      );
-    }
-  });
 });

package/src/adapter/entry-points/handlers/GetStoryObjectMapUseCaseHandler.ts

@@ -33,9 +33,6 @@ export class GetStoryObjectMapUseCaseHandler {
         bot: {
           github: {
             token: string;
-            name?: string;
-            password?: string;
-            authenticatorKey?: string;
           };
         };
       };
@@ -54,14 +51,7 @@ export class GetStoryObjectMapUseCaseHandler {
     );
     const githubRepositoryParams: ConstructorParameters<
       typeof BaseGitHubRepository
-    > = [
-      localStorageRepository,
-      `${cachePath}/github.com.cookies.json`,
-      input.credentials.bot.github.token,
-      input.credentials.bot.github.name,
-      input.credentials.bot.github.password,
-      input.credentials.bot.github.authenticatorKey,
-    ];
+    > = [localStorageRepository, input.credentials.bot.github.token];
     const projectRepository = {
       ...new GraphqlProjectRepository(...githubRepositoryParams),
     };

package/src/adapter/entry-points/handlers/HandleScheduledEventUseCaseHandler.test.ts

@@ -23,6 +23,7 @@ const mockRun = jest.fn().mockImplementation((...args: Parameters<RunFn>) => {
     issues: [],
     cacheUsed: false,
     targetDateTimes: [],
+    rotationOrder: null,
   });
 });
 
@@ -114,6 +115,9 @@ jest.mock('../../repositories/GitHubIssueCommentRepository', () => ({
 jest.mock('./situationFileWriter', () => ({
   writeSituationFile: jest.fn().mockResolvedValue(undefined),
 }));
+jest.mock('./rotationOrderFileWriter', () => ({
+  writeRotationOrderFile: jest.fn(),
+}));
 
 import { HandleScheduledEventUseCaseHandler } from './HandleScheduledEventUseCaseHandler';
 import { writeSituationFile } from './situationFileWriter';
@@ -185,44 +189,17 @@ describe('HandleScheduledEventUseCaseHandler', () => {
     mockFetchReturningReadme(null);
   });
 
-  it('should pass bot credentials to repository constructors when provided', async () => {
-    const configWithCredentials = {
-      ...validConfig,
-      credentials: {
-        ...validConfig.credentials,
-        bot: {
-          github: {
-            token: 'test-token',
-            name: 'bot-user',
-            password: 'bot-pass',
-            authenticatorKey: 'bot-auth-key',
-          },
-        },
-      },
-    };
-    jest
-      .mocked(fs.readFileSync)
-      .mockReturnValue(YAML.stringify(configWithCredentials));
-
+  it('should pass bot token to repository constructors', async () => {
     const handler = new HandleScheduledEventUseCaseHandler();
     await handler.handle('config.yml', false);
 
-    const expectedCookiePath = `./tmp/cache/${validConfig.projectName}/github.com.cookies.json`;
-
     for (const MockedClass of [
       MockedGraphqlProjectRepository,
       MockedApiV3IssueRepository,
       MockedRestIssueRepository,
       MockedGraphqlProjectItemRepository,
     ]) {
-      expect(MockedClass).toHaveBeenCalledWith(
-        expect.anything(),
-        expectedCookiePath,
-        'test-token',
-        'bot-user',
-        'bot-pass',
-        'bot-auth-key',
-      );
+      expect(MockedClass).toHaveBeenCalledWith(expect.anything(), 'test-token');
     }
 
     expect(MockedApiV3CheerioRestIssueRepository).toHaveBeenCalledWith(
@@ -231,37 +208,10 @@ describe('HandleScheduledEventUseCaseHandler', () => {
       expect.anything(),
       expect.anything(),
       expect.anything(),
-      expectedCookiePath,
       'test-token',
-      'bot-user',
-      'bot-pass',
-      'bot-auth-key',
     );
   });
 
-  it('should pass undefined credentials when not provided in config', async () => {
-    const handler = new HandleScheduledEventUseCaseHandler();
-    await handler.handle('config.yml', false);
-
-    const expectedCookiePath = `./tmp/cache/${validConfig.projectName}/github.com.cookies.json`;
-
-    for (const MockedClass of [
-      MockedGraphqlProjectRepository,
-      MockedApiV3IssueRepository,
-      MockedRestIssueRepository,
-      MockedGraphqlProjectItemRepository,
-    ]) {
-      expect(MockedClass).toHaveBeenCalledWith(
-        expect.anything(),
-        expectedCookiePath,
-        'test-token',
-        undefined,
-        undefined,
-        undefined,
-      );
-    }
-  });
-
   it('should write situation file after successful run with resolved config values', async () => {
     const configWithPreparation = {
       ...validConfig,

package/src/adapter/entry-points/handlers/HandleScheduledEventUseCaseHandler.ts

@@ -2,6 +2,7 @@ import YAML from 'yaml';
 import TYPIA from 'typia';
 import fs from 'fs';
 import { writeSituationFile } from './situationFileWriter';
+import { writeRotationOrderFile } from './rotationOrderFileWriter';
 import {
   fetchProjectReadme,
   parseProjectReadmeConfig,
@@ -44,6 +45,7 @@ import { SetupTowerDefenceProjectUseCase } from '../../../domain/usecases/SetupT
 import {
   AWAITING_QUALITY_CHECK_STATUS_NAME,
   AWAITING_WORKSPACE_STATUS_NAME,
+  FAILED_PREPARATION_STATUS_NAME,
   PREPARATION_STATUS_NAME,
 } from '../../../domain/entities/WorkflowStatus';
 
@@ -76,9 +78,6 @@ export class HandleScheduledEventUseCaseHandler {
         bot: {
           github: {
             token: string;
-            name?: string;
-            password?: string;
-            authenticatorKey?: string;
           };
         };
       };
@@ -151,14 +150,7 @@ export class HandleScheduledEventUseCaseHandler {
     );
     const githubRepositoryParams: ConstructorParameters<
       typeof BaseGitHubRepository
-    > = [
-      localStorageRepository,
-      `${cachePath}/github.com.cookies.json`,
-      input.credentials.bot.github.token,
-      input.credentials.bot.github.name,
-      input.credentials.bot.github.password,
-      input.credentials.bot.github.authenticatorKey,
-    ];
+    > = [localStorageRepository, input.credentials.bot.github.token];
     const projectRepository = new GraphqlProjectRepository(
       ...githubRepositoryParams,
     );
@@ -281,6 +273,9 @@ export class HandleScheduledEventUseCaseHandler {
 
     const result = await handleScheduledEventUseCase.run(mergedInput);
     if (result) {
+      if (result.rotationOrder !== null) {
+        writeRotationOrderFile(result.rotationOrder);
+      }
       await writeSituationFile({
         cachePath,
         projectId: result.project.id,
@@ -289,6 +284,7 @@ export class HandleScheduledEventUseCaseHandler {
           awaitingQualityCheckStatus: AWAITING_QUALITY_CHECK_STATUS_NAME,
           preparationStatus: PREPARATION_STATUS_NAME,
           awaitingWorkspaceStatus: AWAITING_WORKSPACE_STATUS_NAME,
+          failedPreparationStatus: FAILED_PREPARATION_STATUS_NAME,
         },
         config: {
           maximumPreparingIssuesCount:

package/src/adapter/entry-points/handlers/rotationOrderFileWriter.test.ts

@@ -0,0 +1,177 @@
+import fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { writeRotationOrderFile } from './rotationOrderFileWriter';
+import type { RotationOrderEntry } from '../../../domain/usecases/StartPreparationUseCase';
+
+jest.mock('fs');
+
+const TOKEN_A = 'sk-ant-secret-token-a-value';
+const TOKEN_B = 'sk-ant-secret-token-b-value';
+
+describe('writeRotationOrderFile', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.mocked(fs.mkdirSync).mockReturnValue(undefined);
+    jest.mocked(fs.writeFileSync).mockReturnValue(undefined);
+    jest.mocked(fs.renameSync).mockReturnValue(undefined);
+  });
+
+  it('writes rotation order entries sorted selected-first to the stable path under XDG_CACHE_HOME', () => {
+    const originalXdg = process.env.XDG_CACHE_HOME;
+    process.env.XDG_CACHE_HOME = '/custom/cache';
+
+    const entries: RotationOrderEntry[] = [
+      {
+        name: 'personal-1',
+        fiveHourUtilization: 0.2,
+        blocked: false,
+        rejected: false,
+        thresholdExcluded: false,
+      },
+    ];
+
+    writeRotationOrderFile(entries);
+
+    expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+      '/custom/cache/tdpm/rotation-order.json.tmp',
+      expect.any(String),
+    );
+    expect(jest.mocked(fs.renameSync)).toHaveBeenCalledWith(
+      '/custom/cache/tdpm/rotation-order.json.tmp',
+      '/custom/cache/tdpm/rotation-order.json',
+    );
+
+    process.env.XDG_CACHE_HOME = originalXdg;
+  });
+
+  it('falls back to ~/.cache/tdpm/rotation-order.json when XDG_CACHE_HOME is unset', () => {
+    const originalXdg = process.env.XDG_CACHE_HOME;
+    delete process.env.XDG_CACHE_HOME;
+
+    const home = os.homedir();
+    const expectedPath = path.join(
+      home,
+      '.cache',
+      'tdpm',
+      'rotation-order.json',
+    );
+
+    writeRotationOrderFile([]);
+
+    expect(jest.mocked(fs.renameSync)).toHaveBeenCalledWith(
+      `${expectedPath}.tmp`,
+      expectedPath,
+    );
+
+    process.env.XDG_CACHE_HOME = originalXdg;
+  });
+
+  it('includes name, fiveHourUtilization, blocked, rejected, and thresholdExcluded in output', () => {
+    process.env.XDG_CACHE_HOME = '/cache';
+
+    const entries: RotationOrderEntry[] = [
+      {
+        name: 'personal-1',
+        fiveHourUtilization: 0.3,
+        blocked: false,
+        rejected: false,
+        thresholdExcluded: false,
+      },
+      {
+        name: 'personal-2',
+        fiveHourUtilization: 0.95,
+        blocked: false,
+        rejected: false,
+        thresholdExcluded: true,
+      },
+    ];
+
+    writeRotationOrderFile(entries);
+
+    expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.stringContaining('"name":"personal-1"'),
+    );
+    expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.stringContaining('"name":"personal-2"'),
+    );
+    expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.stringContaining('"fiveHourUtilization":0.3'),
+    );
+    expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.stringContaining('"thresholdExcluded":true'),
+    );
+
+    delete process.env.XDG_CACHE_HOME;
+  });
+
+  it('does not write raw token values to the output file', () => {
+    process.env.XDG_CACHE_HOME = '/cache';
+
+    const entries: RotationOrderEntry[] = [
+      {
+        name: 'personal-1',
+        fiveHourUtilization: 0.1,
+        blocked: false,
+        rejected: false,
+        thresholdExcluded: false,
+      },
+    ];
+
+    writeRotationOrderFile(entries);
+
+    expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.not.stringContaining(TOKEN_A),
+    );
+    expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.not.stringContaining(TOKEN_B),
+    );
+    expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.not.stringContaining('sk-ant-'),
+    );
+
+    delete process.env.XDG_CACHE_HOME;
+  });
+
+  it('writes atomically: mkdirSync before writeFileSync before renameSync', () => {
+    process.env.XDG_CACHE_HOME = '/cache';
+
+    const callOrder: string[] = [];
+    jest.mocked(fs.mkdirSync).mockImplementation((): undefined => {
+      callOrder.push('mkdir');
+      return undefined;
+    });
+    jest.mocked(fs.writeFileSync).mockImplementation((): void => {
+      callOrder.push('write');
+    });
+    jest.mocked(fs.renameSync).mockImplementation((): void => {
+      callOrder.push('rename');
+    });
+
+    writeRotationOrderFile([]);
+
+    expect(callOrder).toEqual(['mkdir', 'write', 'rename']);
+
+    delete process.env.XDG_CACHE_HOME;
+  });
+
+  it('writes an empty array when no rotation entries are provided', () => {
+    process.env.XDG_CACHE_HOME = '/cache';
+
+    writeRotationOrderFile([]);
+
+    expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+      expect.any(String),
+      '[]',
+    );
+
+    delete process.env.XDG_CACHE_HOME;
+  });
+});

package/src/adapter/entry-points/handlers/rotationOrderFileWriter.ts

@@ -0,0 +1,20 @@
+import fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import type { RotationOrderEntry } from '../../../domain/usecases/StartPreparationUseCase';
+
+const rotationOrderFilePath = (): string => {
+  const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
+  return path.join(base, 'tdpm', 'rotation-order.json');
+};
+
+export const writeRotationOrderFile = (
+  rotationOrder: RotationOrderEntry[],
+): void => {
+  const filePath = rotationOrderFilePath();
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmpPath = `${filePath}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(rotationOrder));
+  fs.renameSync(tmpPath, filePath);
+};

package/src/adapter/entry-points/handlers/situationFileWriter.test.ts

@@ -50,6 +50,7 @@ const baseParams = {
     awaitingQualityCheckStatus: 'Awaiting quality check',
     preparationStatus: 'Preparation',
     awaitingWorkspaceStatus: 'Awaiting workspace',
+    failedPreparationStatus: 'Failed Preparation',
   },
   config: {
     maximumPreparingIssuesCount: 6,
@@ -183,6 +184,7 @@ describe('writeSituationFile', () => {
           awaitingQualityCheckStatus: null,
           preparationStatus: null,
           awaitingWorkspaceStatus: null,
+          failedPreparationStatus: null,
         },
         issues,
       };
@@ -207,6 +209,40 @@ describe('writeSituationFile', () => {
         expect.any(String),
         expect.stringContaining('"awaitingWorkspaceBlockedByDependency":0'),
       );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"failedPreparation":0'),
+      );
+    });
+
+    it('counts failedPreparation correctly from fixture issues', async () => {
+      const issues = [
+        createIssue({ status: 'Failed Preparation' }),
+        createIssue({ status: 'Failed Preparation' }),
+        createIssue({ status: 'Preparation' }),
+        createIssue({ status: 'Awaiting workspace' }),
+      ];
+
+      await writeSituationFile({ ...baseParams, issues });
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"failedPreparation":2'),
+      );
+    });
+
+    it('sets failedPreparation to 0 when no issues match the failed preparation status', async () => {
+      const issues = [
+        createIssue({ status: 'Preparation' }),
+        createIssue({ status: 'Awaiting workspace' }),
+      ];
+
+      await writeSituationFile({ ...baseParams, issues });
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"failedPreparation":0'),
+      );
     });
   });
 

package/src/adapter/entry-points/handlers/situationFileWriter.ts

@@ -10,6 +10,7 @@ export type SituationFileParams = {
     awaitingQualityCheckStatus: string | null;
     preparationStatus: string | null;
     awaitingWorkspaceStatus: string | null;
+    failedPreparationStatus: string | null;
   };
   config: {
     maximumPreparingIssuesCount: number | null;
@@ -104,6 +105,12 @@ export const writeSituationFile = async (
       ? issues.filter((i) => i.status === statusNames.awaitingWorkspaceStatus)
       : [];
 
+  const failedPreparation =
+    statusNames.failedPreparationStatus !== null
+      ? issues.filter((i) => i.status === statusNames.failedPreparationStatus)
+          .length
+      : 0;
+
   const awaitingWorkspaceImmediatelyActionable = awaitingWorkspaceIssues.filter(
     isImmediatelyActionable,
   ).length;
@@ -142,6 +149,7 @@ export const writeSituationFile = async (
       preparation: preparationIssues.length,
       awaitingWorkspaceImmediatelyActionable,
       awaitingWorkspaceBlockedByDependency,
+      failedPreparation,
     },
     processes: {
       runningPreparation,

package/src/adapter/proxy/TokenListLoader.test.ts

@@ -1,7 +1,56 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { loadTokens } from './TokenListLoader';
+import { loadTokenEntries, loadTokens } from './TokenListLoader';
+
+describe('loadTokenEntries', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'token-entries-loader-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('should return entries with name and token', () => {
+    const filePath = path.join(tempDir, 'tokens.json');
+    fs.writeFileSync(
+      filePath,
+      JSON.stringify([
+        { name: 'alice', token: 'token-a' },
+        { name: 'bob', token: 'token-b' },
+      ]),
+    );
+    expect(loadTokenEntries(filePath)).toEqual([
+      { name: 'alice', token: 'token-a' },
+      { name: 'bob', token: 'token-b' },
+    ]);
+  });
+
+  it('should assign a unique positional name when name is absent from entry', () => {
+    const filePath = path.join(tempDir, 'tokens.json');
+    fs.writeFileSync(
+      filePath,
+      JSON.stringify([{ token: 'token-a' }, { token: 'token-b' }]),
+    );
+    expect(loadTokenEntries(filePath)).toEqual([
+      { name: 'token-1', token: 'token-a' },
+      { name: 'token-2', token: 'token-b' },
+    ]);
+  });
+
+  it('should return null when file does not exist', () => {
+    expect(loadTokenEntries(path.join(tempDir, 'missing.json'))).toBeNull();
+  });
+
+  it('should return null when every entry is invalid', () => {
+    const filePath = path.join(tempDir, 'invalid.json');
+    fs.writeFileSync(filePath, JSON.stringify([{ name: 'no-token' }]));
+    expect(loadTokenEntries(filePath)).toBeNull();
+  });
+});
 
 describe('TokenListLoader', () => {
   let tempDir: string;