@jcjeon/integration-cli 0.2.0

package/apps/server/README.md

@@ -0,0 +1,294 @@
+# Integration CLI — Server
+
+멀티 에이전트 태스크 실행 백엔드. Claude / Gemini / Codex CLI를 오케스트레이션하고 결과를 WebSocket으로 스트리밍한다.
+
+## 기술 스택
+
+- **Framework**: NestJS 11, TypeScript 5
+- **Database**: SQLite (`~/.ji/ji.db`) via TypeORM 0.3
+- **WebSocket**: Socket.IO 4 (`/tasks`, `/agents/claude`, `/agents/gemini`)
+- **Agent CLI**: Claude Code CLI, Gemini CLI, Codex CLI (node-pty / spawn)
+- **Test**: Jest 30, ts-jest, @nestjs/testing
+
+---
+
+## 실행
+
+```bash
+npm install
+npm run dev          # watch mode (port 3001)
+npm run start:prod   # production
+```
+
+API 문서: `http://localhost:3001/docs` (Scalar UI)
+
+---
+
+## 테스트
+
+### 명령어
+
+```bash
+npm test             # 전체 단위 테스트
+npm run test:watch   # watch 모드
+npm run test:cov     # 커버리지 리포트 (coverage/ 디렉토리 생성)
+npm run test:e2e     # E2E 테스트
+```
+
+### 구성 개요
+
+```
+src/
+├── app.controller.spec.ts                          # 앱 루트 컨트롤러
+├── __mocks__/
+│   ├── uuid.js                                     # uuid v14 (ESM-only) CJS mock
+│   └── glob.js                                     # TypeORM DirectoryLoader glob mock
+└── modules/
+    ├── tasks/
+    │   ├── tasks.service.spec.ts                   # TasksService 단위 테스트
+    │   └── tasks.controller.spec.ts                # TasksController 단위 테스트
+    ├── conversations/
+    │   ├── conversation.service.spec.ts            # ConversationService 단위 테스트
+    │   └── conversation.controller.spec.ts         # ConversationController 단위 테스트
+    ├── sessions/
+    │   ├── session.service.spec.ts                 # SessionService 단위 테스트
+    │   └── session.controller.spec.ts              # SessionController 단위 테스트
+    ├── harness/
+    │   ├── harness.service.spec.ts                 # HarnessService 단위 테스트
+    │   └── harness.controller.spec.ts              # HarnessController 단위 테스트
+    └── changelog/
+        └── changelog.service.spec.ts               # GitChangelogService 단위 테스트
+```
+
+---
+
+## 테스트 상세
+
+### TasksService — `tasks.service.spec.ts` (29개)
+
+Repository 5개, `TaskExecutionService`, `GitChangelogService`를 모두 mock으로 교체한 순수 단위 테스트.
+
+| 그룹 | 시나리오 |
+|------|---------|
+| `findOne` | task 반환 / 미존재 시 `NotFoundException` |
+| `findAll` | `archived: false` 필터 + 최신순 정렬 |
+| `create` | 요구사항·에이전트 없음 / 요구사항 포함 / 에이전트 포함 / workingDir null |
+| `update` | title 변경 / 요구사항 교체 / 빈 배열로 전체 삭제 / 에이전트 교체 / 미존재 예외 |
+| `execute` | 정상 실행 → `spawnTask` 호출 / 이미 running 상태 → 재실행 없음 |
+| `rerun` | 에이전트 초기화 + 다음 버전 계산 / 실행 이력 없을 때 버전 1 / running 상태 → 재실행 없음 |
+| `stop` | `stopTask` 호출 + run 상태를 `stopped` 업데이트 |
+| `getRuns` | 버전 내림차순 반환 |
+| `archive` | `archived: true` 업데이트 / 미존재 예외 |
+| `remove` | `delete` 호출 |
+| `mergeAgentAll` | 전체 병합 / 에이전트 없음 예외 / `worktreePath` 없음 / `workingDir` 없으면 `process.cwd()` 사용 |
+| `mergeAgentFile` | 단일 파일 병합 / 에이전트 없음 예외 / `worktreePath` 없음 |
+
+```typescript
+// 실행 상태 확인 예시
+it('이미 running 상태이면 spawnTask를 호출하지 않는다', async () => {
+  taskRepo.findOne.mockResolvedValue({ ...baseTask, status: 'running' });
+  await service.execute('task-1');
+  expect(executionService.spawnTask).not.toHaveBeenCalled();
+});
+```
+
+---
+
+### TasksController — `tasks.controller.spec.ts` (13개)
+
+`TasksService`를 mock으로 교체. 컨트롤러가 올바른 인수로 서비스 메서드를 위임하는지 검증.
+
+| 메서드 | 검증 항목 |
+|--------|---------|
+| `POST /tasks` | `service.create(dto)` 위임 |
+| `GET /tasks` | `service.findAll()` 위임 |
+| `GET /tasks/:id` | `service.findOne(id)` 위임 |
+| `PATCH /tasks/:id` | `service.update(id, dto)` 위임 |
+| `POST /tasks/:id/execute` | `service.execute(id)` 위임 |
+| `POST /tasks/:id/stop` | `service.stop(id)` 위임 |
+| `POST /tasks/:id/rerun` | `service.rerun(id, supplementNote)` / `supplementNote` 없을 때 undefined 전달 |
+| `GET /tasks/:id/runs` | `service.getRuns(id)` 위임 |
+| `POST /tasks/:id/archive` | `service.archive(id)` 위임 |
+| `POST /tasks/:id/agents/:agentId/merge` | `agentId`를 `Number`로 변환 후 위임 |
+| `POST /tasks/:id/agents/:agentId/merge-file` | `filePath` + `Number(agentId)` 위임 |
+| `DELETE /tasks/:id` | `service.remove(id)` 위임 |
+
+---
+
+### ConversationService — `conversation.service.spec.ts` (14개)
+
+`ConversationEntity` Repository를 mock으로 교체.
+
+| 그룹 | 시나리오 |
+|------|---------|
+| `create` | 기본 메시지 저장 / `agentId` + `runId` 포함 저장 |
+| `findBySession` | `sessionId` 필터 + ASC 정렬 / 빈 결과 |
+| `findByRun` | `runId` 필터 + ASC 정렬 |
+| `findOne` | ID 조회 / 미존재 `NotFoundException` |
+| `remove` | 조회 후 삭제 / 미존재 `NotFoundException` |
+| `removeBySession` | `sessionId` 기준 전체 삭제 |
+
+---
+
+### ConversationController — `conversation.controller.spec.ts` (5개)
+
+`ConversationService` mock. 각 엔드포인트 위임 검증.
+
+| 엔드포인트 | 검증 |
+|-----------|------|
+| `POST /conversations` | `service.create(dto)` |
+| `GET /conversations/session/:sessionId` | `service.findBySession(sessionId)` |
+| `GET /conversations/:id` | `service.findOne(id)` |
+| `DELETE /conversations/:id` | `service.remove(id)` |
+| `DELETE /conversations/session/:sessionId` | `service.removeBySession(sessionId)` |
+
+---
+
+### SessionService — `session.service.spec.ts` (7개)
+
+`SessionEntity` Repository mock.
+
+| 그룹 | 시나리오 |
+|------|---------|
+| `findAll` | 전체 최신순 / `agentType: 'claude'` 필터 / `agentType: 'gemini'` 필터 / 빈 결과 |
+| `findOne` | `sessionId` 조회 / 미존재 `NotFoundException` (메시지 포함) |
+
+---
+
+### SessionController — `session.controller.spec.ts` (3개)
+
+`SessionService` mock. `agentType` query param 유무 모두 검증.
+
+---
+
+### HarnessService — `harness.service.spec.ts` (17개)
+
+`fs` 모듈 전체를 `jest.mock('fs')`로 교체. 파일시스템 접근을 직접 제어.
+
+| 그룹 | 시나리오 |
+|------|---------|
+| `findAll` | 존재하는 파일만 수집 / 없으면 빈 배열 / `md` → `tsx` 순서로 탐색 |
+| `findOne` | `.md` 파일 반환 / `.tsx` 파일 반환 / 없으면 null / `readFileSync` utf8 호출 확인 |
+| `save` | `.md` 저장 / `.tsx` 저장 / 확장자 변경 시 기존 파일 삭제 / 다른 확장자 없으면 삭제 안 함 |
+| `remove` | `.md` 삭제 / `.tsx` 삭제 / 두 파일 모두 존재하면 둘 다 삭제 / 없으면 삭제 안 함 |
+
+```typescript
+// 확장자 변경 처리 예시
+it('확장자 변경 시 기존 파일을 삭제한다', () => {
+  const oldPath = path.join(harnessDir, 'common.tsx');
+  (fs.existsSync as jest.Mock).mockImplementation((p) => p === oldPath);
+
+  service.save('common', 'content', 'md'); // tsx → md로 변경
+
+  expect(fs.unlinkSync).toHaveBeenCalledWith(oldPath);
+});
+```
+
+---
+
+### HarnessController — `harness.controller.spec.ts` (6개)
+
+`HarnessService` mock. `findOne`이 null 반환 시 기본값(`{ role, ext: 'md', content: '' }`) 반환 검증 포함.
+
+---
+
+### GitChangelogService — `changelog.service.spec.ts` (30개)
+
+`child_process`(`execSync`, `execFileSync`)와 `fs`를 모두 mock. private 메서드 `parseDiff`는 `(service as any).parseDiff()`로 직접 접근.
+
+| 그룹 | 시나리오 |
+|------|---------|
+| `isGitRepo` | git repo 확인 (`true`) / 아닐 때 (`false`) |
+| `getCurrentHead` | HEAD SHA 반환 + trim |
+| `getCurrentBranch` | 브랜치명 반환 / 특수문자 → `-` 치환 + 40자 자름 / 에러 → `'unknown'` |
+| `getRepoRoot` | `--show-toplevel` 결과 반환 |
+| `mergeAll` | 전체 병합 성공 / worktree 없음 실패 / 충돌 시 `false` + abort 시도 |
+| `mergeFile` | 단일 파일 병합 성공 / worktree 없음 실패 / checkout 실패 → 에러 메시지 |
+| `getLatestRunId` | 최근 runId 반환 / 없으면 null |
+| `getByTask` | 에이전트별 그룹핑 / runId 직접 지정 / 없으면 빈 배열 |
+| `parseDiff` | `modified` 파일 / `added` 파일 / `deleted` 파일 / `renamed` 파일 / 멀티파일 / 빈 diff / 200KB 초과 truncation / `+++`·`---` 헤더 카운트 제외 |
+| `captureAndSave` | 변경사항 있음 → DB 저장 + SHA 반환 / 없음 → DB 미저장 / 에러 → null |
+| `mergeToMain` | merge 성공 / 충돌 → abort 후 예외 미전파 |
+
+```typescript
+// parseDiff truncation 예시
+it('200KB 초과 patch는 truncated 처리한다', () => {
+  const longContent = '+' + 'x'.repeat(210_000);
+  // ...
+  expect(result[0].patch).toContain('(truncated)');
+});
+```
+
+---
+
+## Jest 설정 (`package.json`)
+
+```json
+"jest": {
+  "rootDir": "src",
+  "testRegex": ".*\\.spec\\.ts$",
+  "transform": { "^.+\\.(t|j)s$": "ts-jest" },
+  "moduleNameMapper": {
+    "^uuid$": "<rootDir>/__mocks__/uuid.js",
+    "^glob$": "<rootDir>/__mocks__/glob.js"
+  },
+  "coverageDirectory": "../coverage"
+}
+```
+
+### `__mocks__/uuid.js`
+
+uuid v14는 ESM-only 패키지여서 Jest(CJS)에서 직접 import 시 파싱 에러 발생. `jest.fn()`으로 감싼 CJS mock으로 대체.
+
+### `__mocks__/glob.js`
+
+TypeORM v0.3이 로드될 때 `DirectoryExportedClassesLoader`가 `glob`을 통해 `path-scurry`(ESM)를 불러온다. 단위 테스트에서는 디렉터리 스캔이 필요 없으므로 no-op mock으로 차단.
+
+### `tsconfig.json`
+
+`"isolatedModules": true` — ts-jest가 각 파일을 독립적으로 트랜스파일. 타입 체크를 생략해 테스트 속도를 높이고 NodeNext 모듈 해석의 부작용을 방지.
+
+---
+
+## 커버리지 현황
+
+> `npm run test:cov` 실행 기준
+
+| 모듈 | Statements | Branches | Functions | Lines |
+|------|-----------|----------|-----------|-------|
+| `tasks/tasks.service.ts` | 99% | 85% | 100% | 100% |
+| `tasks/tasks.controller.ts` | 100% | 75% | 100% | 100% |
+| `conversations/conversation.service.ts` | 100% | 83% | 100% | 100% |
+| `conversations/conversation.controller.ts` | 100% | 75% | 100% | 100% |
+| `sessions/session.service.ts` | 100% | 88% | 100% | 100% |
+| `sessions/session.controller.ts` | 100% | 75% | 100% | 100% |
+| `harness/harness.service.ts` | 100% | 100% | 100% | 100% |
+| `harness/harness.controller.ts` | 100% | 80% | 100% | 100% |
+| `changelog/changelog.service.ts` | 85% | 81% | 87% | 85% |
+
+**미커버 영역**: `task-execution.service.ts`, `*.gateway.ts`, 에이전트 모듈(`claude/`, `gemini/`, `codex/`) — CLI 서브프로세스·PTY 세션 의존으로 단위 테스트 제외. 통합/E2E 테스트 대상.
+
+---
+
+## 테스트 전략
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  단위 테스트 (현재)                                        │
+│  Service / Controller — Repository·외부 의존 전부 mock    │
+├─────────────────────────────────────────────────────────┤
+│  통합 테스트 (미구현)                                      │
+│  실제 SQLite in-memory DB + TypeORM                      │
+│  대상: TasksService CRUD, ConversationService            │
+├─────────────────────────────────────────────────────────┤
+│  E2E 테스트 (test/app.e2e-spec.ts)                       │
+│  실 서버 기동 + supertest HTTP 요청                        │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Mock 원칙
+
+- **Repository**: `create / save / findOne / find / update / delete`를 `jest.fn()`으로 교체
+- **ExternalProcess (`task-execution.service`)**: `jest.mock('./task-execution.service', () => ...)` 으로 모듈 레벨 대체 — CLI 프로세스를 실제로 실행하지 않음
+- **Git CLI (`child_process`)**: `execSync` / `execFileSync`를 `jest.Mock`으로 교체
+- **FileSystem (`fs`)**: `jest.mock('fs')`로 전체 대체 — 실 파일시스템 접근 없음

package/apps/server/eslint.config.mjs

@@ -0,0 +1,20 @@
+/*
+ * @Author: 전지창
+ * @Date: 2026-05-04 17:17:33
+ * @LastEditTime: 2026-05-04 17:21:47
+ * @LastEditors: 전지창
+ * @Description:
+ */
+import nestConfig from "@ji/eslint-config/nest";
+
+export default [
+  ...nestConfig,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: path.join(import.meta.dirname, ".."),
+      },
+    },
+  },
+];

package/apps/server/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/apps/server/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@ji/server",
+  "version": "0.0.1",
+  "private": true,
+  "license": "UNLICENSED",
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "build": "nest build",
+    "dev": "nest start --watch",
+    "start": "nest start",
+    "start:debug": "nest start --debug --watch",
+    "start:prod": "node dist/main",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "lint:fix": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:e2e": "jest --config ./test/jest-e2e.json",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/platform-express": "^11.0.1",
+    "@nestjs/platform-socket.io": "^11.1.19",
+    "@nestjs/swagger": "^11.4.3",
+    "@nestjs/typeorm": "^11.0.1",
+    "@nestjs/websockets": "^11.1.19",
+    "@scalar/nestjs-api-reference": "^1.1.16",
+    "better-sqlite3": "^12.9.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "node-pty": "^1.1.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "socket.io": "^4.8.3",
+    "typeorm": "^0.3.29",
+    "uuid": "^14.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@ji/eslint-config": "*",
+    "@ji/typescript-config": "*",
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.1",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.0",
+    "@types/supertest": "^7.0.0",
+    "@types/uuid": "^10.0.0",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.2.2",
+    "globals": "^17.0.0",
+    "jest": "^30.0.0",
+    "source-map-support": "^0.5.21",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "ts-loader": "^9.5.2",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "moduleNameMapper": {
+      "^uuid$": "<rootDir>/__mocks__/uuid.js",
+      "^glob$": "<rootDir>/__mocks__/glob.js"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  }
+}

package/apps/server/scripts/postinstall.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// ~/.ji 데이터 디렉토리 생성
+const dataDir = path.join(os.homedir(), '.ji');
+if (!fs.existsSync(dataDir)) {
+  fs.mkdirSync(dataDir, { recursive: true });
+  console.log(`[ji] Created data directory: ${dataDir}`);
+}
+
+// better-sqlite3 네이티브 모듈 확인 및 빌드
+function isSqliteLoadable() {
+  try {
+    require('better-sqlite3');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (!isSqliteLoadable()) {
+  console.log('[ji] Building better-sqlite3 for your platform...');
+
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const result = spawnSync(npm, ['rebuild', 'better-sqlite3'], {
+    stdio: 'inherit',
+    cwd: path.join(__dirname, '..'),
+    shell: false,
+  });
+
+  if (result.status !== 0) {
+    console.error(
+      '\n[ji] ⚠️  better-sqlite3 build failed.\n' +
+        '  SQLite requires native build tools (node-gyp).\n' +
+        '  Install them and retry:\n\n' +
+        '    Windows : npm install --global windows-build-tools\n' +
+        '    macOS   : xcode-select --install\n' +
+        '    Linux   : sudo apt-get install build-essential python3\n\n' +
+        '  Then run: npm rebuild better-sqlite3\n' +
+        '  See: https://github.com/nodejs/node-gyp#installation\n',
+    );
+    // 빌드 실패해도 설치 자체는 중단하지 않음 (경고만 출력)
+  } else {
+    console.log('[ji] better-sqlite3 built successfully.');
+  }
+} else {
+  console.log('[ji] better-sqlite3 is ready.');
+}

package/apps/server/src/__mocks__/glob.js

@@ -0,0 +1,6 @@
+// glob을 mock하여 typeorm의 DirectoryExportedClassesLoader가 path-scurry(ESM)를 로드하지 못하도록 방지
+module.exports = {
+  glob: jest.fn().mockResolvedValue([]),
+  globSync: jest.fn().mockReturnValue([]),
+  sync: jest.fn().mockReturnValue([]),
+};

package/apps/server/src/__mocks__/uuid.js

@@ -0,0 +1,5 @@
+let counter = 0;
+
+module.exports = {
+  v4: jest.fn(() => `mock-uuid-${++counter}`),
+};

package/apps/server/src/app.controller.spec.ts

@@ -0,0 +1,24 @@
+import type { TestingModule } from '@nestjs/testing';
+import { Test } from '@nestjs/testing';
+
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+
+describe('AppController', () => {
+  let appController: AppController;
+
+  beforeEach(async () => {
+    const app: TestingModule = await Test.createTestingModule({
+      controllers: [AppController],
+      providers: [AppService],
+    }).compile();
+
+    appController = app.get<AppController>(AppController);
+  });
+
+  describe('root', () => {
+    it('should return "Hello World!"', () => {
+      expect(appController.getHello()).toBe('Hello World!');
+    });
+  });
+});

package/apps/server/src/app.controller.ts

@@ -0,0 +1,13 @@
+import { Controller, Get } from '@nestjs/common';
+
+import { AppService } from './app.service';
+
+@Controller()
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Get()
+  getHello(): string {
+    return this.appService.getHello();
+  }
+}

package/apps/server/src/app.module.ts

@@ -0,0 +1,18 @@
+import { Module } from '@nestjs/common';
+
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { DatabaseModule } from './database/database.module';
+import { AgentsModule } from './modules/agents/agents.module';
+import { ConversationModule } from './modules/conversations/conversation.module';
+import { FsModule } from './modules/fs/fs.module';
+import { HarnessModule } from './modules/harness/harness.module';
+import { SessionModule } from './modules/sessions/session.module';
+import { TasksModule } from './modules/tasks/tasks.module';
+
+@Module({
+  imports: [DatabaseModule, AgentsModule, ConversationModule, FsModule, HarnessModule, SessionModule, TasksModule],
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}

package/apps/server/src/app.service.ts

@@ -0,0 +1,8 @@
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class AppService {
+  getHello(): string {
+    return 'Hello World!';
+  }
+}

package/apps/server/src/common/ji-paths.ts

@@ -0,0 +1,41 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+export const JI_HOME = path.join(os.homedir(), '.ji');
+
+export const JI_PATHS = {
+  home:        JI_HOME,
+  db:          path.join(JI_HOME, 'ji.db'),
+  logs:        path.join(JI_HOME, 'logs'),
+  serverLog:   path.join(JI_HOME, 'logs', 'server.log'),
+  worktrees:   path.join(JI_HOME, 'worktrees'),
+  patches:     path.join(JI_HOME, 'patches'),
+  harness:     path.join(JI_HOME, 'harness'),
+  agents: {
+    gemini: {
+      dir:      path.join(JI_HOME, 'agents', 'gemini'),
+      apiKey:   path.join(JI_HOME, 'agents', 'gemini', 'api-key'),
+      settings: path.join(JI_HOME, 'agents', 'gemini', 'settings.json'),
+    },
+    codex: {
+      dir:    path.join(JI_HOME, 'agents', 'codex'),
+      apiKey: path.join(JI_HOME, 'agents', 'codex', 'api-key'),
+    },
+  },
+} as const;
+
+export function ensureJiDirs(): void {
+  const dirs = [
+    JI_PATHS.home,
+    JI_PATHS.logs,
+    JI_PATHS.worktrees,
+    JI_PATHS.patches,
+    JI_PATHS.harness,
+    JI_PATHS.agents.gemini.dir,
+    JI_PATHS.agents.codex.dir,
+  ];
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+}

package/apps/server/src/database/database.module.ts

@@ -0,0 +1,27 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { ensureJiDirs, JI_PATHS } from '../common/ji-paths';
+import { AgentChangelogEntity } from './entities/agent-changelog.entity';
+import { AgentSessionEntity } from './entities/agent-session.entity';
+import { ConversationEntity } from './entities/conversation.entity';
+import { SessionEntity } from './entities/session.entity';
+import { TaskAgentEntity } from './entities/task-agent.entity';
+import { TaskAgentRunEntity } from './entities/task-agent-run.entity';
+import { TaskRequirementEntity } from './entities/task-requirement.entity';
+import { TaskEntity } from './entities/task.entity';
+import { TaskRunEntity } from './entities/task-run.entity';
+
+ensureJiDirs();
+
+@Module({
+  imports: [
+    TypeOrmModule.forRoot({
+      type: 'better-sqlite3',
+      database: JI_PATHS.db,
+      entities: [SessionEntity, AgentSessionEntity, ConversationEntity, TaskEntity, TaskRequirementEntity, TaskAgentEntity, TaskRunEntity, TaskAgentRunEntity, AgentChangelogEntity],
+      synchronize: true,
+    }),
+  ],
+})
+export class DatabaseModule {}

package/apps/server/src/database/entities/agent-changelog.entity.ts

@@ -0,0 +1,39 @@
+import { Column, CreateDateColumn, Entity, PrimaryGeneratedColumn } from 'typeorm';
+
+export type ChangeType = 'added' | 'modified' | 'deleted' | 'renamed';
+
+@Entity('agent_changelogs')
+export class AgentChangelogEntity {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column('text')
+  taskId!: string;
+
+  @Column('integer')
+  agentId!: number;
+
+  @Column('integer', { nullable: true })
+  runId!: number | null;
+
+  @Column('text')
+  filePath!: string;
+
+  @Column('text')
+  changeType!: ChangeType;
+
+  @Column('text', { nullable: true })
+  patch!: string | null;
+
+  @Column('text', { nullable: true })
+  patchPath!: string | null;
+
+  @Column('integer', { default: 0 })
+  additions!: number;
+
+  @Column('integer', { default: 0 })
+  deletions!: number;
+
+  @CreateDateColumn()
+  createdAt!: Date;
+}