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  # 축약형

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

# 특정 검사만 실행하거나 일부 건너뛰기 (빠른 반복 작업용)
# (일회성; `preflight ignore`와 달리 preflight.yml을 변경하지 않음)
preflight scan --only seoMeta,ogTwitter
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

대시보드에서는 각 실행의 pass/warn/fail 분석, 전체 결과 목록, 프로젝트별 기록을 확인할 수 있어 배포 간 변경 사항을 볼 수 있습니다.

터미널에서도 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 / LLMs

• 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, etc.

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"  # optional - auto-detects common paths if not set

  stripeWebhook:
    enabled: true
    url: "https://api.example.com/webhooks/stripe"

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

  security:
    enabled: true

  secrets:
    enabled: true
    # Per-file allowlist for the secrets scan. Use this to suppress an
    # individual finding (e.g. a referrer-restricted public key) without
    # disabling the whole check.
    allowlist:
      - path: web/js/golden-hour.js
        fingerprint: "sha256:<hex>"   # recommended — pins to the exact secret
        reason: "HTTP-referrer-restricted Google Timezone key"
      - path: "web/tools/**/*.php"    # doublestar globs are supported

  indexNow:
    enabled: true
    key: "your32characterhexkeyhere00000"

  emailAuth:
    enabled: true  # opt-in, checks SPF/DMARC on production domain

  humansTxt:
    enabled: false  # opt-in, credits the team

  license:
    enabled: false  # opt-in, for open source projects

# Silence specific checks or services by ID
ignore:
  - sitemap
  - llmsTxt
  - google_analytics

검사 및 서비스 무시

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

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

단일 시크릿 결과 허용 목록

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

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

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

지문을 고정하세요. 경로만 있는 허용 목록은 해당 파일에 향후 어떤 시크릿이 추가되어도 자동으로 수락합니다. 항목을 편집하고 fingerprint: "sha256:<hex>"를 추가하세요. 이는 감지된 시크릿 값의 SHA-256 해시입니다. 이제 키가 교체되거나 동일한 파일에 다른 시크릿이 나타나면 preflight가 다시 경고합니다.

결과는 경로 + 지문으로 일치하며, 파일 전체가 아닙니다. 파일 내 허용 목록에 등록된 지문이 같은 파일의 다른 줄에 있는 다른 시크릿을 억제하지는 않습니다.

무시 가능한 검사 ID

SEO 및 소셜: seoMeta, canonical, structured_data, indexNow (옵트인), ogTwitter, viewport, lang

보안 및 인프라: securityHeaders, ssl, www_redirect, email_auth (옵트인), secrets

환경 및 상태: envParity, healthEndpoint

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

법률 및 규정 준수: legal_pages

웹 표준 파일: favicon, robotsTxt, sitemap, llmsTxt, adsTxt (옵트인), humansTxt (옵트인), license (옵트인)

무시 가능한 서비스 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: indexNow

쿠키 동의: 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