CLI

InstaFix CLI는 프로젝트 설정과 상태 점검을 자동화합니다. 런타임 의존성이 전혀 없는 단일 실행 파일로 배포되며, Node 20 이상이 필요합니다.

npx @instafix/cli --help

패키지 이름이 중요합니다. 항상 npx @instafix/cli <command> 형태로 실행하세요. npm에는 instafix라는 패키지가 존재하지 않으므로, npx instafix는 프로젝트에 @instafix/cli가 이미 설치되어 있을 때만 동작합니다.

init — 대화형 설정

npx @instafix/cli init

init은 최대 네 가지 확인 절차를 안내합니다:

1. Prisma 모델 동기화 — 스키마가 발견되면(스키마 탐지 참고), InstaFixFeedback과 InstaFixAnnotation 모델을 추가할지 제안합니다.
2. 스키마 반영 — 스키마가 발견되었다면 npx prisma db push를 바로 실행할지 제안합니다. Prisma의 출력(그리고 Prisma가 요구하는 확인 절차까지)이 그대로 터미널에 표시됩니다.
3. API 라우트 생성 — 위젯을 서비스하는 Next.js App Router 라우트 생성을 제안합니다. 파일은 app/api/instafix/route.ts에, 프로젝트가 src/ 구조를 사용한다면 src/app/api/instafix/route.ts에 생성됩니다. 기존 라우트는 절대 덮어쓰지 않습니다.
   • 스키마를 찾은 경우: @instafix/adapter-prisma 기반 라우트를 생성합니다.
   • 스키마를 찾지 못한 경우: 대신 어떤 백엔드를 쓸지 물어봅니다 — SQLite(@instafix/adapter-sqlite, 외부 서비스 불필요) 또는 건너뛰고 직접 연결. Prisma 스키마가 없는데도 무조건 Prisma를 가정하지 않습니다.
4. 위젯 컴포넌트 생성 — initInstaFix()를 호출하는 "use client" 컴포넌트를 components/instafix-widget.tsx(또는 src/ 구조라면 src/components/...)에 생성할지 제안합니다. package.json의 이름을 projectName으로 사용합니다. 기존 컴포넌트는 절대 덮어쓰지 않습니다.

Prisma 방식 라우트는 여러분이 직접 준비해야 하는 두 가지를 import합니다 — CLI는 아무것도 설치하지 않습니다:

• @instafix/adapter-prisma 패키지 (npm i @instafix/adapter-prisma)
• @/lib/prisma에서 export된 Prisma 클라이언트

SQLite 방식 라우트는 @instafix/adapter-sqlite만 설치되어 있으면 됩니다 — 별도로 연결할 클라이언트도, 반영할 스키마도 없습니다. SQLite 어댑터 참고.

프로젝트에 app/(또는 src/app/) 디렉터리가 없다면 init은 오류와 함께 종료됩니다: Next.js App Router 라우트만 스캐폴딩하기 때문입니다. 다른 프레임워크에서는 어댑터를 수동으로 연결해야 합니다 — 어댑터 참고.

자동으로 처리되지 않은 항목 — 거절했거나 스키마/라우트를 찾지 못한 경우 — 은 마지막에 다음 단계(Next steps) 노트로 안내되므로, 아무것도 조용히 누락되지 않습니다.

init은 설계상 대화형이며 CI 환경에서는 아무 동작도 하지 않습니다(터미널이 없으면 조용히 종료됩니다). 자동화가 필요하다면 sync를 사용하세요.

sync — 비대화형 스키마 병합

npx @instafix/cli sync
npx @instafix/cli sync --schema prisma/schema.prisma

sync는 확인 질문 없이 InstaFix 모델을 Prisma 스키마에 병합하므로, CI나 업데이트 스크립트에서 안전하게 사용할 수 있습니다. AST 레벨에서 동작합니다:

• 두 모델이 없으면 새로 생성하고,
• 누락된 필드와 @@index 블록을 추가하며,
• 예상된 형태에서 벗어난 InstaFix 필드의 타입이나 속성을 다시 작성하고,
• 여러분이 직접 추가한 필드에는 절대 손대지 않습니다.

변경 사항이 있으면 npx prisma db push를 실행하라고 알려줍니다. 연달아 두 번 실행해도 아무 일도 일어나지 않습니다.

실행하기 전에 커밋하세요. sync는 스키마 파일 전체를 다시 출력하므로, 포맷팅(주석 뒤 빈 줄, 컬럼 정렬)이 여러분 자신의 모델에도 함께 정규화됩니다. 깨끗한 git diff 상태에서 실행하면 변경 사항을 검토하기 쉽습니다.

status — 프로젝트 상태 리포트

npx @instafix/cli status
npx @instafix/cli status --schema prisma/schema.prisma

status는 네 가지 점검을 수행하고 리포트를 출력합니다:

API 라우트 점검은 Next.js App Router만 인식합니다. Express, Hono, 또는 Pages Router에서 어댑터를 서비스하는 경우, 실제로는 정상 동작하더라도 해당 항목은 "Not found"로 표시됩니다.

doctor — 실시간 엔드포인트 점검

npx @instafix/cli doctor --url http://localhost:3000 --endpoint /api/instafix

doctor는 실행 중인 서버에 GET 요청을 한 번 보내서 InstaFix 핸들러가 응답했는지 알려줍니다(타임아웃 10초). 두 플래그를 모두 전달하면 비대화형으로 실행됩니다 — 생략한 플래그는 질문으로 대체됩니다.

HTTP 응답만 확인할 뿐, 스키마는 전혀 읽지 않습니다. 스키마 검증에는 status를 사용하세요.

종료 코드

모든 명령은 스크립트로 실행할 수 있습니다. 0은 성공, 1은 고쳐야 할 무언가가 있다는 뜻입니다:

CI 파이프라인에서 주의할 점이 두 가지 있습니다: 스키마 필드가 단순히 어긋난 경우 status는 (sync 실행을 권하는 힌트와 함께) 0으로 종료되고, doctor는 InstaFix 핸들러가 아니더라도 200 응답이기만 하면 0으로 종료됩니다(대신 경고를 출력합니다). 둘 다 엄격한 게이트는 아닙니다.

스키마 탐지

--schema를 전달하지 않으면 CLI는 다음 세 위치를 순서대로 확인합니다:

1. prisma/schema.prisma
2. schema.prisma
3. prisma/schema/schema.prisma