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

سكربت Shell

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 seo_meta,og_twitter
preflight scan --skip vulnerability,secrets

# كتم فحص
preflight ignore sitemap

# إلغاء كتم فحص
preflight unignore sitemap

# قائمة بجميع معرفات الفحوصات
preflight checks

مهارة الوكيل

يتضمن هذا المستودع مهارة وكيل متوافقة مع skills.sh في skills/preflight/SKILL.md. تمنح وكلاء البرمجة سير عمل 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

لوحة المعلومات والاقتراحات بالذكاء الاصطناعي

Preflight قابلة للاستخدام بالكامل من سطر الأوامر دون الحاجة إلى حساب. تضيف لوحة المعلومات الاختيارية في app.preflight.sh سجلاً مستضافاً لعمليات الفحص واقتراحات إصلاح مولّدة بالذكاء الاصطناعي لكل نتيجة. لا تغادر شيفرتك البرمجية جهازك أبداً: يتم تشغيل الفحص محلياً، ويتم إرسال ملخص منقح فقط من النتائج (معرفات الفحوصات، والحالات، والرسائل، دون قيم سرية أو محتويات ملفات) عند النشر.

أنشئ حساباً مجانياً، ثم اربط 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 remote الخاص به، وهو نفس المفتاح المستخدم عند النشر.

افتح أي فحص فاشل أو تحذيري في تشغيل منشور لتوليد إصلاح خطوة بخطوة مصمم خصيصاً لحزمتك التقنية المكتشفة، مع أوامر وشيفرات جاهزة للنسخ.

• مجاني يتضمن 5 عمليات نشر شهرياً.
• استخدم مفتاحك الخاص: أضف مفتاح API من OpenAI أو Anthropic في إعدادات لوحة المعلومات ويبقى النشر مجانياً وغير محدود (تدفع لمزود الخدمة مباشرة).
• مُدار (5 دولارات/شهرياً): نغطي تكاليف الذكاء الاصطناعي وتكون التشغيلات غير محدودة، دون الحاجة إلى مفتاح 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

الذكاء الاصطناعي / نماذج اللغة الكبيرة

• 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"  # optional - probed with a GET; a 404 or no response is reported

  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
  - llms_txt
  - google_analytics

كتم الفحوصات والخدمات

قم بكتم فحوصات أو خدمات محددة باستخدام preflight ignore <id>:

preflight ignore sitemap        # تجاهل فحص sitemap
preflight ignore sentry         # تجاهل التحقق من خدمة Sentry
preflight unignore sitemap      # إعادة تفعيل فحص sitemap
preflight checks                # قائمة بجميع المعرفات القابلة للكتم

إدراج نتيجة أسرار واحدة في القائمة البيضاء

فضل إدراج نتيجة فردية في القائمة البيضاء على كتم فحص secrets بالكامل. أضف استثناءات لمرة واحدة من سطر الأوامر:

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

يضيف ذلك إدخال مسار تحت checks.secrets.allowlist في ملف preflight.yml الخاص بك. حقل path هو نمط doublestar glob (** يطابق عبر الدلائل) يتم حله مقابل مسار الملف النسبي للمشروع.

ثبّت بصمة الإصبع. قائمة بيضاء بالمسار فقط تقبل بصمت أي سر مستقبلي يُضاف إلى ذلك الملف. عدّل الإدخال وأضف fingerprint: "sha256:<hex>" — وهو SHA-256 لقيمة السر المكتشف. الآن إذا تم تدوير المفتاح أو ظهر سر مختلف في نفس الملف، يعيد preflight التنبيه.

تتم مطابقة النتائج عبر المسار + بصمة الإصبع، وليس الملف بأكمله. بصمة إصبع مدرجة في القائمة البيضاء داخل ملف لا تكتم الأسرار الأخرى في أسطر أخرى من نفس الملف.

معرفات الفحوصات القابلة للكتم

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

أصبح كل معرف فحص الآن بصيغة snake_case. تستمر أسماء camelCase القديمة في العمل في كل مكان يُقبل فيه المعرف (قوائم ignore: و--only و--skip وpreflight ignore) عبر خط الإصدار 1.x، مع ملاحظة على stderr، وتُزال في 2.0. يكتب preflight ignore الاسم الجديد. المفاتيح تحت checks: في preflight.yml (healthEndpoint, seoMeta, ...) هي مخطط منفصل ولم تتغير.

ملاحظة حول فحص شيفرة لا تثق بها

يقرأ كل فحص ملفات؛ أحدها يشغل برنامجاً. ينفذ فحص vulnerability مدير الحزم الخاص بمشروعك (npm audit, yarn audit, composer audit, bundle audit, pip-audit, govulncheck, cargo audit) داخل دليل المشروع، مع بيئة منقحة ومنزل مؤقت بحيث لا يمكنه قراءة رموزك المميزة. لا تزال مديرو الحزم يحترمون الإعدادات المحلية للمشروع، وبعض تلك الإعدادات يمكنها تشغيل شيفرة من المستودع (مسار yarnPath في Yarn، أو اسم مستعار في Cargo، أو إضافة Composer). فحص مشاريعك الخاصة هو الغرض من Preflight. عند فحص مستودع لا تثق به، مثل طلب سحب من fork في CI، أضف --skip vulnerability.

معرفات الخدمات القابلة للكتم

جميع الخدمات لديها فحوصات تحقق تتحقق من التكامل الصحيح (متغيرات البيئة، أنماط 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

الذكاء الاصطناعي: 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 التمييز بين "هذا المشروع لديه مشاكل" و"هذا الاستدعاء كان خاطئاً".

إكمالات Shell

إكمال تلقائي بعلامة التبويب للأوامر والخيارات ومعرفات الفحوصات (بما في ذلك قيم --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

أنظمة إدارة المحتوى التقليدية

• WordPress, Craft CMS, Drupal, Ghost

مولدو المواقع الثابتة

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

أنظمة إدارة المحتوى بدون واجهة

• 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