Preflight.sh

Preflight.sh는 코드베이스를 스캔하여 출시 준비 상태를 확인하는 명령줄 도구입니다. 프로덕션에 배포하기 전에 누락된 구성, 통합 문제, 보안 우려 사항, SEO 메타데이터 누락 및 기타 일반적인 실수를 식별합니다.

프로덕션에서 망신을 당하지 마세요. 그냥 명령을 실행하세요.

설치

Homebrew (macOS/Linux)

brew install preflightsh/preflight/preflight

npm

npm install -g @preflightsh/preflight

Go

go install github.com/preflightsh/preflight@latest

Docker

docker pull ghcr.io/preflightsh/preflight

셸 스크립트

curl -sSL https://preflight.sh/install.sh | sh

수동 다운로드

GitHub Releases에서 최신 릴리스를 다운로드하세요.

빠른 시작

# 프로젝트 디렉터리에서 초기화
cd your-project
preflight init

# 모든 검사 실행
preflight scan

# 특정 디렉터리 스캔
preflight scan /path/to/project

# 상세 출력으로 실행 (각 검사에 매칭된 파일 표시)
preflight scan --verbose
preflight scan -v  # 축약형

# JSON 출력의 CI 모드로 실행
preflight scan --ci --format json

# 빠른 반복을 위해 특정 검사만 실행하거나 일부 건너뛰기
# (일회성; `preflight ignore`와 달리 preflight.yml을 변경하지 않음)
preflight scan --only seo_meta,og_twitter
preflight scan --skip vulnerability,secrets

# 검사 무시
preflight ignore sitemap

# 검사 무시 해제
preflight unignore sitemap

# 모든 검사 ID 나열
preflight checks

에이전트 스킬

이 저장소에는 skills/preflight/SKILL.md에 skills.sh 호환 에이전트 스킬이 포함되어 있습니다. 코딩 에이전트에게 반복 가능한 Preflight 워크플로를 제공합니다: preflight.yml 검사, CI 안전 스캔 실행, 결과 분류, 안전하지 않은 무시 방지, 검증 재실행, 잔여 출시 위험 보고.

이 저장소에서 스킬 목록 보기:

# Bun 사용
bunx --yes skills add preflightsh/preflight --list

# 또는 npm 사용
npx --yes skills add preflightsh/preflight --list

Preflight 스킬만 설치:

# Bun 사용
bunx --yes skills add preflightsh/preflight --skill preflight

# 또는 npm 사용
npx --yes skills add preflightsh/preflight --skill preflight

대시보드 및 AI 제안

Preflight는 계정 없이도 명령줄에서 완전히 사용할 수 있습니다. 선택적 대시보드인 app.preflight.sh는 스캔의 호스팅된 기록과 각 결과에 대한 AI 생성 수정 제안을 추가합니다. 코드는 절대 머신을 떠나지 않습니다: 스캔은 로컬에서 실행되며, 게시할 때 결과의 수정된 요약(검사 ID, 상태, 메시지 — 비밀 값이나 파일 내용은 절대 아님)만 전송됩니다.

무료 계정을 만든 후 CLI를 연결하세요:

preflight auth login    # 브라우저를 열어 이 CLI를 인증
preflight auth status   # 로그인한 사용자 표시
preflight auth logout   # 저장된 자격 증명 제거

--publish로 스캔을 대시보드에 게시하세요. 실행을 볼 수 있는 링크가 출력됩니다. 게시는 최선 노력 방식입니다: 오프라인이거나 로그인하지 않은 경우에도 스캔은 계속 실행되고 정상적으로 종료됩니다.

preflight scan --publish

대시보드에서 각 실행의 통과/경고/실패 분석, 전체 결과 목록, 프로젝트별 기록을 확인하여 배포 간 변경 사항을 볼 수 있습니다.

터미널에서 preflight history로 해당 기록을 읽을 수도 있습니다:

preflight history                       # 프로젝트 전체의 최근 실행
preflight history --here                # 현재 프로젝트의 실행만
preflight history <run-id>              # 단일 실행의 전체 검사 결과
preflight history --here --format json  # 에이전트용 기계 판독 가능 형식

preflight auth login이 필요합니다. --here는 게시 시 사용되는 것과 동일한 키인 git 원격을 기준으로 실행을 현재 저장소에 매칭합니다.

게시된 실행에서 실패하거나 경고가 있는 검사를 열어 감지된 스택에 맞춘 단계별 수정 사항을 생성하세요. 복사 가능한 명령과 코드가 포함됩니다.

• 무료는 월 5회 게시 실행을 포함합니다.
• 자체 키 사용: 대시보드 설정에서 OpenAI 또는 Anthropic API 키를 추가하면 게시가 무료로 무제한 유지됩니다(공급자에게 직접 비용 지불).
• 관리형 ($5/월): AI 비용을 당사가 부담하며 실행이 무제한이고 API 키가 필요 없습니다.

검사 항목

지원 서비스 (72)

Preflight는 다음 서비스의 구성을 자동 감지하고 검증합니다:

결제

• Stripe, PayPal, Braintree, Paddle, LemonSqueezy

오류 추적 및 모니터링

• Sentry, Bugsnag, Rollbar, Honeybadger, Datadog, New Relic, LogRocket

이메일 및 뉴스레터

• Postmark, SendGrid, Mailgun, AWS SES, Resend, Mailchimp, Kit, Beehiiv, AWeber, ActiveCampaign, Campaign Monitor, Drip, Klaviyo, Buttondown

분석

• Plausible, Fathom, Umami, Fullres Analytics, Datafa.st Analytics, Google Analytics, PostHog, Mixpanel, Amplitude, Segment, Hotjar

인증

• Auth0, Clerk, WorkOS

채팅

• Intercom, Crisp

알림

• Slack, Discord, Twilio

인프라

• Firebase, Supabase, Redis, Sidekiq, RabbitMQ, Elasticsearch, Convex

스토리지 및 CDN

• AWS S3, Cloudinary, Cloudflare

검색

• Algolia

SEO

• IndexNow

AI / LLM

• OpenAI, Anthropic Claude, Google AI (Gemini), Mistral, Cohere, Replicate, Hugging Face, Grok (X/Twitter), Perplexity, Together AI

구성

Preflight는 프로젝트 루트의 preflight.yml 파일을 사용합니다:

projectName: my-app
stack: rails  # rails, next, react, vite, laravel 등

urls:
  staging: "https://staging.example.com"
  production: "https://example.com"

services:
  stripe:
    declared: true
  sentry:
    declared: true

checks:
  envParity:
    enabled: true
    envFile: ".env"
    exampleFile: ".env.example"

  healthEndpoint:
    enabled: true
    path: "/health"  # 선택 사항 - 설정하지 않으면 일반적인 경로를 자동 감지

  stripeWebhook:
    enabled: true
    url: "https://api.example.com/webhooks/stripe"  # 선택 사항 - GET으로 프로브; 404 또는 응답 없음이 보고됨

  seoMeta:
    enabled: true
    mainLayout: "app/views/layouts/application.html.erb"

  security:
    enabled: true

  secrets:
    enabled: true
    # 비밀 스캔용 파일별 허용 목록. 전체 검사를 비활성화하지 않고
    # 개별 결과(예: 리퍼러 제한 공개 키)를 억제하는 데 사용합니다.
    allowlist:
      - path: web/js/golden-hour.js
        fingerprint: "sha256:<hex>"   # 권장 — 정확한 비밀에 고정
        reason: "HTTP-리퍼러 제한 Google Timezone 키"
      - path: "web/tools/**/*.php"    # doublestar 글로브 지원

  indexNow:
    enabled: true
    key: "your32characterhexkeyhere00000"

  emailAuth:
    enabled: true  # 선택 사항, 프로덕션 도메인의 SPF/DMARC 확인

  humansTxt:
    enabled: false  # 선택 사항, 팀 표시

  license:
    enabled: false  # 선택 사항, 오픈 소스 프로젝트용

# ID로 특정 검사 또는 서비스 무시
ignore:
  - sitemap
  - llms_txt
  - google_analytics

검사 및 서비스 무시

preflight ignore <id>를 사용하여 특정 검사 또는 서비스를 무음 처리하세요:

preflight ignore sitemap        # sitemap 검사 무시
preflight ignore sentry         # Sentry 서비스 검증 무시
preflight unignore sitemap      # sitemap 검사 다시 활성화
preflight checks                # 무시 가능한 모든 ID 나열

단일 비밀 결과 허용 목록

전체 secrets 검사를 무음 처리하는 것보다 개별 결과를 허용 목록에 추가하는 것이 좋습니다. 명령줄에서 일회성 예외를 추가하세요:

preflight ignore secrets web/js/golden-hour.js

그러면 preflight.yml의 checks.secrets.allowlist 아래에 경로 항목이 추가됩니다. path 필드는 프로젝트 상대 파일 경로를 기준으로 해석되는 doublestar 글로브(**는 디렉터리 간 매칭)입니다.

지문을 고정하세요. 경로 전용 허용 목록은 해당 파일에 향후 추가되는 모든 비밀을 조용히 수용합니다. 항목을 편집하고 fingerprint: "sha256:<hex>"를 추가하세요 — 감지된 비밀 값의 SHA-256입니다. 이제 키가 교체되거나 동일한 파일에 다른 비밀이 나타나면 preflight가 다시 경고합니다.

결과는 경로 + 지문으로 매칭되며, 전체 파일이 아닙니다. 파일의 허용 목록 지문은 동일한 파일의 다른 줄에 있는 다른 비밀을 억제하지 않습니다.

무시 가능한 검사 ID

SEO 및 소셜: seo_meta, canonical, structured_data, index_now (선택), og_twitter, viewport, lang

보안 및 인프라: security_headers, ssl, www_redirect, email_auth (선택), secrets

환경 및 헬스: env_parity, health_endpoint

코드 품질 및 성능: vulnerability, debug_statements, error_pages, image_optimization

법적 및 규정 준수: legal_pages

웹 표준 파일: favicon, robots_txt, sitemap, llms_txt, ads_txt (선택), humans_txt (선택), license (선택)

0.22에서 이름이 변경된 검사 ID

이제 모든 검사 ID는 snake_case입니다. 기존 camelCase 이름은 1.x 라인을 통해 ID가 허용되는 모든 곳(ignore: 목록, --only, --skip, preflight ignore)에서 stderr에 메모와 함께 계속 작동하며, 2.0에서 제거됩니다. preflight ignore는 새 이름을 작성합니다. preflight.yml의 checks: 아래 키(healthEndpoint, seoMeta, ...)는 별도 스키마이며 변경되지 않았습니다.

신뢰할 수 없는 코드 스캔에 대한 참고 사항

모든 검사는 파일을 읽습니다. 하나는 프로그램을 실행합니다. vulnerability 검사는 프로젝트 디렉터리 내에서 프로젝트 자체의 패키지 관리자(npm audit, yarn audit, composer audit, bundle audit, pip-audit, govulncheck, cargo audit)를 실행하며, 정리된 환경과 임시 홈 디렉터리를 사용하여 토큰을 읽을 수 없게 합니다. 패키지 관리자는 여전히 프로젝트 로컬 구성을 존중하며, 해당 구성 중 일부는 저장소에서 코드를 실행할 수 있습니다(Yarn yarnPath, Cargo 별칭, Composer 플러그인). 자신의 프로젝트를 스캔하는 것이 Preflight의 목적입니다. CI에서 포크의 풀 리퀘스트와 같이 신뢰할 수 없는 저장소를 스캔할 때는 --skip vulnerability를 추가하세요.

무시 가능한 서비스 ID

모든 서비스에는 올바른 통합(환경 변수, SDK 패턴, 구성 파일)을 검증하는 검사가 있습니다:

결제: stripe, paypal, braintree, paddle, lemonsqueezy

오류 추적: sentry, bugsnag, rollbar, honeybadger, datadog, newrelic, logrocket

트랜잭션 이메일: postmark, sendgrid, mailgun, aws_ses, resend

이메일 마케팅: mailchimp, convertkit, beehiiv, aweber, activecampaign, campaignmonitor, drip, klaviyo, buttondown

분석: plausible, fathom, google_analytics, fullres, datafast, posthog, mixpanel, amplitude, segment, hotjar

인증: auth0, clerk, workos, firebase, supabase

커뮤니케이션: twilio, slack, discord, intercom, crisp

인프라: redis, sidekiq, rabbitmq, elasticsearch, convex

스토리지 및 CDN: aws_s3, cloudinary, cloudflare

검색: algolia

AI: openai, anthropic, google_ai, mistral, cohere, replicate, huggingface, grok, perplexity, together_ai

SEO: index_now

쿠키 동의: cookieconsent, cookiebot, onetrust, termly, cookieyes, iubenda

종료 코드

코드 1과 2는 스캔이 실행되어 무언가를 보고했음을 의미합니다. 코드 64는 그 단계에 도달하지 못했음을 의미하므로, CI는 "이 프로젝트에 문제가 있다"와 "이 호출이 잘못되었다"를 구분할 수 있습니다.

셸 완성

명령, 플래그 및 검사 ID(--only 및 --skip 값 포함)에 대한 탭 완성:

# bash (~/.bashrc에 추가)
source <(preflight completion bash)

# zsh (~/.zshrc에 추가)
source <(preflight completion zsh)

# fish
preflight completion fish | source

출력은 NO_COLOR 환경 변수도 존중합니다.

지원 스택

백엔드 프레임워크

• Ruby on Rails, Laravel, PHP, Go, Python/Django, Rust, Node.js

프론트엔드 프레임워크

• Next.js, Nuxt, Remix, React, Vue.js, Vite, Svelte, Angular

전통적 CMS

• WordPress, Craft CMS, Drupal, Ghost

정적 사이트 생성기

• Hugo, Jekyll, Gatsby, Eleventy (11ty), Astro

헤드리스 CMS

• Strapi, Sanity, Contentful, Prismic

기타

• 정적 사이트

CI 통합

# GitHub Actions 예시 (curl)
- name: Run Preflight
  run: |
    curl -sSL https://preflight.sh/install.sh | sh
    preflight scan --ci --format json

# GitHub Actions 예시 (Docker)
- name: Run Preflight
  run: docker run -v ${{ github.workspace }}:/app ghcr.io/preflightsh/preflight scan --ci --format json

라이선스

MIT