github-issue-tower-defence-management 1.46.0 → 1.48.0

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

@@ -0,0 +1,417 @@
+import fs from 'fs';
+import type { Issue } from '../../../domain/entities/Issue';
+import type { LocalCommandRunner } from '../../../domain/usecases/adapter-interfaces/LocalCommandRunner';
+import { parseMeminfo, writeSituationFile } from './situationFileWriter';
+
+jest.mock('fs');
+
+const FIXTURE_MEMINFO = `MemTotal:       16384000 kB
+MemFree:         4096000 kB
+MemAvailable:    8192000 kB
+Buffers:          512000 kB
+Cached:          3584000 kB
+SwapTotal:       4096000 kB
+SwapFree:        3072000 kB
+SwapCached:            0 kB
+`;
+
+const createIssue = (overrides: Partial<Issue> = {}): Issue => ({
+  nameWithOwner: 'owner/repo',
+  number: 1,
+  title: 'Test Issue',
+  state: 'OPEN',
+  status: null,
+  story: null,
+  nextActionDate: null,
+  nextActionHour: null,
+  estimationMinutes: null,
+  dependedIssueUrls: [],
+  completionDate50PercentConfidence: null,
+  url: 'https://github.com/owner/repo/issues/1',
+  assignees: [],
+  labels: [],
+  org: 'owner',
+  repo: 'repo',
+  body: '',
+  itemId: 'item-1',
+  isPr: false,
+  isInProgress: false,
+  isClosed: false,
+  createdAt: new Date('2025-01-01'),
+  author: 'user',
+  ...overrides,
+});
+
+const baseParams = {
+  cachePath: './tmp/cache/test-project',
+  projectId: 'PVT_kwHOtest999',
+  issues: [],
+  statusNames: {
+    awaitingQualityCheckStatus: 'Awaiting quality check',
+    preparationStatus: 'Preparation',
+    awaitingWorkspaceStatus: 'Awaiting workspace',
+  },
+  config: {
+    maximumPreparingIssuesCount: 6,
+    utilizationPercentageThreshold: 90,
+    allowIssueCacheMinutes: 5,
+    thresholdForAutoReject: 3,
+  },
+};
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  jest.mocked(fs.readFileSync).mockReturnValue(FIXTURE_MEMINFO);
+  jest.mocked(fs.mkdirSync).mockReturnValue(undefined);
+  jest.mocked(fs.writeFileSync).mockReturnValue(undefined);
+  jest.mocked(fs.renameSync).mockReturnValue(undefined);
+});
+
+describe('parseMeminfo', () => {
+  it('parses MemTotal, MemAvailable, SwapTotal, SwapFree from /proc/meminfo fixture', () => {
+    const result = parseMeminfo(FIXTURE_MEMINFO);
+    expect(result.memTotalKb).toBe(16384000);
+    expect(result.memAvailableKb).toBe(8192000);
+    expect(result.swapTotalKb).toBe(4096000);
+    expect(result.swapFreeKb).toBe(3072000);
+  });
+
+  it('returns 0 for missing fields', () => {
+    const result = parseMeminfo('MemTotal: 8192000 kB\n');
+    expect(result.memAvailableKb).toBe(0);
+    expect(result.swapTotalKb).toBe(0);
+    expect(result.swapFreeKb).toBe(0);
+  });
+});
+
+describe('writeSituationFile', () => {
+  describe('status counts from issue fixtures', () => {
+    it('counts awaitingQualityCheckImmediatelyActionable correctly', async () => {
+      const issues = [
+        createIssue({
+          status: 'Awaiting quality check',
+          dependedIssueUrls: [],
+          nextActionDate: null,
+          nextActionHour: null,
+        }),
+        createIssue({
+          status: 'Awaiting quality check',
+          dependedIssueUrls: ['https://github.com/owner/repo/issues/2'],
+          nextActionDate: null,
+          nextActionHour: null,
+        }),
+        createIssue({
+          status: 'Awaiting quality check',
+          dependedIssueUrls: [],
+          nextActionDate: new Date('2025-06-01'),
+          nextActionHour: null,
+        }),
+        createIssue({ status: 'Awaiting quality check', nextActionHour: 9 }),
+        createIssue({ status: 'Preparation' }),
+      ];
+
+      await writeSituationFile({ ...baseParams, issues });
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining(
+          '"awaitingQualityCheckImmediatelyActionable":1',
+        ),
+      );
+    });
+
+    it('counts preparation total correctly', async () => {
+      const issues = [
+        createIssue({ status: 'Preparation' }),
+        createIssue({ status: 'Preparation' }),
+        createIssue({ status: 'Awaiting workspace' }),
+      ];
+
+      await writeSituationFile({ ...baseParams, issues });
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"preparation":2'),
+      );
+    });
+
+    it('counts awaitingWorkspaceImmediatelyActionable correctly', async () => {
+      const issues = [
+        createIssue({
+          status: 'Awaiting workspace',
+          dependedIssueUrls: [],
+          nextActionDate: null,
+          nextActionHour: null,
+        }),
+        createIssue({
+          status: 'Awaiting workspace',
+          dependedIssueUrls: [],
+          nextActionDate: null,
+          nextActionHour: null,
+        }),
+        createIssue({
+          status: 'Awaiting workspace',
+          dependedIssueUrls: ['https://github.com/owner/repo/issues/10'],
+        }),
+        createIssue({
+          status: 'Awaiting workspace',
+          dependedIssueUrls: [],
+          nextActionDate: new Date('2025-06-01'),
+        }),
+      ];
+
+      await writeSituationFile({ ...baseParams, issues });
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"awaitingWorkspaceImmediatelyActionable":2'),
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"awaitingWorkspaceBlockedByDependency":1'),
+      );
+    });
+
+    it('sets all counts to 0 when statusNames are null', async () => {
+      const issues = [
+        createIssue({ status: 'Preparation' }),
+        createIssue({ status: 'Awaiting workspace' }),
+      ];
+      const params = {
+        ...baseParams,
+        statusNames: {
+          awaitingQualityCheckStatus: null,
+          preparationStatus: null,
+          awaitingWorkspaceStatus: null,
+        },
+        issues,
+      };
+
+      await writeSituationFile(params);
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining(
+          '"awaitingQualityCheckImmediatelyActionable":0',
+        ),
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"preparation":0'),
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"awaitingWorkspaceImmediatelyActionable":0'),
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"awaitingWorkspaceBlockedByDependency":0'),
+      );
+    });
+  });
+
+  describe('system metrics from /proc/meminfo fixture', () => {
+    it('parses memory usedPercent from fixture', async () => {
+      await writeSituationFile(baseParams);
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"usedPercent":50'),
+      );
+    });
+
+    it('parses swap usedPercent from fixture', async () => {
+      await writeSituationFile(baseParams);
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"usedPercent":25'),
+      );
+    });
+
+    it('includes memory totalGib from fixture', async () => {
+      await writeSituationFile(baseParams);
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"system"'),
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"memory"'),
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"swap"'),
+      );
+    });
+
+    it('handles zero swap total without division by zero', async () => {
+      jest
+        .mocked(fs.readFileSync)
+        .mockReturnValue(
+          'MemTotal: 8192000 kB\nMemAvailable: 4096000 kB\nSwapTotal: 0 kB\nSwapFree: 0 kB\n',
+        );
+
+      await writeSituationFile(baseParams);
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining(
+          '"swap":{"usedPercent":0,"usedGib":0,"totalGib":0}',
+        ),
+      );
+    });
+  });
+
+  describe('atomic write path', () => {
+    it('writes to tmp file then renames to final path', async () => {
+      await writeSituationFile(baseParams);
+
+      const expectedFinalPath = `${baseParams.cachePath}/situation-${baseParams.projectId}.json`;
+      const expectedTmpPath = `${expectedFinalPath}.tmp`;
+
+      expect(jest.mocked(fs.mkdirSync)).toHaveBeenCalledWith(
+        baseParams.cachePath,
+        { recursive: true },
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expectedTmpPath,
+        expect.any(String),
+      );
+      expect(jest.mocked(fs.renameSync)).toHaveBeenCalledWith(
+        expectedTmpPath,
+        expectedFinalPath,
+      );
+    });
+
+    it('writes mkdirSync before writeFileSync before renameSync', async () => {
+      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');
+      });
+
+      await writeSituationFile(baseParams);
+
+      expect(callOrder).toEqual(['mkdir', 'write', 'rename']);
+    });
+
+    it('written JSON contains config and capturedAt fields', async () => {
+      await writeSituationFile(baseParams);
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"capturedAt"'),
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"maximumPreparingIssuesCount":6'),
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"utilizationPercentageThreshold":90'),
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"allowIssueCacheMinutes":5'),
+      );
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"thresholdForAutoReject":3'),
+      );
+    });
+  });
+
+  describe('running preparation processes', () => {
+    it('counts running processes via preparationProcessCheckCommand', async () => {
+      const mockRunCommand = jest
+        .fn()
+        .mockImplementation(async (_program: string, args: string[]) =>
+          Promise.resolve({
+            stdout: '',
+            stderr: '',
+            exitCode:
+              args[3] === 'https://github.com/owner/repo/issues/1' ? 0 : 1,
+          }),
+        );
+      const mockRunner: LocalCommandRunner = {
+        runCommand: mockRunCommand,
+      };
+      const issues = [
+        createIssue({
+          status: 'Preparation',
+          url: 'https://github.com/owner/repo/issues/1',
+          number: 1,
+        }),
+        createIssue({
+          status: 'Preparation',
+          url: 'https://github.com/owner/repo/issues/2',
+          number: 2,
+        }),
+      ];
+
+      await writeSituationFile({
+        ...baseParams,
+        issues,
+        preparationProcessCheckCommand: 'pgrep -fa "{URL}"',
+        localCommandRunner: mockRunner,
+      });
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"runningPreparation":1'),
+      );
+    });
+
+    it('sets runningPreparation to 0 when no preparation issues exist', async () => {
+      const mockRunCommand = jest.fn();
+      const mockRunner: LocalCommandRunner = {
+        runCommand: mockRunCommand,
+      };
+
+      await writeSituationFile({
+        ...baseParams,
+        issues: [],
+        preparationProcessCheckCommand: 'pgrep -fa "{URL}"',
+        localCommandRunner: mockRunner,
+      });
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"runningPreparation":0'),
+      );
+      expect(mockRunCommand).not.toHaveBeenCalled();
+    });
+
+    it('sets runningPreparation to null when no localCommandRunner provided', async () => {
+      await writeSituationFile({
+        ...baseParams,
+        preparationProcessCheckCommand: 'pgrep -fa "{URL}"',
+      });
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"runningPreparation":null'),
+      );
+    });
+
+    it('sets runningPreparation to null when no preparationProcessCheckCommand', async () => {
+      await writeSituationFile({
+        ...baseParams,
+        preparationProcessCheckCommand: null,
+      });
+
+      expect(jest.mocked(fs.writeFileSync)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('"runningPreparation":null'),
+      );
+    });
+  });
+});

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

@@ -0,0 +1,168 @@
+import fs from 'fs';
+import type { Issue } from '../../../domain/entities/Issue';
+import type { LocalCommandRunner } from '../../../domain/usecases/adapter-interfaces/LocalCommandRunner';
+
+export type SituationFileParams = {
+  cachePath: string;
+  projectId: string;
+  issues: Issue[];
+  statusNames: {
+    awaitingQualityCheckStatus: string | null;
+    preparationStatus: string | null;
+    awaitingWorkspaceStatus: string | null;
+  };
+  config: {
+    maximumPreparingIssuesCount: number | null;
+    utilizationPercentageThreshold: number;
+    allowIssueCacheMinutes: number;
+    thresholdForAutoReject: number;
+  };
+  preparationProcessCheckCommand?: string | null;
+  localCommandRunner?: LocalCommandRunner;
+};
+
+type MeminfoValues = {
+  memTotalKb: number;
+  memAvailableKb: number;
+  swapTotalKb: number;
+  swapFreeKb: number;
+};
+
+export const parseMeminfo = (meminfo: string): MeminfoValues => {
+  const getValue = (key: string): number => {
+    const match = meminfo.match(new RegExp(`^${key}:\\s+(\\d+)`, 'm'));
+    return match ? parseInt(match[1], 10) : 0;
+  };
+  return {
+    memTotalKb: getValue('MemTotal'),
+    memAvailableKb: getValue('MemAvailable'),
+    swapTotalKb: getValue('SwapTotal'),
+    swapFreeKb: getValue('SwapFree'),
+  };
+};
+
+const kbToGib = (kb: number): number =>
+  Math.round((kb / 1024 / 1024) * 100) / 100;
+
+const toPercent = (used: number, total: number): number =>
+  total > 0 ? Math.round((used / total) * 1000) / 10 : 0;
+
+const isImmediatelyActionable = (issue: Issue): boolean =>
+  issue.dependedIssueUrls.length === 0 &&
+  issue.nextActionDate === null &&
+  issue.nextActionHour === null;
+
+const countRunningProcesses = async (
+  preparationIssues: Issue[],
+  commandTemplate: string,
+  localCommandRunner: LocalCommandRunner,
+): Promise<number> => {
+  const resolvedTemplate = commandTemplate.replace('{URL}', '$1');
+  const checks = await Promise.all(
+    preparationIssues.map(async (issue) => {
+      const { exitCode } = await localCommandRunner.runCommand('sh', [
+        '-c',
+        resolvedTemplate,
+        '--',
+        issue.url,
+      ]);
+      return exitCode === 0;
+    }),
+  );
+  return checks.filter(Boolean).length;
+};
+
+export const writeSituationFile = async (
+  params: SituationFileParams,
+): Promise<void> => {
+  const {
+    cachePath,
+    projectId,
+    issues,
+    statusNames,
+    config,
+    preparationProcessCheckCommand,
+    localCommandRunner,
+  } = params;
+
+  const awaitingQualityCheckImmediatelyActionable =
+    statusNames.awaitingQualityCheckStatus !== null
+      ? issues.filter(
+          (i) =>
+            i.status === statusNames.awaitingQualityCheckStatus &&
+            isImmediatelyActionable(i),
+        ).length
+      : 0;
+
+  const preparationIssues =
+    statusNames.preparationStatus !== null
+      ? issues.filter((i) => i.status === statusNames.preparationStatus)
+      : [];
+
+  const awaitingWorkspaceIssues =
+    statusNames.awaitingWorkspaceStatus !== null
+      ? issues.filter((i) => i.status === statusNames.awaitingWorkspaceStatus)
+      : [];
+
+  const awaitingWorkspaceImmediatelyActionable = awaitingWorkspaceIssues.filter(
+    isImmediatelyActionable,
+  ).length;
+
+  const awaitingWorkspaceBlockedByDependency = awaitingWorkspaceIssues.filter(
+    (i) => i.dependedIssueUrls.length > 0,
+  ).length;
+
+  let runningPreparation: number | null = null;
+  if (
+    preparationProcessCheckCommand &&
+    localCommandRunner &&
+    preparationIssues.length > 0
+  ) {
+    runningPreparation = await countRunningProcesses(
+      preparationIssues,
+      preparationProcessCheckCommand,
+      localCommandRunner,
+    );
+  } else if (preparationProcessCheckCommand && localCommandRunner) {
+    runningPreparation = 0;
+  }
+
+  const meminfo = fs.readFileSync('/proc/meminfo', 'utf-8');
+  const { memTotalKb, memAvailableKb, swapTotalKb, swapFreeKb } =
+    parseMeminfo(meminfo);
+
+  const memUsedKb = memTotalKb - memAvailableKb;
+  const swapUsedKb = swapTotalKb - swapFreeKb;
+
+  const situation = {
+    capturedAt: new Date().toISOString(),
+    config,
+    status: {
+      awaitingQualityCheckImmediatelyActionable,
+      preparation: preparationIssues.length,
+      awaitingWorkspaceImmediatelyActionable,
+      awaitingWorkspaceBlockedByDependency,
+    },
+    processes: {
+      runningPreparation,
+    },
+    system: {
+      memory: {
+        usedPercent: toPercent(memUsedKb, memTotalKb),
+        usedGib: kbToGib(memUsedKb),
+        totalGib: kbToGib(memTotalKb),
+      },
+      swap: {
+        usedPercent: toPercent(swapUsedKb, swapTotalKb),
+        usedGib: kbToGib(swapUsedKb),
+        totalGib: kbToGib(swapTotalKb),
+      },
+    },
+  };
+
+  const finalPath = `${cachePath}/situation-${projectId}.json`;
+  const tmpPath = `${finalPath}.tmp`;
+  fs.mkdirSync(cachePath, { recursive: true });
+  fs.writeFileSync(tmpPath, JSON.stringify(situation));
+  fs.renameSync(tmpPath, finalPath);
+};

package/src/adapter/repositories/GraphqlProjectRepository.ts

@@ -9,7 +9,11 @@ export class GraphqlProjectRepository
   implements
     Pick<
       ProjectRepository,
-      'getProject' | 'findProjectIdByUrl' | 'getByUrl' | 'updateStoryList'
+      | 'getProject'
+      | 'findProjectIdByUrl'
+      | 'getByUrl'
+      | 'updateStoryList'
+      | 'updateStatusList'
     >
 {
   extractProjectFromUrl = (
@@ -362,4 +366,54 @@ export class GraphqlProjectRepository
       }>();
     return response.data.updateProjectV2Field.projectV2Field.options;
   };
+  updateStatusList = async (
+    project: Project,
+    newStatusList: (Omit<FieldOption, 'id'> & {
+      id: FieldOption['id'] | null;
+    })[],
+  ): Promise<FieldOption[]> => {
+    const mutation = `mutation UpdateStatusOptions($fieldId: ID!, $options: [ProjectV2SingleSelectFieldOptionInput!]!) {
+  updateProjectV2Field(input: {
+    fieldId: $fieldId
+    singleSelectOptions: $options
+  }) {
+    projectV2Field {
+      ... on ProjectV2SingleSelectField {
+        options {
+          id
+          name
+          color
+          description
+        }
+      }
+    }
+  }
+}`;
+    const variables = {
+      fieldId: project.status.fieldId,
+      options: newStatusList.map(({ id, name, color, description }) => ({
+        ...(id !== null ? { id } : {}),
+        name,
+        color,
+        description,
+      })),
+    };
+    const response = await ky
+      .post('https://api.github.com/graphql', {
+        json: { query: mutation, variables },
+        headers: {
+          Authorization: `Bearer ${this.ghToken}`,
+        },
+      })
+      .json<{
+        data: {
+          updateProjectV2Field: {
+            projectV2Field: {
+              options: FieldOption[];
+            };
+          };
+        };
+      }>();
+    return response.data.updateProjectV2Field.projectV2Field.options;
+  };
 }

package/src/domain/entities/WorkflowStatus.ts

@@ -0,0 +1,41 @@
+import { FieldOption } from './Project';
+
+export const DEFAULT_STATUS_NAME = 'Unread';
+export const AWAITING_WORKSPACE_STATUS_NAME = 'Awaiting Workspace';
+export const PREPARATION_STATUS_NAME = 'Preparation';
+export const AWAITING_QUALITY_CHECK_STATUS_NAME = 'Awaiting Quality Check';
+export const DISABLED_STATUS_NAME = 'Disabled';
+
+export type WorkflowStatusDefinition = {
+  name: string;
+  color: FieldOption['color'];
+  description: string;
+};
+
+export const REQUIRED_WORKFLOW_STATUSES: WorkflowStatusDefinition[] = [
+  {
+    name: DEFAULT_STATUS_NAME,
+    color: 'GRAY',
+    description: 'Default fallback status for issues before triage',
+  },
+  {
+    name: AWAITING_WORKSPACE_STATUS_NAME,
+    color: 'YELLOW',
+    description: 'Issue is ready and waiting for an agent workspace',
+  },
+  {
+    name: PREPARATION_STATUS_NAME,
+    color: 'ORANGE',
+    description: 'Agent is preparing the issue',
+  },
+  {
+    name: AWAITING_QUALITY_CHECK_STATUS_NAME,
+    color: 'BLUE',
+    description: 'Awaiting human quality check',
+  },
+  {
+    name: DISABLED_STATUS_NAME,
+    color: 'GRAY',
+    description: 'Disabled and excluded from the active workflow',
+  },
+];