preship 0.1.0__tar.gz

preship-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+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/`는 테스트용 버그 앱
+(제품 코드 아님).

preship-0.1.0/README.md

@@ -0,0 +1,93 @@
+# 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/`는 테스트용 버그 앱
+(제품 코드 아님).

preship-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "preship"
+version = "0.1.0"
+description = "Preship: FastAPI 스테이징 URL을 퍼징해 터지는 입력과 패턴별 AI 수정 프롬프트를 내주는 출시 전 진단 CLI."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "Preship" }]
+keywords = ["fastapi", "testing", "fuzzing", "openapi", "api", "preflight"]
+# CLI 런타임 의존은 schemathesis 하나(core가 동일 venv의 schemathesis 콘솔 스크립트를 서브프로세스로 구동).
+# fastapi/uvicorn 등은 데모 타깃 실행용으로 requirements.txt에 유지.
+dependencies = ["schemathesis==4.20.3", "anthropic==0.105.2"]
+
+# 홈페이지/URL: 레포 private — 공개 랜딩 페이지(베타-1) 확정 후 추가 예정.
+
+[project.scripts]
+preship = "ohs_preflight.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

preship-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

preship-0.1.0/src/ohs_preflight/__init__.py

@@ -0,0 +1,3 @@
+"""preship — FastAPI staging URL을 schemathesis로 스캔해 결함 리스트를 출력하는 CLI 골격 (S2)."""
+
+__version__ = "0.1.0"

preship-0.1.0/src/ohs_preflight/cli.py

@@ -0,0 +1,254 @@
+"""사람용 CLI: `preship scan <URL>`.
+
+core.scan()이 돌려준 list[Finding]를 사람이 읽게 포맷해 출력한다(문자열 직박기 아님).
+기계용(JSON) 출력·패치 생성은 S3 — 여기 없다.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from collections import OrderedDict
+
+from ohs_preflight.core import Finding, ScanError, scan
+from ohs_preflight.patch import Diagnosis, generate_patches, has_api_key
+from ohs_preflight.verify import WELL_KNOWN_PATH, VerificationResult, WellKnownVerifier
+
+
+# A(c): 같은 체크가 여러 엔드포인트에서 반복되면 "패턴 1 × N 위치"로 묶어 출력.
+# 정적(canned) 일괄수정 방향 — AI 생성 아님(S3.5 프롬프트와 무관).
+_FIX_HINT = {
+    "not_a_server_error": "입력 검증·예외 처리로 500 제거(타입 강화·가드·표준 예외).",
+    "status_code_conformance": "반환하는 상태코드를 라우트 responses={코드: {...}}에 문서화.",
+    "response_schema_conformance": "응답이 선언된 response_model 스키마를 충족하게(모델 인스턴스 반환).",
+    "content_type_conformance": "선언된 content-type(application/json 등)에 응답을 맞춤.",
+}
+
+# S3.5(a): 패턴별 평문 문제 설명 — 외부 AI에 붙여넣을 프롬프트의 ①문제 문장.
+# 진단 분류(관측된 동작)만 서술 — 유저 소스를 모르므로 원인은 상상하지 않는다.
+_PROBLEM = {
+    "not_a_server_error": "아래 엔드포인트들이 특정 입력에서 처리되지 않은 예외로 서버 500을 반환합니다.",
+    "status_code_conformance": "아래 엔드포인트들이 OpenAPI에 문서화되지 않은 상태코드를 반환합니다.",
+    "response_schema_conformance": "아래 엔드포인트들의 응답 본문이 선언된 response_model 스키마를 충족하지 않습니다.",
+    "content_type_conformance": "아래 엔드포인트들이 선언된 content-type과 다른 형식으로 응답합니다.",
+}
+
+
+def _group_by_pattern(findings: list[Finding]) -> "list[tuple[str, list[Finding]]]":
+    """결함을 체크(패턴)별로 묶고 high 패턴 먼저 정렬해 반환.
+
+    _format(사람용 리포트)와 _format_prompts(붙여넣기용 프롬프트)가 공유 —
+    "패턴 1개 = 그룹 1개" 단위를 한 군데서만 정의한다.
+    """
+    patterns: "OrderedDict[str, list[Finding]]" = OrderedDict()
+    for f in findings:
+        patterns.setdefault(f.check, []).append(f)
+    # high 패턴 먼저, low 뒤(그룹 내 첫 Finding의 level 기준; 그 외 등장 순서 유지)
+    return sorted(patterns.items(), key=lambda kv: 0 if kv[1][0].level == "high" else 1)
+
+
+def _format(findings: list[Finding]) -> str:
+    if not findings:
+        return "✓ 결함 없음 (No issues found).\n"
+
+    ordered = _group_by_pattern(findings)
+    patterns = dict(ordered)
+
+    n_ep = len({(f.method, f.path) for f in findings})
+    lines = [
+        f"결함 {len(findings)}건 / 패턴 {len(patterns)}개 / 엔드포인트 {n_ep}개 "
+        "(severity: high 먼저):\n"
+    ]
+    for check, group in ordered:
+        level = group[0].level
+        endpoints = sorted({f"{f.method} {f.path}" for f in group})
+        lines.append(f"[{level.upper()}] {check} — {len(endpoints)}개 엔드포인트")
+        hint = _FIX_HINT.get(check)
+        if hint:
+            lines.append(f"  일괄 수정 방향: {hint}")
+        lines.append("  영향 엔드포인트:")
+        for ep in endpoints:
+            lines.append(f"    - {ep}")
+        rep = group[0]
+        trig = rep.trigger if len(rep.trigger) <= 160 else rep.trigger[:160] + "…"
+        lines.append(f"  대표 예: {trig}  →  {rep.response_summary}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+# S3.5: scan 출력에 한 줄 고지. 추후 방향 전환(자동패치 유료화 등) 시 "베타였고 공지함" 근거.
+_BETA_NOTICE = (
+    "베타: AI 수정 프롬프트를 무료 제공합니다. 정식 출시 시 기능·정책이 변경될 수 있습니다."
+)
+
+
+def _format_prompts(findings: list[Finding]) -> str:
+    """패턴(체크)별로 외부 AI에 그대로 붙여넣을 프롬프트를 텍스트로 조립한다.
+
+    **LLM을 부르지 않는다** — 이미 정제된 Finding을 텍스트로 조립만 한다(비용 0·결정론).
+    패턴 1개 = 프롬프트 1개(_group_by_pattern과 동일 단위). 야생 앱의 "같은 패턴 × N
+    엔드포인트"가 자연스럽게 프롬프트 1개로 묶인다.
+
+    제약(★): 유저 소스를 모르므로 코드를 상상하지 않고(〈유저의 핸들러〉 placeholder)
+    관측된 진단정보(요청 트리거·응답 요약)만 담는다. 특정 AI를 지칭하지 않는다(모델 중립).
+    """
+    if not findings:
+        return ""
+
+    bar = "=" * 64
+    sep = "─" * 64
+    ordered = _group_by_pattern(findings)
+    out = [
+        "",
+        bar,
+        "AI 수정 프롬프트 — 키 없이 무료 · 외부 AI에 붙여넣기 (S3.5 · 베타)",
+        _BETA_NOTICE,
+        bar,
+        "각 패턴마다 아래 프롬프트 블록을 통째로 복사해, 쓰는 AI(아무거나)에 붙여넣으세요.",
+        "",
+    ]
+    for i, (check, group) in enumerate(ordered, start=1):
+        level = group[0].level
+        endpoints = sorted({f"{f.method} {f.path}" for f in group})
+        problem = _PROBLEM.get(check, f"아래 엔드포인트들에서 '{check}' 위반이 관측되었습니다.")
+
+        out.append(sep)
+        out.append(f"[프롬프트 {i}/{len(ordered)}] [{level.upper()}] {check} · {len(endpoints)}개 엔드포인트")
+        out.append(sep)
+        # ④ 지시(모델 중립) + 소스 상상 금지 안내
+        out.append(
+            "당신은 FastAPI 전문가입니다. 아래 진단 정보만 근거로 일괄 수정 패치를 만들어 주세요. "
+            "핸들러 소스는 제공되지 않습니다(각 핸들러는 〈유저의 핸들러〉). "
+            "코드를 상상하지 말고, 관측된 동작만으로 원인을 추정해 수정하세요."
+        )
+        out.append("")
+        # ① 문제(평문)
+        out.append(f"[문제] {problem}")
+        out.append("")
+        # ② 영향 엔드포인트 목록
+        out.append("[영향 엔드포인트]")
+        for ep in endpoints:
+            out.append(f"  - {ep}")
+        out.append("")
+        # ③ 관측된 동작(엔드포인트별 요청 트리거 → 응답 요약) — 진단정보만
+        out.append("[관측된 동작] (스캐너가 실제로 보낸 요청 → 받은 응답)")
+        for f in group:
+            trig = f.trigger if len(f.trigger) <= 200 else f.trigger[:200] + "…"
+            out.append(f"  - 요청: {trig}")
+            out.append(f"    응답: {f.response_summary}")
+        out.append("")
+        # ④ 산출물 지시
+        out.append("[해줄 것]")
+        out.append("  1. 각 엔드포인트에서 이 동작이 나온 원인을 추정하고,")
+        out.append("  2. FastAPI 관용구에 맞는 일괄 수정 패치(수정 코드 또는 diff)를 제시하고,")
+        out.append("  3. 각 수정이 왜 문제를 해결하는지 설명해 주세요.")
+        out.append("")
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="preship",
+        description="FastAPI 스테이징 URL을 schemathesis로 스캔해 결함을 출력한다.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    scan_p = sub.add_parser("scan", help="FastAPI URL을 스캔한다.")
+    scan_p.add_argument("url", help="FastAPI 베이스 URL (여기서 /openapi.json 수집).")
+    scan_p.add_argument(
+        "--header",
+        action="append",
+        default=[],
+        metavar='"Name: Value"',
+        help='모든 요청에 실을 헤더(반복 가능). 예: --header "Authorization: Bearer ..."',
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    if args.command == "scan":
+        # 소유권 게이트: 미검증이면 scan·openapi·LLM 등 어떤 외부 요청도 내보내지 않는다.
+        verification = WellKnownVerifier().verify(args.url, headers=args.header)
+        if not verification.verified:
+            sys.stdout.write(_format_rejection(args.url, verification))
+            return 3
+        try:
+            findings = scan(args.url, headers=args.header)
+        except ScanError as exc:
+            print(f"scan 실패: {exc}", file=sys.stderr)
+            return 2
+        sys.stdout.write(_format(findings))
+        # S3.5: 결함 리포트 그다음에 패턴별 AI 수정 프롬프트(텍스트 조립만, LLM 호출 0).
+        sys.stdout.write(_format_prompts(findings))
+        _maybe_patch(findings, args)
+        return 1 if findings else 0
+    return 0
+
+
+def _maybe_patch(findings: list[Finding], args) -> None:
+    """결함이 있고 키가 있으면 패치를 생성·출력. 키 없으면 안내만(scan은 이미 출력됨)."""
+    if not findings:
+        return
+    if not has_api_key():
+        sys.stdout.write(
+            "\nℹ️  ANTHROPIC_API_KEY를 설정하면 결함별 설명·원인·FastAPI 패치를 생성합니다 "
+            "(BYOK). 스캔은 키 없이도 동작합니다.\n"
+        )
+        return
+    try:
+        diagnoses = generate_patches(findings, args.url, headers=args.header)
+    except Exception as exc:  # noqa: BLE001 — 스캔 결과는 이미 출력됨; 패치 단계만 graceful 실패
+        print(f"\n패치 생성 단계 실패(스캔 결과는 위와 같음): {type(exc).__name__}", file=sys.stderr)
+        return
+    sys.stdout.write(_format_patches(diagnoses))
+
+
+def _format_patches(diagnoses: list[Diagnosis]) -> str:
+    bar = "=" * 64
+    lines = ["", bar, "AI 패치 제안 — BYOK · 소스 없이 진단정보로 생성 (S3)", bar, ""]
+    for d in diagnoses:
+        lines.append(f"■ {d.method} {d.path}")
+        if d.error:
+            lines.append(f"    ⚠ {d.error}")
+        else:
+            lines.append("  [설명]")
+            lines.append(_indent(d.explanation))
+            lines.append("  [원인]")
+            lines.append(_indent(d.cause))
+            lines.append("  [적용 단계]")
+            lines.append(_indent(d.steps))
+            if (d.optional or "").strip() and d.optional.strip() != "없음":
+                lines.append("  [선택]")
+                lines.append(_indent(d.optional))
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _indent(text: str, prefix: str = "    ") -> str:
+    body = (text or "").strip() or "(없음)"
+    return "\n".join(prefix + line for line in body.splitlines())
+
+
+def _format_rejection(url: str, result: VerificationResult) -> str:
+    """소유권 미검증 시 거부 안내 — 이유·방법·토큰을 명확히(버그 오해 방지)."""
+    lines = [
+        f"✗ 소유권 미검증 — 스캔을 거부합니다 (사유: {result.reason}).",
+        "",
+        "이 URL이 당신 소유임을 증명해야 스캔합니다 (제3자 서버 스캔 방지).",
+        f"대상 서버의 {WELL_KNOWN_PATH} 가 아래 토큰을 반환하게 한 뒤 다시 실행하세요.",
+        "",
+        f"  토큰: {result.token}",
+        "",
+        "  # FastAPI 예 (라우트 한 줄):",
+        "  from fastapi.responses import PlainTextResponse",
+        f'  @app.get("{WELL_KNOWN_PATH}")',
+        "  def _preflight_verify():",
+        f'      return PlainTextResponse("{result.token}")',
+        "",
+        f"  증명 후: preship scan {url}",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

preship-0.1.0/src/ohs_preflight/core.py

@@ -0,0 +1,221 @@
+"""스캔 엔진: URL -> /openapi.json 수집 -> schemathesis 실행 -> list[Finding] 반환.
+
+이 모듈은 CLI/출력 포맷을 모른다. 구조화된 Finding 객체만 반환한다(cli.py가 포맷).
+
+통합 방식: S1에서 확정·검증된 스코프 커맨드
+    schemathesis run <URL>/openapi.json --phases examples,fuzzing --mode positive --seed 0
+를 동일 venv의 schemathesis 콘솔 스크립트로 **그대로** 서브프로세스 실행한다(행동 패리티).
+결과는 NDJSON 리포트(--report ndjson)로 받아 ScenarioFinished 이벤트를 파싱한다.
+
+한계 (fresh state): 스캐너는 HTTP로 대상을 호출하므로, 대상이 요청에 따라 자기 상태를
+변경(예: 인메모리 store에 쓰는 POST 핸들러)하는 것을 막을 수 없다. 재현 가능한 결과를
+위해 **매 스캔 깨끗한/일회용 스테이징 인스턴스**를 전제하라. 상태를 누적하는 대상을
+반복 스캔하면 결과가 흔들릴 수 있다.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+from ohs_preflight.verify import WELL_KNOWN_PATH
+
+# S1 §부록 B 잠금 커맨드와 정확히 일치 (--checks 미지정 → 4.x 기본=all).
+SCOPE_FLAGS = ["--phases", "examples,fuzzing", "--mode", "positive", "--seed", "0"]
+
+# A(신호 정제): 노이즈 체크는 수집 후 리포트에서 제외(탐지 불변 — 필터 레이어만).
+# positive_data_acceptance = 앱이 잘못된 입력을 옳게 거부했는데 "정상 입력 거부"로 잡는 false positive.
+EXCLUDED_CHECKS = frozenset({"positive_data_acceptance"})
+
+# A(severity): 500/크래시는 high, 계약 미문서·스키마 위반은 low.
+_HIGH_CHECKS = frozenset({"not_a_server_error"})
+
+
+def _level(check: str) -> str:
+    return "high" if check in _HIGH_CHECKS else "low"
+
+
+@dataclass
+class Finding:
+    """결함 1건 = (엔드포인트, 뜨는 체크) 단위. S1_spec §5 매트릭스가 분류 근거."""
+
+    method: str
+    path: str
+    check: str
+    trigger: str          # 결함을 발사한 입력(요청)
+    response_summary: str  # 응답 status + content-type + 본문 요약
+    severity: str = ""     # schemathesis failure 유형(부가 정보)
+    level: str = "low"     # A: high(500/크래시) | low(계약 미문서·스키마 위반)
+
+
+class ScanError(RuntimeError):
+    """스캔 자체가 실행되지 못한 경우(대상 도달 불가, schemathesis 부재 등)."""
+
+
+def scan(url: str, headers: list[str] | None = None) -> list[Finding]:
+    """`url`(FastAPI 베이스 URL)을 스캔해 결함 list[Finding]를 반환한다.
+
+    `headers`: "Name: Value" 문자열 목록. 모든 요청에 실린다(--header 전달).
+    """
+    exe = _find_schemathesis()
+    if exe is None:
+        raise ScanError("schemathesis 실행 파일을 찾지 못함(동일 venv에 설치 필요).")
+
+    with tempfile.TemporaryDirectory(prefix="ohs-preflight-") as tmp:
+        ndjson_path = Path(tmp) / "events.ndjson"
+        cmd = [
+            exe, "run", _schema_url(url), *SCOPE_FLAGS,
+            "--report", "ndjson", "--report-dir", tmp,
+            "--report-ndjson-path", str(ndjson_path),
+        ]
+        for h in headers or []:
+            cmd += ["--header", h]
+
+        # cwd=tmp: schemathesis가 cwd에 만드는 .schemathesis/ 캐시를 임시디렉터리에 가둔다(M11,
+        # 자동 정리). URL·리포트 경로가 모두 절대경로라 동작은 불변.
+        proc = subprocess.run(cmd, capture_output=True, text=True, cwd=tmp)
+        # schemathesis는 결함을 찾으면 비0으로 종료한다(정상). 리포트 부재만 오류로 본다.
+        if not ndjson_path.exists():
+            raise ScanError(
+                "schemathesis가 리포트를 생성하지 못함.\n"
+                f"exit={proc.returncode}\nstderr:\n{(proc.stderr or '')[-2000:]}"
+            )
+        findings = _parse(ndjson_path)
+        # M10: 검증용 well-known 경로 제외(자기참조 방지). A(a): positive_data_acceptance 등
+        # false-positive 체크 제외. 둘 다 '필터 레이어' — 탐지 자체는 불변.
+        return [
+            f for f in findings
+            if f.path != WELL_KNOWN_PATH and f.check not in EXCLUDED_CHECKS
+        ]
+
+
+def _find_schemathesis() -> str | None:
+    """동일 venv(현재 인터프리터)의 schemathesis 콘솔 스크립트를 PATH 비의존으로 해석.
+
+    `ohs-preflight`를 풀패스로 호출하면 PATH에 venv/bin이 없을 수 있으므로,
+    sys.executable의 형제 경로를 우선 본 뒤 PATH(shutil.which)로 폴백한다.
+    """
+    sibling = Path(sys.executable).parent / "schemathesis"
+    if sibling.exists():
+        return str(sibling)
+    return shutil.which("schemathesis")
+
+
+def _schema_url(url: str) -> str:
+    u = url.rstrip("/")
+    return u if u.endswith("/openapi.json") else u + "/openapi.json"
+
+
+def _parse_headers(headers: list[str] | None) -> list[tuple[str, str]]:
+    """"Name: Value" 문자열 목록을 (name, value) 튜플로 파싱."""
+    out: list[tuple[str, str]] = []
+    for h in headers or []:
+        name, sep, value = h.partition(":")
+        if sep:
+            out.append((name.strip(), value.strip()))
+    return out
+
+
+def fetch_openapi(url: str, headers: list[str] | None = None) -> dict:
+    """대상의 /openapi.json을 가져와 dict로 반환(공개 계약 — S3 패치 진단용).
+
+    헤더는 scan과 동일하게 모든 요청에 적용된다(--header).
+    """
+    request = urllib.request.Request(_schema_url(url))
+    for name, value in _parse_headers(headers):
+        request.add_header(name, value)
+    with urllib.request.urlopen(request, timeout=30) as response:  # noqa: S310 (사용자 지정 URL)
+        return json.loads(response.read().decode("utf-8"))
+
+
+def _parse(ndjson_path: Path) -> list[Finding]:
+    """NDJSON의 ScenarioFinished 이벤트에서 실패 체크를 추출, (method,path,check)로 dedup."""
+    seen: set[tuple[str, str, str]] = set()
+    findings: list[Finding] = []
+
+    for line in ndjson_path.read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        event = json.loads(line)
+        scenario = event.get("ScenarioFinished")
+        if not scenario:
+            continue
+
+        recorder = scenario.get("recorder", {})
+        cases = recorder.get("cases", {})
+        checks = recorder.get("checks", {})
+        interactions = recorder.get("interactions", {})
+
+        for case_id, check_list in checks.items():
+            failed = [c for c in check_list if c.get("status") == "failure"]
+            if not failed:
+                continue
+
+            case = cases.get(case_id, {}).get("value", {})
+            method = case.get("method", "?")
+            path = case.get("path", "?")
+            interaction = interactions.get(case_id, {})
+            trigger = _trigger(method, path, case, interaction.get("request", {}))
+            response_summary = _response_summary(interaction.get("response", {}))
+
+            for c in failed:
+                name = c.get("name", "?")
+                key = (method, path, name)
+                if key in seen:
+                    continue
+                seen.add(key)
+                failure = (c.get("failure_info") or {}).get("failure", {})
+                findings.append(Finding(
+                    method=method,
+                    path=path,
+                    check=name,
+                    trigger=trigger,
+                    response_summary=response_summary,
+                    severity=failure.get("type", ""),
+                    level=_level(name),
+                ))
+
+    findings.sort(key=lambda f: (f.path, f.method, f.check))
+    return findings
+
+
+def _decode(blob) -> str:
+    """NDJSON의 본문 표현({"$base64": ...} 또는 일반 값)을 문자열로."""
+    if isinstance(blob, dict) and "$base64" in blob:
+        try:
+            return base64.b64decode(blob["$base64"]).decode("utf-8", "replace")
+        except Exception:
+            return str(blob["$base64"])
+    if blob is None:
+        return ""
+    return blob if isinstance(blob, str) else json.dumps(blob, ensure_ascii=False)
+
+
+def _trigger(method: str, path: str, case: dict, request: dict) -> str:
+    uri = request.get("uri") or path  # uri는 쿼리스트링까지 포함(GET 트리거 식별에 유용)
+    body = case.get("body")
+    body_str = json.dumps(body, ensure_ascii=False) if body is not None else _decode(request.get("body"))
+    out = f"{method} {uri}"
+    if body_str:
+        out += f"  body={body_str}"
+    return out
+
+
+def _response_summary(response: dict) -> str:
+    if not response:
+        return "(응답 미수집)"
+    status = response.get("status_code", "?")
+    content_type = ""
+    for key, value in (response.get("headers") or {}).items():
+        if key.lower() == "content-type":
+            content_type = value[0] if isinstance(value, list) else value
+            break
+    body = _decode(response.get("content")).replace("\n", " ")[:120]
+    return f"{status} {content_type}; {body}".strip()

preship-0.1.0/src/ohs_preflight/patch.py

@@ -0,0 +1,209 @@
+"""AI 패치 통역 (S3) — core 하위 모듈.
+
+(가) 방식: **소스 코드 없이** 진단 정보(요청 / 관측 응답 / 선언된 공개 OpenAPI 계약)만
+LLM에 보내 결함당 "설명 + 원인 + FastAPI 패치"를 생성한다. cli는 결과를 포맷만 한다.
+
+BYOK: 키는 `ANTHROPIC_API_KEY` env에서만 읽는다(anthropic SDK가 자동 로드). 키는 코드·로그·
+에러에 출력하지 않는다. 키가 없으면 cli가 패치 단계를 건너뛰고 scan은 그대로 동작한다.
+
+페이로드에서 제외(유저 미지의 내부 정보): 소스 코드, schemathesis 체크 이름, `[det]` example 스캐폴딩.
+"""
+from __future__ import annotations
+
+import os
+import re
+from collections import OrderedDict
+from dataclasses import dataclass
+
+from ohs_preflight.core import Finding, fetch_openapi
+
+DEFAULT_MODEL = "claude-opus-4-8"  # env ANTHROPIC_MODEL로 override 가능
+
+_SYSTEM = (
+    "당신은 시니어 FastAPI 엔지니어다. 자동 API 프로브가 수집한 진단정보(요청, 관측된 응답, "
+    "선언된 OpenAPI 계약)만 받는다 — 소스 코드는 절대 받지 않는다. 너의 산출물은 유저의 기존 "
+    "핸들러에 적용할 '적용 가이드'이지, 파일을 새로 쓴 코드가 아니다.\n"
+    "규칙:\n"
+    "- 파일/앱을 통째로 재작성하지 마라. 유저 코드를 지어내지 마라 — 진단정보에 없는 변수명·필드·"
+    "핸들러 본문·import·저장소·비즈니스 로직을 상상 금지. 모르는 부분은 〈유저의 핸들러〉·〈유저의 "
+    "모델〉처럼 placeholder로 지칭하고 그대로 둔다.\n"
+    "- 단, 수정에 쓰는 **구체적 FastAPI 심볼은 정확히 명시**하라: 예) Path(..., ge=1), "
+    "Query(ge=1, le=100), Field(gt=0), HTTPException(status_code=404, ...), response_model=..., "
+    "모델 인스턴스 반환. '검증을 추가하라' 같은 추상적 지시로 끝내지 마라.\n"
+    "- **상태코드 문서화 필수**: 핸들러가 새 상태코드를 raise/return하면(404·409·400 등) 반드시 같은 "
+    "라우트 데코레이터에 responses={코드: {\"description\": ...}}로 문서화하는 단계를 포함하라. "
+    "누락하면 스펙 미준수(conformance)로 재검 실패한다.\n"
+    "- **최소 침습**: 결함 수정에 꼭 필요한 변경만. 결함과 무관한 추가(새 검증 필드, EmailStr, 로깅, "
+    "불필요한 response_model 신설)는 넣지 마라. 결함 수정에 불필수인 강화는 '## 선택'에만 두고 선택임을 밝혀라.\n"
+    "- 500을 try/except로 가리는 임시방편이 아니라 타입 검증 위임·Pydantic 모델·HTTPException(문서화된 "
+    "상태코드)·response_model 정합 같은 프레임워크 표준 idiom을 우선하라.\n"
+    "- 산문은 한국어, 코드 심볼/스니펫은 실행 가능한 형태로. 반드시 '## 설명', '## 원인', '## 적용 단계', "
+    "'## 선택' 네 섹션만 출력하라('## 선택'에 내용이 없으면 \"없음\")."
+)
+
+_TASK = (
+    "\n\n[작업]\n소스 코드 없이 — 위 요청, 관측된 응답, 선언된 계약만으로 — 판단하라. "
+    "정확히 아래 네 섹션으로 답하라:\n"
+    "## 설명\n(결함을 평문으로 2~4문장)\n"
+    "## 원인\n(추정 근본 원인)\n"
+    "## 적용 단계\n(유저의 기존 핸들러/모델에 적용할 변경을 번호 매긴 줄 단위 지시로. 각 단계에 쓰는 "
+    "구체적 FastAPI 심볼을 명시. 새 상태코드를 쓰면 responses={...} 문서화 단계를 반드시 포함. "
+    "전체 파일 재작성 금지 — 바뀌는 시그니처/한두 줄 스니펫만.)\n"
+    "## 선택\n(결함 수정에 불필수인 강화만, 각 항목 앞에 \"선택:\". 없으면 \"없음\".)"
+)
+
+
+@dataclass
+class Diagnosis:
+    """결함 1건(엔드포인트 단위)에 대한 LLM 산출물. cli가 포맷만 한다."""
+
+    method: str
+    path: str
+    explanation: str = ""
+    cause: str = ""
+    steps: str = ""     # 적용 단계 (유저 핸들러에 적용할 줄 단위 지시)
+    optional: str = ""  # 선택 (불필수 강화)
+    error: str = ""     # 이 엔드포인트의 패치 생성이 실패한 경우 사유(키 누수 없음)
+
+
+def has_api_key() -> bool:
+    """ANTHROPIC_API_KEY가 환경에 있는지만 확인(값은 다루지 않음)."""
+    return bool(os.environ.get("ANTHROPIC_API_KEY"))
+
+
+def model_name() -> str:
+    return os.environ.get("ANTHROPIC_MODEL", DEFAULT_MODEL)
+
+
+def generate_patches(findings: list[Finding], url: str, headers: list[str] | None = None) -> list[Diagnosis]:
+    """결함을 엔드포인트로 묶어 엔드포인트별 패치 1건을 생성한다(6 엔드포인트 → 6 패치).
+
+    호출 전 cli가 has_api_key()로 키 존재를 보장한다.
+    """
+    import anthropic  # lazy: scan 경로가 anthropic import에 의존하지 않게
+
+    groups: "OrderedDict[tuple[str, str], list[Finding]]" = OrderedDict()
+    for f in findings:
+        groups.setdefault((f.method, f.path), []).append(f)
+
+    # 공개 계약(소스 아님). 못 가져오면 계약 없이 진행.
+    try:
+        openapi = fetch_openapi(url, headers)
+    except Exception:
+        openapi = None
+
+    client = anthropic.Anthropic()  # ANTHROPIC_API_KEY 자동 로드
+    results: list[Diagnosis] = []
+    for (method, path), group in groups.items():
+        try:
+            payload = _build_payload(method, path, group, openapi)
+            text = _call_llm(client, payload)
+            explanation, cause, steps, optional = _parse_sections(text)
+            results.append(Diagnosis(method, path, explanation, cause, steps, optional))
+        except anthropic.AuthenticationError:
+            results.append(Diagnosis(method, path, error="API 키 인증 실패 — ANTHROPIC_API_KEY 확인"))
+        except anthropic.RateLimitError:
+            results.append(Diagnosis(method, path, error="레이트리밋 — 잠시 후 재시도"))
+        except Exception as exc:  # noqa: BLE001 — 한 엔드포인트 실패가 전체를 죽이지 않게
+            results.append(Diagnosis(method, path, error=f"패치 생성 실패: {type(exc).__name__}"))
+    return results
+
+
+def _call_llm(client, payload: str) -> str:
+    message = client.messages.create(
+        model=model_name(),
+        max_tokens=4096,
+        thinking={"type": "adaptive"},  # 진단→패치는 추론 작업
+        system=[{"type": "text", "text": _SYSTEM, "cache_control": {"type": "ephemeral"}}],
+        messages=[{"role": "user", "content": payload}],
+    )
+    return "".join(b.text for b in message.content if getattr(b, "type", None) == "text")
+
+
+def _build_payload(method: str, path: str, findings: list[Finding], openapi: dict | None) -> str:
+    lines = [
+        "자동 API 프로브가 FastAPI 엔드포인트를 스캔해 결함을 발견했다. 소스 코드는 없다.",
+        f"\nENDPOINT: {method} {path}",
+        "\n[프로브가 보낸 요청(들) — 결함을 유발한 입력]",
+    ]
+    for trigger in _unique(f.trigger for f in findings):
+        lines.append(f"  - {trigger}")
+    lines.append("\n[관측된 응답]")
+    for summary in _unique(f.response_summary for f in findings):
+        lines.append(f"  - {summary}")
+
+    contract = _operation_contract(openapi, method, path)
+    if contract is not None:
+        import json
+        lines.append("\n[엔드포인트의 선언된 OpenAPI 계약 (공개·구조만; example 제외)]")
+        lines.append(json.dumps(contract, ensure_ascii=False, indent=2)[:4000])
+
+    lines.append(_TASK)
+    return "\n".join(lines)
+
+
+def _operation_contract(openapi: dict | None, method: str, path: str) -> dict | None:
+    """해당 operation의 선언 계약(요청/응답 스키마)을 추출. example/examples는 제거."""
+    if not openapi:
+        return None
+    operation = (openapi.get("paths", {}).get(path) or {}).get(method.lower())
+    if not operation:
+        return None
+    schemas = openapi.get("components", {}).get("schemas", {})
+
+    referenced: dict = {}
+    pending = _collect_refs(operation)
+    while pending:
+        name = pending.pop()
+        if name in referenced or name not in schemas:
+            continue
+        referenced[name] = schemas[name]
+        pending |= _collect_refs(schemas[name])
+
+    return _strip_examples({"operation": operation, "referenced_schemas": referenced})
+
+
+def _collect_refs(node) -> set[str]:
+    refs: set[str] = set()
+    if isinstance(node, dict):
+        ref = node.get("$ref")
+        if isinstance(ref, str) and ref.startswith("#/components/schemas/"):
+            refs.add(ref.rsplit("/", 1)[-1])
+        for value in node.values():
+            refs |= _collect_refs(value)
+    elif isinstance(node, list):
+        for value in node:
+            refs |= _collect_refs(value)
+    return refs
+
+
+def _strip_examples(obj):
+    if isinstance(obj, dict):
+        return {k: _strip_examples(v) for k, v in obj.items() if k not in ("example", "examples")}
+    if isinstance(obj, list):
+        return [_strip_examples(v) for v in obj]
+    return obj
+
+
+_SECTION_RE = re.compile(r"^#{1,6}\s*(설명|원인|적용\s*단계|선택)\s*$", re.MULTILINE)
+
+
+def _parse_sections(text: str) -> tuple[str, str, str, str]:
+    matches = list(_SECTION_RE.finditer(text))
+    if not matches:
+        return "", "", text.strip(), ""  # 헤더 못 찾으면 원문 보존(적용 단계 칸)
+    out = {"설명": "", "원인": "", "적용단계": "", "선택": ""}
+    for i, m in enumerate(matches):
+        key = m.group(1).replace(" ", "")  # "적용 단계" → "적용단계"
+        start = m.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        out[key] = text[start:end].strip()
+    return out["설명"], out["원인"], out["적용단계"], out["선택"]
+
+
+def _unique(items):
+    seen = []
+    for item in items:
+        if item not in seen:
+            seen.append(item)
+    return seen

preship-0.1.0/src/ohs_preflight/verify.py

@@ -0,0 +1,76 @@
+"""URL 소유권 검증 게이트 (S4a) — core 레벨 모듈.
+
+목적: Preship으로 '자기 것 아닌 URL'을 스캔하는 악용 차단. scan 직전 1회, 대상 URL이
+요청자 자산임을 well-known 토큰으로 증명한다. **미검증이면 스캔 외부 요청(openapi 수집·
+schemathesis·LLM)을 절대 내보내지 않는다** — 유일한 외부 요청은 well-known 프로브 GET 1회.
+
+검증 로직은 OwnershipVerifier 전략으로 추상화(향후 DNS 등 추가 여지). 현재 구현은
+WellKnownVerifier 하나뿐 — DNS 등은 구현하지 않는다.
+"""
+from __future__ import annotations
+
+import hashlib
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Protocol
+
+WELL_KNOWN_PATH = "/.well-known/preflight-verify"
+
+# 고정 네임스페이스 salt(한 번 무작위로 정해 코드에 박음). 토큰을 URL에 결합하고 무상태로
+# 재현 가능하게 만든다("난수 기반" 충족). 비밀이 아니어도 됨 — 보안은 '대상 서버에 이 토큰을
+# 올릴 수 있는가'에서 나온다(토큰 비밀성 아님).
+_SALT = "b9c41e7a2f8d4063a1e5c0d7f2b3a6e4"
+
+
+def issue_token(url: str) -> str:
+    """URL에 결정론적으로 묶인 검증 토큰. 발급 run과 검증 run이 같은 값을 얻도록(무상태)."""
+    base = url.rstrip("/")
+    return hashlib.sha256(f"{_SALT}::{base}".encode("utf-8")).hexdigest()[:32]
+
+
+@dataclass
+class VerificationResult:
+    verified: bool
+    token: str
+    reason: str = ""  # 미검증 사유(사람용; 키/민감정보 없음)
+
+
+class OwnershipVerifier(Protocol):
+    """소유권 검증 전략. 구현체는 verify(url, headers) -> VerificationResult를 제공한다."""
+
+    def verify(self, url: str, headers: list[str] | None = None) -> VerificationResult: ...
+
+
+class WellKnownVerifier:
+    """`<url>/.well-known/preflight-verify`에 발급 토큰이 게시됐는지로 소유권을 증명한다.
+
+    well-known 프로브 GET 단 1회만 외부 요청을 낸다. 그 외 어떤 요청도 하지 않는다.
+    도달 실패·부재·불일치는 전부 verified=False로 수렴한다(스캔으로 넘어가지 않음).
+    """
+
+    def verify(self, url: str, headers: list[str] | None = None) -> VerificationResult:
+        token = issue_token(url)
+        probe_url = url.rstrip("/") + WELL_KNOWN_PATH
+        request = urllib.request.Request(probe_url)
+        for name, value in _parse_headers(headers):
+            request.add_header(name, value)
+        try:
+            with urllib.request.urlopen(request, timeout=10) as response:  # noqa: S310 (사용자 지정 URL)
+                body = response.read(4096).decode("utf-8", "replace")
+        except urllib.error.HTTPError as exc:
+            return VerificationResult(False, token, reason=f"well-known 미발견 (HTTP {exc.code})")
+        except Exception as exc:  # noqa: BLE001 — 도달 실패 전부 '미검증'으로 (요청 안 나감)
+            return VerificationResult(False, token, reason=f"well-known 도달 실패 ({type(exc).__name__})")
+        if token in body:
+            return VerificationResult(True, token)
+        return VerificationResult(False, token, reason="well-known 토큰 불일치")
+
+
+def _parse_headers(headers: list[str] | None) -> list[tuple[str, str]]:
+    out: list[tuple[str, str]] = []
+    for h in headers or []:
+        name, sep, value = h.partition(":")
+        if sep:
+            out.append((name.strip(), value.strip()))
+    return out

preship-0.1.0/src/preship.egg-info/PKG-INFO

@@ -0,0 +1,105 @@
+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/`는 테스트용 버그 앱
+(제품 코드 아님).

preship-0.1.0/src/preship.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/ohs_preflight/__init__.py
+src/ohs_preflight/cli.py
+src/ohs_preflight/core.py
+src/ohs_preflight/patch.py
+src/ohs_preflight/verify.py
+src/preship.egg-info/PKG-INFO
+src/preship.egg-info/SOURCES.txt
+src/preship.egg-info/dependency_links.txt
+src/preship.egg-info/entry_points.txt
+src/preship.egg-info/requires.txt
+src/preship.egg-info/top_level.txt

preship-0.1.0/src/preship.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

preship-0.1.0/src/preship.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+preship = ohs_preflight.cli:main

preship-0.1.0/src/preship.egg-info/requires.txt

@@ -0,0 +1,2 @@
+schemathesis==4.20.3
+anthropic==0.105.2

preship-0.1.0/src/preship.egg-info/top_level.txt

@@ -0,0 +1 @@
+ohs_preflight