Metadata-Version: 2.4
Name: preship
Version: 0.1.0
Summary: Preship: FastAPI 스테이징 URL을 퍼징해 터지는 입력과 패턴별 AI 수정 프롬프트를 내주는 출시 전 진단 CLI.
Author: Preship
License: Proprietary
Keywords: fastapi,testing,fuzzing,openapi,api,preflight
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: schemathesis==4.20.3
Requires-Dist: anthropic==0.105.2

# Preship

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

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

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

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

---

## 1. 설치

Python 3.10 이상이 필요합니다.

```bash
pip install preship
```

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

```bash
preship --help
```

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

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

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

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

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

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

## 3. 스캔 실행

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

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

```bash
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 키를 **당신의** 환경변수에 넣고 스캔하세요.
넣지 않아도 위의 수정 프롬프트는 그대로 나옵니다 — 키는 어디까지나 선택입니다.

```bash
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/`는 테스트용 버그 앱
(제품 코드 아님).
