문제 해결

핵심 요약

문제가 생기면 먼저 종료 코드와 출력된 상태를 확인하세요. NOT_AVAILABLE은 기능이 없다는 뜻이지 연동 성공이 아닙니다.

보호 작업은 대상 파일 → 승인 여부 → 계획 해시 → 증적 파일 순서로 확인한 뒤 다시 실행하세요.

종료 코드부터

모든 CLI 결과는 네 개의 종료 코드 중 하나로 매핑됩니다 — 진단을 거기서 시작하세요:

Exit	이름	일반적 원인
0	ok	단계 완료. NOT_AVAILABLE/NOT_CONFIGURED 상태도 exit 0입니다 — 실패가 아닌 정직한 답변입니다.
1	fail	단계가 실행됐지만 실패: doctor 검사 FAIL, 동등성 FAIL_ADOPTION, 무효 증거 레코드, 잘못된 로그인, 미인증 auth status, 무효 라이선스 키.
2	needs-approval	필수 입력 누락(protect.target 미설정, 위치 인자 없음), 무효 spec, apply 시 plan/spec/target sha 드리프트, 승인 필요.
3	refused	fail-closed 거부: 파이프라인이 apply 거부(예: 미승인 AUTO 결정), 또는 인증 필요 명령에서 401/403 → "yp auth login 실행".

--json에서는 객체가 status, error, 명령별 필드를 가집니다 — yp-mcp가 이를 그대로 표면화합니다.

일반적인 실패

protect plan 거부: protect target 없음

init은 유료 경계를 절대 추측하지 않습니다. 설정하세요:

yp init --force --target src/paid.mjs
# 또는 devpay.json 편집: "protect": { "target": "src/paid.mjs" }

Rust 프로젝트: 분석기는 js/wasm 모듈만 읽습니다 — protect.target을 Cargo 소스가 아닌 .mjs 유료 로직 래퍼로 지정하세요.

apply exit 2 — sha 드리프트

플랜은 정확한 spec/target/driver 바이트에 바운드됩니다 (plan.spec_sha256, plan.target_sha256, plan.driver_sha256). 플래닝 후 이들 중 하나를 수정했다면 승인은 stale 상태입니다: yp protect plan을 다시 실행하고, 다시 review한 후 apply하세요.

apply exit 3 — 거부됨

미승인/초안 spec 하의 AUTO 결정은 --approve가 있어도 거부됩니다 (handoff만). spec을 승격하세요: .devpay/spec.draft.json을 review하고, 모든 REQUIRES_APPROVAL 마커를 해결하고, draft:false로 승인된 spec 경로(protect.spec, 기본 .devpay/spec.json)에 저장한 뒤, re-plan, re-apply하세요.

verify exit 2 — 적용된 것 없음

Verify는 적용된 작업을 입증합니다. plan.json만으로는 planned이지 applied가 아닙니다 — 먼저 yp protect apply를 실행하세요(.devpay/apply-report.json이 존재해야 함).

auth status / 플랫폼 명령 exit 3

저장된 자격 증명이 없거나 백엔드가 거부했습니다. 실행하세요:

yp auth login --api-base <url>
yp auth status

Axum(be/)에서 로그인이 성공하면 저장된 타입은 dev-user입니다 — X-Dev-User는 dev-auth 배포에서만 인증되며, 프로덕션 백엔드는 401을 응답하고 CLI가 이를 보고합니다.

integration check가 NOT_AVAILABLE 출력 (exit 0)

CLI가 도달한 백엔드에서 라우트가 라우팅되지 않았습니다(Worker request_id 404 지문으로 감지). 이는 정직한 디그레이드입니다 — 의도한 백엔드를 가리키고 있는지(--api-base), 배포에 d3 integration-parity 라우트가 포함되어 있는지 확인하세요(be-cloudflare/src/lib.rs/api/v1/projects/:id/integration arm).

license status 프로브가 NOT_AVAILABLE

bindings/usage 상세 프로브는 be-cloudflare에만 존재합니다; Axum 백엔드에서는 항상 NOT_AVAILABLE을 보고합니다. 기본 목록은 양쪽에서 동작합니다.

license status <key> "not found"

라이선스 키는 Worker 백엔드의 셀러 목록에 노출되지 않습니다 — 키 인자는 공개 verify 엔드포인트로 폴백합니다(JSON의 source:"public-verify"). 거기서 NOT_FOUND 판정은 키가 셀러 목록에 없으면서 동시에 공개적으로 검증도 안 된다는 뜻입니다 — 다른 셀러의 것일 수 있습니다.

doctor FAIL

doctor는 각 검사(node 버전, toolkit, SDK, config, API, git)를 ok/FAIL과 함께 출력합니다 — 실패한 항목만 고치세요; 어디든 FAIL이 있으면 exit 1.

더 많은 신호 얻기

yp <cmd> --json        # 구조화된 status + error 필드
yp <cmd> --help        # 명령별 계약
cat .devpay/state.json     # apply 게이트가 바인딩되는 plan/spec/target sha
cat .devpay/apply-report.json .devpay/verify-report.json