github-issue-tower-defence-management 1.60.1 → 1.63.1

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

@@ -475,7 +475,7 @@ codexHomeCandidates:
 
   describe('startDaemon', () => {
     it('should read parameters from config file', async () => {
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedStartPreparationUseCase = jest.mocked(
         StartPreparationUseCase,
       );
@@ -511,7 +511,7 @@ codexHomeCandidates:
     });
 
     it('should allow CLI args to override config file values', async () => {
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedStartPreparationUseCase = jest.mocked(
         StartPreparationUseCase,
       );
@@ -558,7 +558,7 @@ codexHomeCandidates:
       };
       writeConfig(configWithLlm);
 
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedStartPreparationUseCase = jest.mocked(
         StartPreparationUseCase,
       );
@@ -593,7 +593,7 @@ codexHomeCandidates:
       };
       writeConfig(configWithCount);
 
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedStartPreparationUseCase = jest.mocked(
         StartPreparationUseCase,
       );
@@ -621,7 +621,7 @@ codexHomeCandidates:
     });
 
     it('should pass maximumPreparingIssuesCount from CLI overriding config', async () => {
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedStartPreparationUseCase = jest.mocked(
         StartPreparationUseCase,
       );
@@ -815,7 +815,7 @@ codexHomeCandidates:
         });
       const mockRun = jest.fn().mockImplementation(() => {
         callOrder.push('useCase.run');
-        return Promise.resolve(undefined);
+        return Promise.resolve({ rotationOrder: null });
       });
       const MockedStartPreparationUseCase = jest.mocked(
         StartPreparationUseCase,
@@ -857,7 +857,7 @@ codexHomeCandidates:
       ].join('\n');
       mockFetchReturningReadme(readmeContent);
 
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedStartPreparationUseCase = jest.mocked(
         StartPreparationUseCase,
       );
@@ -891,7 +891,7 @@ codexHomeCandidates:
       };
       writeConfig(configWithCandidates);
 
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedStartPreparationUseCase = jest.mocked(
         StartPreparationUseCase,
       );
@@ -919,7 +919,7 @@ codexHomeCandidates:
     });
 
     it('should pass codexHomeCandidates as null when not in config', async () => {
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedStartPreparationUseCase = jest.mocked(
         StartPreparationUseCase,
       );
@@ -958,7 +958,7 @@ codexHomeCandidates:
       ].join('\n');
       mockFetchReturningReadme(readmeContent);
 
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedStartPreparationUseCase = jest.mocked(
         StartPreparationUseCase,
       );
@@ -988,7 +988,7 @@ codexHomeCandidates:
 
   describe('notifyFinishedIssuePreparation', () => {
     it('should read parameters from config file', async () => {
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedNotifyFinishedUseCase = jest.mocked(
         NotifyFinishedIssuePreparationUseCase,
       );
@@ -1020,7 +1020,7 @@ codexHomeCandidates:
     });
 
     it('should allow CLI args to override config file values', async () => {
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedNotifyFinishedUseCase = jest.mocked(
         NotifyFinishedIssuePreparationUseCase,
       );
@@ -1059,7 +1059,7 @@ codexHomeCandidates:
       };
       writeConfig(configWithThreshold);
 
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedNotifyFinishedUseCase = jest.mocked(
         NotifyFinishedIssuePreparationUseCase,
       );
@@ -1089,7 +1089,7 @@ codexHomeCandidates:
     });
 
     it('should pass custom thresholdForAutoReject from CLI overriding config', async () => {
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedNotifyFinishedUseCase = jest.mocked(
         NotifyFinishedIssuePreparationUseCase,
       );
@@ -1221,7 +1221,7 @@ codexHomeCandidates:
       };
       writeConfig(configWithWebhook);
 
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedNotifyFinishedUseCase = jest.mocked(
         NotifyFinishedIssuePreparationUseCase,
       );
@@ -1261,7 +1261,7 @@ codexHomeCandidates:
       ].join('\n');
       mockFetchReturningReadme(readmeContent);
 
-      const mockRun = jest.fn().mockResolvedValue(undefined);
+      const mockRun = jest.fn().mockResolvedValue({ rotationOrder: null });
       const MockedNotifyFinishedUseCase = jest.mocked(
         NotifyFinishedIssuePreparationUseCase,
       );

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