이랑이
5a64e26005
- install.sh: Node/pnpm 체크, git clone, 의존성, .env 생성, Prisma migrate, PM2 설정 자동화 --dev / --dir / --repo 옵션 지원, 범용 사용 가능 - SPRINT-001 스펙: SQLite → MariaDB + Prisma ORM 으로 전환 기존 Dev 서버 MariaDB(10.10.10.146:33006) 활용 - stack.md 규칙 갱신: better-sqlite3 → Prisma Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
97 lines
4.9 KiB
Markdown
97 lines
4.9 KiB
Markdown
# SPRINT-001 — 스켈레톤: XState FSM + orchestrator + CLI
|
|
|
|
> **목표**: 결정론적 파이프라인의 뼈대를 세운다. XState 머신이 메모리에서 돌고, MariaDB(Prisma) 에 상태가 저장되고, `rails status` CLI 로 조회 가능해야 한다.
|
|
|
|
## Type
|
|
`scaffold`
|
|
|
|
## Prerequisites
|
|
- Sprint 000 완료
|
|
- Node 22, pnpm 설치됨
|
|
- `.plans/design/state-machine.md` 확정
|
|
|
|
## Scope
|
|
|
|
- `package.json` / `tsconfig.json` (strict + noUncheckedIndexedAccess)
|
|
- Core 디렉토리 구조: `src/orchestrator/`, `src/contract/`, `src/cli/`, `tests/`
|
|
- XState v5 머신 정의 (`src/orchestrator/machine.ts`)
|
|
- Zod 이벤트/컨텍스트 스키마 (`src/orchestrator/events.ts`)
|
|
- Prisma schema + MariaDB migration (`prisma/schema.prisma`)
|
|
- citty CLI 뼈대 (`rails <subcommand>`)
|
|
- `rails start` — 빈 파이프라인 시작
|
|
- `rails status` — 현재 상태 표시
|
|
- `install.sh` — 원클릭 설치 스크립트 (Node/pnpm 체크 + clone + 빌드 + .env + PM2)
|
|
- `.env.example` — 환경변수 템플릿
|
|
- `ecosystem.config.cjs` — PM2 설정
|
|
- Vitest 테스트: 머신 상태 전이 단위 테스트 (성공 경로 1건 + 에러 경로 1건)
|
|
|
|
## Non-Goals
|
|
|
|
- 실제 자매 spawn (Sprint 004)
|
|
- Sprint Contract validator (Sprint 003)
|
|
- Skill enforcement hook 로직 (Sprint 002)
|
|
- 재시도 policy 실구현 (Sprint 005)
|
|
- QA runtime (Sprint 006)
|
|
- 디스코드 브릿지 (Sprint 004 또는 별도)
|
|
|
|
## Tasks
|
|
|
|
| # | 내용 | DoD | Depends | Status |
|
|
|---|---|---|---|---|
|
|
| 1.1 | `package.json` + `pnpm-lock.yaml` + 의존성 설치 | `pnpm install` 성공 | — | cc:TODO |
|
|
| 1.2 | `tsconfig.json` strict + noUncheckedIndexedAccess | `pnpm tsc --noEmit` 통과 | 1.1 | cc:TODO |
|
|
| 1.3 | 디렉토리 구조 생성 (`src/`, `tests/`, `fixtures/`) | `ls src/` 기대대로 | 1.1 | cc:TODO |
|
|
| 1.4 | `src/orchestrator/events.ts` — Zod 이벤트 스키마 | 타입체크 통과 | 1.2 | cc:TODO |
|
|
| 1.5 | `src/orchestrator/context.ts` — FSM context 타입 | 타입체크 통과 | 1.4 | cc:TODO |
|
|
| 1.6 | `src/orchestrator/machine.ts` — XState v5 머신 (stub actor) | `createActor` 성공 | 1.5 | cc:TODO |
|
|
| 1.7 | `prisma/schema.prisma` — MariaDB 스키마 (pipelines, state_transitions, actor_spawns, contracts) | `pnpm prisma migrate dev` 성공 | 1.1 | cc:TODO |
|
|
| 1.8 | `src/orchestrator/persist.ts` — FSM snapshot ↔ Prisma 변환 | snapshot round-trip 테스트 통과 | 1.6, 1.7 | cc:TODO |
|
|
| 1.9 | `src/cli/index.ts` — citty 진입점 | `pnpm rails --help` 출력 | 1.1 | cc:TODO |
|
|
| 1.10 | `src/cli/start.ts` — `rails start <projectName>` | 파이프라인 생성, ULID 반환 | 1.9, 1.8 | cc:TODO |
|
|
| 1.11 | `src/cli/status.ts` — `rails status [<id>]` | 현재 상태 표 출력 | 1.9, 1.8 | cc:TODO |
|
|
| 1.12 | `tests/machine.test.ts` — 성공 경로 + 에러 경로 | 2개 이상 pass | 1.6 | cc:TODO |
|
|
| 1.13 | `tests/store.test.ts` — snapshot round-trip (Prisma) | 1개 이상 pass | 1.8 | cc:TODO |
|
|
| 1.17 | `install.sh` — 원클릭 설치 스크립트 | bash install.sh --help 동작 | — | cc:완료 |
|
|
| 1.18 | `.env.example` + `ecosystem.config.cjs` | 파일 존재 | — | cc:TODO |
|
|
| 1.14 | `src/logger.ts` — pino 구조화 로거 + pipelineId 필드 | 로그 JSON 형식 확인 | 1.1 | cc:TODO |
|
|
| 1.15 | `src/env.ts` — Zod 검증 env | 환경변수 검증 실패 시 throw | 1.1 | cc:TODO |
|
|
| 1.16 | README 실행 방법 섹션 업데이트 | `## 실행 방법` 존재 | — | cc:TODO |
|
|
|
|
## Definition of Done
|
|
|
|
### 자동 검증 (contract validator)
|
|
- `pnpm install` exit 0
|
|
- `pnpm tsc --noEmit` exit 0
|
|
- `pnpm test` 전체 통과 (머신 + store 최소 3개)
|
|
- `pnpm rails --help` exit 0 + 출력에 `start`, `status` 포함
|
|
- `pnpm rails start test-project` → ULID 출력
|
|
- `pnpm rails status <id>` → `idle` 또는 `planning` 상태 표시
|
|
- MariaDB `hanarang_rails` DB 에 테이블 4개 생성 확인
|
|
- `package.json` lockfile 이 `pnpm-lock.yaml` (yarn/npm 아님)
|
|
|
|
### 수동 검증 (다랑이 manual)
|
|
- [ ] 아무 파일에도 `console.*` 호출 없음 (pino 사용)
|
|
- [ ] 아무 파일에도 `any` 타입 없음 (Zod 경계 제외)
|
|
- [ ] 모든 외부 입력에 Zod 검증 존재
|
|
- [ ] 에러 처리에 Result / neverthrow 또는 명시적 try/catch + 재던지기
|
|
- [ ] `.claude/rules/stack.md` 의 코딩 룰 전수 준수
|
|
|
|
## 환경 전제
|
|
|
|
- `node --version` ≥ 22
|
|
- `pnpm --version` ≥ 9
|
|
- `/home/erang/hanarang-rails/` 쓰기 권한
|
|
|
|
## Risks
|
|
|
|
- XState v5 + TypeScript strict + Zod 조합이 typegen 세팅 초기 삽질 가능 → **완화**: fixture 예제 따라하기
|
|
- better-sqlite3 네이티브 빌드 — Node 22 ABI 대응 필요 → **완화**: `@types/better-sqlite3` + build-from-source 옵션
|
|
- FSM snapshot round-trip 테스트가 XState 내부 구현 의존 → **완화**: public API (`getPersistedSnapshot` / `restore`) 만 사용
|
|
|
|
## Exit Criteria
|
|
|
|
- 모든 태스크 `cc:완료`
|
|
- `pnpm test` 전부 pass
|
|
- Plans.md 에서 SPRINT-001 Status 가 `cc:완료 [hash]`
|
|
- feature 브랜치 머지됨 (PR + 다랑이 QA)
|