preship 0.1.0

Preship: FastAPI 스테이징 URL을 퍼징해 터지는 입력과 패턴별 AI 수정 프롬프트를 내주는 출시 전 진단 CLI.

Preship

FastAPI 스테이징 앱을 출시 전에 자동으로 두드려, 터지는 입력과 고치는 법을 찾아주는 CLI 도구.

스테이징 URL 하나만 주면 모든 엔드포인트에 입력을 퍼징해서:

• 무엇이 터지는지 — 500 에러, 문서화 안 된 응답, 스키마 불일치를 패턴별로 묶어서 보여주고
• 어떻게 고치는지 — 그대로 복사해 당신이 쓰는 AI(ChatGPT·Claude·Gemini 등 아무거나)에 붙여넣을 수정 프롬프트를 패턴마다 1개씩 만들어 줍니다.

API 키 필요 없습니다. 결함을 찾고 수정 프롬프트를 받는 데까지 전부 키 없이 됩니다.

---

1. 설치

Python 3.10 이상이 필요합니다.

pip install preship

설치되면 preship 명령이 생깁니다.

preship --help

2. 스테이징 URL 준비 + 소유권 확인 라우트 달기

Preship은 당신이 소유한 URL만 스캔합니다 (남의 서버를 두드리지 못하게). 그래서 스캔 전에 "이 URL은 내 것"임을 한 번 증명해야 합니다 — 확인용 라우트 한 개를 앱에 다는 게 전부입니다.

먼저 스캔을 한 번 실행하면, Preship이 당신만의 토큰과 그대로 붙여넣을 라우트 코드를 출력해 줍니다. 그 토큰을 아래 스니펫에 끼워 앱에 추가하고 재배포하세요.

# 당신의 FastAPI 앱에 이 라우트 하나만 추가 (app = FastAPI() 아래 아무 곳)
from fastapi.responses import PlainTextResponse

@app.get("/.well-known/preflight-verify")
def preflight_verify():
    return PlainTextResponse("여기에 scan이 알려준 당신의 토큰을 붙여넣으세요")

토큰은 첫 스캔 실행이 정확히 알려주고, 라우트 코드도 함께 출력합니다. 추측할 필요 없이 출력된 걸 그대로 복사해 붙여넣으면 됩니다. (토큰은 URL마다 고정이라 한 번만 달면 됩니다.)

3. 스캔 실행

preship scan https://your-staging.example.com

스테이징에 인증이 걸려 있으면 헤더를 함께 넘기세요:

preship scan https://your-staging.example.com --header "Authorization: Bearer <토큰>"

4. 결과 읽는 법

출력은 두 부분입니다.

(1) 결함 리포트 — 같은 종류의 문제를 패턴으로 묶고, [HIGH](서버가 500으로 터짐) / [LOW](응답 계약 불일치)로 심각도를 표시합니다. 각 패턴마다 영향받는 엔드포인트 목록과 실제로 보냈던 요청 → 받은 응답이 따라옵니다.

(2) AI 수정 프롬프트 — 패턴마다 프롬프트 블록이 1개씩 나옵니다. 블록을 통째로 복사해 당신이 쓰는 AI에 그대로 붙여넣으면, 원인 추정 + FastAPI 수정 패치 + 설명을 받습니다. 프롬프트는 당신 소스 코드를 담지 않고(스캐너가 관측한 동작만), 특정 AI에 묶이지 않습니다.

받은 패치를 적용하고 다시 preship scan 하면 그 패턴이 사라졌는지 바로 확인할 수 있습니다.

---

고급 (선택): 자동 패치 초안

자동 패치 초안까지 원하면, 당신의 Anthropic API 키를 당신의 환경변수에 넣고 스캔하세요. 넣지 않아도 위의 수정 프롬프트는 그대로 나옵니다 — 키는 어디까지나 선택입니다.

export ANTHROPIC_API_KEY="sk-ant-..."   # 당신의 키. 베타 기본 경로는 키 없이 프롬프트만으로 충분합니다.
preship scan https://your-staging.example.com

---

개발 / 문서

설계 계약과 진행 기록은 docs/에 있습니다 — docs/S0_scope.md(범위), docs/S1_spec.md(데모 앱 스펙·채점 기준, 읽기 전용), docs/HANDOFF_LOG.md(빌드 로그). fixtures/는 테스트용 버그 앱 (제품 코드 아님).