Preflight.sh

Preflight.sh è uno strumento da riga di comando che analizza il tuo codebase per verificare la prontezza al lancio. Identifica configurazioni mancanti, problemi di integrazione, problemi di sicurezza, lacune nei metadati SEO e altri errori comuni prima di effettuare il deploy in produzione.

Non metterti in imbarazzo in produzione. Basta eseguire il comando.

Installazione

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

Script Shell

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

Download Manuale

Scarica l'ultima release da GitHub Releases.

Avvio Rapido

# Inizializza nella directory del tuo progetto
cd your-project
preflight init

# Esegui tutti i controlli
preflight scan

# Analizza una directory specifica
preflight scan /path/to/project

# Esegui con output verboso (mostra quali file corrispondono a ciascun controllo)
preflight scan --verbose
preflight scan -v  # forma abbreviata

# Esegui in modalità CI con output JSON
preflight scan --ci --format json

# Esegui solo controlli specifici, o saltane alcuni, per iterazioni rapide
# (una tantum; a differenza di `preflight ignore` non modifica preflight.yml)
preflight scan --only seo_meta,og_twitter
preflight scan --skip vulnerability,secrets

# Silenzia un controllo
preflight ignore sitemap

# Riattiva un controllo
preflight unignore sitemap

# Elenca tutti gli ID dei controlli
preflight checks

Skill per Agenti

Questo repository include una skill per agenti compatibile con skills.sh in skills/preflight/SKILL.md. Fornisce agli agenti di codifica un flusso di lavoro Preflight ripetibile: ispeziona preflight.yml, esegui scansioni sicure per CI, classifica i risultati, evita ignore non sicuri, riesegui la validazione e segnala il rischio residuo di lancio.

Elenca la skill da questo repository:

# Con Bun
bunx --yes skills add preflightsh/preflight --list

# Oppure con npm
npx --yes skills add preflightsh/preflight --list

Installa solo la skill Preflight:

# Con Bun
bunx --yes skills add preflightsh/preflight --skill preflight

# Oppure con npm
npx --yes skills add preflightsh/preflight --skill preflight

Dashboard e Suggerimenti IA

Preflight è completamente utilizzabile dalla riga di comando senza account. La dashboard opzionale su app.preflight.sh aggiunge una cronologia ospitata delle tue scansioni e suggerimenti di correzione generati dall'IA per ogni risultato. Il tuo codice non lascia mai la tua macchina: la scansione viene eseguita localmente e solo un riepilogo oscurato dei risultati (ID dei controlli, stati e messaggi, mai valori segreti o contenuti dei file) viene inviato quando pubblichi.

Crea un account gratuito, poi collega la CLI:

preflight auth login    # apre il browser per autorizzare questa CLI
preflight auth status   # mostra con quale account sei connesso
preflight auth logout   # rimuove le credenziali salvate

Pubblica una scansione sulla tua dashboard con --publish. Stampa un link per visualizzare l'esecuzione. La pubblicazione è best-effort: se sei offline o non connesso, la scansione viene comunque eseguita ed esce normalmente.

preflight scan --publish

Sulla dashboard ottieni per ogni esecuzione la suddivisione pass/warn/fail, l'elenco completo dei risultati e una cronologia per progetto, così puoi vedere cosa è cambiato tra i deploy.

Puoi anche leggere quella cronologia dal terminale con preflight history:

preflight history                       # esecuzioni recenti su tutti i tuoi progetti
preflight history --here                # solo le esecuzioni del progetto corrente
preflight history <run-id>              # risultati completi dei controlli di una singola esecuzione
preflight history --here --format json  # leggibile da macchina, per agenti

Richiede preflight auth login. --here associa le esecuzioni al repository corrente tramite il suo remote git, la stessa chiave usata durante la pubblicazione.

Apri qualsiasi controllo fallito o con avvisi su un'esecuzione pubblicata per generare una correzione passo-passo adattata allo stack rilevato, con comandi e codice pronti da copiare.

• Gratuito include 5 esecuzioni pubblicate al mese.
• Porta la tua chiave: aggiungi una chiave API OpenAI o Anthropic nelle impostazioni della dashboard e la pubblicazione rimane gratuita e illimitata (paghi direttamente il tuo fornitore).
• Gestito ($5/mese): copriamo i costi IA e le esecuzioni sono illimitate, senza bisogno di chiave API.

Cosa Controlla

Servizi Supportati (72)

Preflight rileva automaticamente e valida la configurazione per questi servizi:

Pagamenti

• Stripe, PayPal, Braintree, Paddle, LemonSqueezy

Tracciamento Errori e Monitoraggio

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

Email e Newsletter

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

Analytics

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

Autenticazione

• Auth0, Clerk, WorkOS

Chat

• Intercom, Crisp

Notifiche

• Slack, Discord, Twilio

Infrastruttura

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

Storage e CDN

• AWS S3, Cloudinary, Cloudflare

Ricerca

• Algolia

SEO

• IndexNow

IA / LLM

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

Configurazione

Preflight utilizza un file preflight.yml nella root del tuo progetto:

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

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"  # opzionale - rileva automaticamente i percorsi comuni se non impostato

  stripeWebhook:
    enabled: true
    url: "https://api.example.com/webhooks/stripe"  # opzionale - sondato con una GET; un 404 o nessuna risposta viene segnalato

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

  security:
    enabled: true

  secrets:
    enabled: true
    # Allowlist per-file per la scansione dei segreti. Usala per sopprimere un
    # singolo risultato (es. una chiave pubblica limitata dal referrer) senza
    # disabilitare l'intero controllo.
    allowlist:
      - path: web/js/golden-hour.js
        fingerprint: "sha256:<hex>"   # consigliato — fissa il segreto esatto
        reason: "Chiave Google Timezone limitata dal referrer HTTP"
      - path: "web/tools/**/*.php"    # i glob doublestar sono supportati

  indexNow:
    enabled: true
    key: "your32characterhexkeyhere00000"

  emailAuth:
    enabled: true  # opt-in, controlla SPF/DMARC sul dominio di produzione

  humansTxt:
    enabled: false  # opt-in, accredita il team

  license:
    enabled: false  # opt-in, per progetti open source

# Silenzia controlli o servizi specifici tramite ID
ignore:
  - sitemap
  - llms_txt
  - google_analytics

Ignorare Controlli e Servizi

Silenzia controlli o servizi specifici usando preflight ignore <id>:

preflight ignore sitemap        # Ignora il controllo sitemap
preflight ignore sentry         # Ignora la validazione del servizio Sentry
preflight unignore sitemap      # Riattiva il controllo sitemap
preflight checks                # Elenca tutti gli ID ignorabili

Allowlist di un singolo risultato segreti

Preferisci l'allowlist di un singolo risultato rispetto al silenziamento dell'intero controllo secrets. Aggiungi eccezioni una tantum dalla riga di comando:

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

Questo aggiunge una voce di percorso sotto checks.secrets.allowlist nel tuo preflight.yml. Il campo path è un glob doublestar (** corrisponde attraverso le directory) risolto rispetto al percorso del file relativo al progetto.

Fissa il fingerprint. Un'allowlist basata solo sul percorso accetta silenziosamente qualsiasi futuro segreto inserito in quel file. Modifica la voce e aggiungi un fingerprint: "sha256:<hex>" — lo SHA-256 del valore del segreto rilevato. Ora, se la chiave viene ruotata o appare un segreto diverso nello stesso file, preflight riallerta.

I risultati vengono associati tramite percorso + fingerprint, non per intero file. Un fingerprint in allowlist in un file non sopprime altri segreti su altre righe dello stesso file.

ID dei Controlli Ignorabili

SEO e Social: seo_meta, canonical, structured_data, index_now (opt-in), og_twitter, viewport, lang

Sicurezza e Infrastruttura: security_headers, ssl, www_redirect, email_auth (opt-in), secrets

Ambiente e Salute: env_parity, health_endpoint

Qualità del Codice e Prestazioni: vulnerability, debug_statements, error_pages, image_optimization

Legale e Conformità: legal_pages

File Standard Web: favicon, robots_txt, sitemap, llms_txt, ads_txt (opt-in), humans_txt (opt-in), license (opt-in)

ID dei Controlli Rinominati nella 0.22

Ogni ID di controllo ora è in snake_case. I vecchi nomi camelCase continuano a funzionare ovunque venga accettato un ID (liste ignore:, --only, --skip, preflight ignore) per tutta la linea 1.x, con una nota su stderr, e spariranno nella 2.0. preflight ignore scrive il nuovo nome. Le chiavi sotto checks: in preflight.yml (healthEndpoint, seoMeta, ...) sono uno schema separato e non sono cambiate.

Una nota sulla scansione di codice di cui non ti fidi

Ogni controllo legge file; uno esegue un programma. Il controllo vulnerability esegue il gestore di pacchetti del tuo progetto (npm audit, yarn audit, composer audit, bundle audit, pip-audit, govulncheck, cargo audit) all'interno della directory del progetto, con un ambiente ripulito e una home temporanea, così non può leggere i tuoi token. I gestori di pacchetti rispettano comunque la configurazione locale del progetto, e parte di quella configurazione può eseguire codice dal repository (uno yarnPath di Yarn, un alias Cargo, un plugin Composer). Scansionare i tuoi progetti è lo scopo di Preflight. Quando scansiona un repository di cui non ti fidi, come una pull request di un fork in CI, aggiungi --skip vulnerability.

ID dei Servizi Ignorabili

Tutti i servizi hanno controlli di validazione che verificano la corretta integrazione (variabili d'ambiente, pattern SDK, file di configurazione):

Pagamenti: stripe, paypal, braintree, paddle, lemonsqueezy

Tracciamento Errori: sentry, bugsnag, rollbar, honeybadger, datadog, newrelic, logrocket

Email Transazionali: postmark, sendgrid, mailgun, aws_ses, resend

Email Marketing: mailchimp, convertkit, beehiiv, aweber, activecampaign, campaignmonitor, drip, klaviyo, buttondown

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

Autenticazione: auth0, clerk, workos, firebase, supabase

Comunicazione: twilio, slack, discord, intercom, crisp

Infrastruttura: redis, sidekiq, rabbitmq, elasticsearch, convex

Storage e CDN: aws_s3, cloudinary, cloudflare

Ricerca: algolia

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

SEO: index_now

Consenso Cookie: cookieconsent, cookiebot, onetrust, termly, cookieyes, iubenda

Codici di Uscita

I codici 1 e 2 significano che la scansione è stata eseguita e ha segnalato qualcosa. Il codice 64 significa che non è mai arrivata a quel punto, quindi la CI può distinguere "questo progetto ha problemi" da "questa invocazione era sbagliata".

Completamenti Shell

Completamento con Tab per comandi, flag e ID dei controlli (inclusi i valori di --only e --skip):

# bash (aggiungi a ~/.bashrc)
source <(preflight completion bash)

# zsh (aggiungi a ~/.zshrc)
source <(preflight completion zsh)

# fish
preflight completion fish | source

L'output rispetta anche la variabile d'ambiente NO_COLOR.

Stack Supportati

Framework Backend

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

Framework Frontend

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

CMS Tradizionali

• WordPress, Craft CMS, Drupal, Ghost

Generatori di Siti Statici

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

CMS Headless

• Strapi, Sanity, Contentful, Prismic

Altro

• Siti statici

Integrazione CI

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

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

Licenza

MIT