Generative Tab Monorepo

generative-tab은 TV Generative Tab 프로토타입을 위한 monorepo입니다.

• apps/ui: Vue 3, Vite, TypeScript 기반 TV UI
• apps/server: FastAPI 서버, 페이지 생성 agent, SQLite 기반 페이지 catalog

빠른 시작

npm run setup
npm run dev

기본 로컬 포트:

• UI: http://localhost:5173
• Server: http://127.0.0.1:8000

개발 환경에서 UI는 브라우저에서 /fetch를 호출합니다. Vite dev server가 이 요청을 FastAPI 서버의 http://localhost:8000/fetch로 proxy합니다.

명령어

npm run setup         # npm 의존성 설치 및 apps/server/.venv 생성
npm run dev           # 서버와 UI를 함께 실행
npm run dev:server    # FastAPI 서버만 실행
npm run dev:ui        # Vite UI만 실행
npm run build         # UI 타입 검사 및 빌드
npm run test          # UI, 서버, root 도구 테스트 실행
npm run test:ui       # Vitest와 Playwright 실행
npm run test:server   # pytest 실행
npm run test:tools    # root Node 개발 도구 테스트 실행
npm run check         # 빌드와 전체 테스트 실행
npm run server:tools  # 서버 개발 TUI 실행(scripted flag가 있으면 CLI 실행)

협업용 worktree helper:

npm run git:hooks:install
npm run task:new -- --type feat --scope ui --slug topic-nav
npm run task:sync
npm run task:status
npm run task:finish
npm run task:cleanup -- --branch feat/ui-20260425-topic-nav
npm run task:auto:start -- --type feat --scope ui --slug topic-nav
npm run task:auto:finish

Task 명령 차이:

명령	실행 위치	역할
task:new	primary checkout의 main	새 요구사항/버그/기능 작업을 시작합니다. ../generative-tab-worktrees/<branch>에 worktree를 만들고, branch metadata와 requirements/changes/*.md task spec을 함께 생성합니다.
task:sync	task worktree	현재 task branch를 최신 main 기준으로 rebase합니다. 작업 중 main 변경을 받아올 때 사용합니다.
task:status	primary checkout 또는 task worktree	현재 branch가 등록된 task인지, worktree 경로가 맞는지, task spec이 있는지, worktree 상태가 깨끗한지 확인합니다.
task:finish	task worktree	현재 task branch의 커밋을 primary checkout의 main에 fast-forward로 반영합니다. worktree와 branch는 삭제하지 않으므로 이어서 작업할 수 있습니다.
task:cleanup	primary checkout	완전히 끝난 task의 worktree와 branch를 정리합니다. task:finish 이후에도 후속 작업 가능성이 없을 때만 실행합니다.
task:auto:start	primary checkout 또는 task worktree	Agent 요청 시작용 진입점입니다. 등록된 task worktree에서는 현재 작업을 이어가고, primary main에서는 직전 active task를 이어가거나 --type/--scope/--slug가 있으면 새 task를 만듭니다.
task:auto:finish	task worktree	Agent 요청 완료용 종료점입니다. 등록된 task worktree에서 task:finish를 실행해 primary main에 반영합니다.

AI agent 작업은 요청 시작 시 task:auto:start, 완료 시 commit 후 task:auto:finish를 실행하는 것을 기본으로 합니다. 직전 요청의 후속 작업이면 task:auto:start를 인자 없이 실행해 기존 active task를 재사용하고, 새로운 주제면 --type, --scope, --slug를 지정해 새 task를 만듭니다.

원격 저장소에는 작업 branch가 아니라 반영 완료된 main을 push합니다. Task worktree에서 commit 후 npm run task:auto:finish로 primary checkout의 main을 fast-forward한 다음, primary checkout에서 git push -u origin main을 실행합니다. 일반 작업에서는 git push -f origin main을 사용하지 않습니다.

서버 상호작용 확인용 helper는 root tools/gentab-dev-tool의 Node CLI/TUI로 실행합니다. 자세한 사용법은 tools/README.md를 참고합니다.

npm run server:tools:tui
npm run server:tools:cli -- --send --event-description "Team A match highlights tonight" --persona-json '{"role":"tester"}'
npm run server:tools:cli -- --once --output table

환경 변수

서버 비밀값은 apps/server/.env에 둡니다. apps/server/.env.example을 기준으로 값을 채우고, 실제 키는 Git에 포함하지 않습니다.

서버 앱 실행과 테스트 script는 apps/server 작업 디렉터리에서 실행합니다. server:tools는 root Node 도구를 실행하며 서버 Python venv에 의존하지 않습니다.

저장소 구조

• requirements/: UI와 서버를 통합한 feature별 요구사항
• docs/architecture.md: UI, 서버, agent, SQLite 간 런타임 흐름
• docs/collaboration.md: worktree 기반 협업 절차
• docs/ownership.md: shared file과 ownership 규칙
• AGENTS.md: coding agent를 위한 저장소 전체 작업 규칙