@preflight-agent/cli 0.1.0

package/src/checks/graphql.ts

@@ -0,0 +1,87 @@
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+import type { CheckResult } from '../scan';
+
+export async function runGraphqlChecks(dir: string): Promise<CheckResult[]> {
+  const results: CheckResult[] = [];
+
+  const gqlFiles = await glob(`${dir}/**/*.{graphql,gql}`, { ignore: ['**/node_modules/**'] });
+  const gqlTsFiles = await glob(`${dir}/src/**/*.ts`, { ignore: ['**/node_modules/**'] });
+
+  const allGqlFiles = [...gqlFiles, ...gqlTsFiles.filter(f => {
+    const content = fs.readFileSync(f, 'utf-8');
+    return content.includes('graphql') || content.includes('GraphQL') || content.includes('gql`') || content.includes('apollo') || content.includes('urql');
+  })];
+
+  if (allGqlFiles.length === 0) {
+    results.push({ status: 'warn', message: 'No GraphQL files detected \u2014 skipping GraphQL checks' });
+    return results;
+  }
+
+  let hasDepthLimit = false;
+  let depthFile: string | undefined;
+
+  for (const file of allGqlFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (
+      content.includes('depthLimit') ||
+      content.includes('queryDepth') ||
+      content.includes('maxDepth') ||
+      content.includes('validationRules') ||
+      content.includes('complexity')
+    ) {
+      hasDepthLimit = true;
+      depthFile = path.relative(dir, file);
+      break;
+    }
+  }
+
+  if (hasDepthLimit) {
+    results.push({ status: 'pass', message: 'GraphQL query depth limiting found', file: depthFile });
+  } else {
+    results.push({ status: 'warn', message: 'No GraphQL depth limiting found \u2014 malicious queries can exhaust your server' });
+  }
+
+  let hasAuth = false;
+  let authFile: string | undefined;
+
+  for (const file of allGqlFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (
+      content.includes('context') && (
+        content.includes('token') ||
+        content.includes('auth') ||
+        content.includes('session') ||
+        content.includes('bearer')
+      )
+    ) {
+      hasAuth = true;
+      authFile = path.relative(dir, file);
+      break;
+    }
+  }
+
+  if (hasAuth) {
+    results.push({ status: 'pass', message: 'GraphQL authentication context found', file: authFile });
+  } else {
+    results.push({ status: 'warn', message: 'No GraphQL auth context detected \u2014 your GraphQL endpoint may be public' });
+  }
+
+  let introspectionDisabled = false;
+  for (const file of allGqlFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (content.includes('introspection') && (content.includes('false') || content.includes('disabled') || content.includes('0'))) {
+      introspectionDisabled = true;
+      break;
+    }
+  }
+
+  results.push(
+    introspectionDisabled
+      ? { status: 'pass', message: 'GraphQL introspection disabled in production' }
+      : { status: 'warn', message: 'GraphQL introspection may be enabled \u2014 attackers can discover your entire schema' }
+  );
+
+  return results;
+}

package/src/checks/index.ts

@@ -0,0 +1,9 @@
+export { runSecurityChecks } from './security';
+export { runAuthChecks } from './auth';
+export { runPaymentChecks } from './payments';
+export { runDatabaseChecks } from './database';
+export { runApiChecks } from './api';
+export { runWebChecks } from './web';
+export { runGraphqlChecks } from './graphql';
+export { runRealtimeChecks } from './realtime';
+export { runVulnerabilityChecks } from './vulnerabilities';

package/src/checks/payments.ts

@@ -0,0 +1,92 @@
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+import type { CheckResult } from '../scan';
+
+export async function runPaymentChecks(dir: string): Promise<CheckResult[]> {
+  const results: CheckResult[] = [];
+
+  const webhookFiles = await glob(
+    `${dir}/**/{webhook,webhooks,mpesa,stripe,payment}/**/*.{ts,tsx,js}`,
+    { ignore: ['**/node_modules/**', '**/.next/**'] }
+  );
+
+  const apiFiles = await glob(`${dir}/src/app/api/**/*.ts`, { ignore: ['**/node_modules/**'] });
+  const allFiles = [...new Set([...webhookFiles, ...apiFiles])];
+  const paymentRelatedFiles = allFiles.filter(f =>
+    /webhook|stripe|mpesa|payment|daraja|stk/i.test(f)
+  );
+
+  if (paymentRelatedFiles.length === 0) {
+    results.push({ status: 'warn', message: 'No payment-related files detected \u2014 skipping payment checks' });
+    return results;
+  }
+
+  let hasSignatureValidation = false;
+  let signatureFile: string | undefined;
+
+  for (const file of paymentRelatedFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (
+      content.includes('constructEvent') ||
+      content.includes('stripe.webhooks') ||
+      content.includes('X-Mpesa-Signature') ||
+      content.includes('validateWebhook') ||
+      content.includes('verifySignature') ||
+      content.includes('crypto.timingSafeEqual') ||
+      content.includes('hmac')
+    ) {
+      hasSignatureValidation = true;
+      signatureFile = path.relative(dir, file);
+      break;
+    }
+  }
+
+  if (hasSignatureValidation) {
+    results.push({ status: 'pass', message: 'Webhook signature validation found', file: signatureFile });
+  } else {
+    const firstFile = path.relative(dir, paymentRelatedFiles[0]);
+    results.push({
+      status: 'fail',
+      message: 'No webhook signature validation found \u2014 anyone can fake payment events',
+      file: firstFile,
+    });
+  }
+
+  let hasErrorHandling = false;
+  for (const file of paymentRelatedFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (content.includes('try') && content.includes('catch')) {
+      hasErrorHandling = true;
+      break;
+    }
+  }
+
+  if (hasErrorHandling) {
+    results.push({ status: 'pass', message: 'Error handling (try/catch) found in payment routes' });
+  } else {
+    results.push({ status: 'warn', message: 'No try/catch found in payment files \u2014 unhandled failures will crash' });
+  }
+
+  let hasIdempotency = false;
+  for (const file of paymentRelatedFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (
+      content.includes('idempotencyKey') ||
+      content.includes('idempotency_key') ||
+      content.includes('TransactionID') ||
+      content.includes('CheckoutRequestID')
+    ) {
+      hasIdempotency = true;
+      break;
+    }
+  }
+
+  results.push(
+    hasIdempotency
+      ? { status: 'pass', message: 'Idempotency keys found in payment flow' }
+      : { status: 'warn', message: 'No idempotency keys detected \u2014 duplicate payments may occur' }
+  );
+
+  return results;
+}

package/src/checks/realtime.ts

@@ -0,0 +1,96 @@
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+import type { CheckResult } from '../scan';
+
+export async function runRealtimeChecks(dir: string): Promise<CheckResult[]> {
+  const results: CheckResult[] = [];
+
+  const tsFiles = await glob(`${dir}/src/**/*.ts`, { ignore: ['**/node_modules/**', '**/.next/**'] });
+  const realtimeFiles = tsFiles.filter(f => {
+    const content = fs.readFileSync(f, 'utf-8');
+    return (
+      content.includes('websocket') ||
+      content.includes('WebSocket') ||
+      content.includes('ws://') ||
+      content.includes('wss://') ||
+      content.includes('socket') ||
+      content.includes('subscription') ||
+      content.includes('realtime') ||
+      content.includes('supabase') && content.includes('channel') ||
+      content.includes('broadcast') ||
+      content.includes('presence')
+    );
+  });
+
+  if (realtimeFiles.length === 0) {
+    results.push({ status: 'warn', message: 'No real-time features detected \u2014 skipping real-time checks' });
+    return results;
+  }
+
+  let hasCleanup = false;
+  let cleanupFile: string | undefined;
+
+  for (const file of realtimeFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (
+      content.includes('unsubscribe') ||
+      content.includes('unmount') ||
+      content.includes('cleanup') ||
+      content.includes('disconnect') ||
+      content.includes('removeChannel') ||
+      content.includes('destroy') ||
+      content.includes('close()')
+    ) {
+      hasCleanup = true;
+      cleanupFile = path.relative(dir, file);
+      break;
+    }
+  }
+
+  if (hasCleanup) {
+    results.push({ status: 'pass', message: 'Real-time connection cleanup found', file: cleanupFile });
+  } else {
+    results.push({ status: 'warn', message: 'No real-time cleanup detected \u2014 connections may leak and cause memory issues' });
+  }
+
+  let hasReconnect = false;
+  for (const file of realtimeFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (
+      content.includes('reconnect') ||
+      content.includes('retry') ||
+      content.includes('backoff')
+    ) {
+      hasReconnect = true;
+      break;
+    }
+  }
+
+  results.push(
+    hasReconnect
+      ? { status: 'pass', message: 'Reconnection logic found for real-time connections' }
+      : { status: 'warn', message: 'No reconnection logic detected \u2014 temporary network issues will drop connections permanently' }
+  );
+
+  let hasAuth = false;
+  for (const file of realtimeFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (
+      content.includes('token') ||
+      content.includes('auth') && (content.includes('channel') || content.includes('socket')) ||
+      content.includes('accessToken')
+    ) {
+      hasAuth = true;
+      break;
+    }
+  }
+
+  results.push(
+    hasAuth
+      ? { status: 'pass', message: 'Authentication found on real-time connections' }
+      : { status: 'warn', message: 'No authentication detected on real-time channels \u2014 anyone can connect' }
+  );
+
+  return results;
+}

package/src/checks/security.ts

@@ -0,0 +1,70 @@
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+import type { CheckResult } from '../scan';
+
+const DANGEROUS_PATTERNS = [
+  { pattern: /supabase.*service_role/i, label: 'Supabase service role key' },
+  { pattern: /sk-[a-zA-Z0-9]{20,}/,     label: 'OpenAI API key' },
+  { pattern: /STRIPE_SECRET_KEY/,        label: 'Stripe secret key' },
+  { pattern: /ANTHROPIC_API_KEY/,        label: 'Anthropic API key' },
+  { pattern: /Consumer_Secret/i,         label: 'M-Pesa consumer secret' },
+];
+
+const CLIENT_SIDE_DIRS = ['components', 'app', 'pages', 'src/app', 'src/pages', 'src/components', 'src/lib'];
+
+export async function runSecurityChecks(dir: string): Promise<CheckResult[]> {
+  const results: CheckResult[] = [];
+
+  const gitignorePath = path.join(dir, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const gitignore = fs.readFileSync(gitignorePath, 'utf-8');
+    if (gitignore.includes('.env')) {
+      results.push({ status: 'pass', message: '.env is gitignored' });
+    } else {
+      results.push({ status: 'fail', message: '.env is NOT gitignored \u2014 your secrets will be committed' });
+    }
+  } else {
+    results.push({ status: 'warn', message: 'No .gitignore found' });
+  }
+
+  const envExamplePath = path.join(dir, '.env.example');
+  if (fs.existsSync(envExamplePath)) {
+    results.push({ status: 'pass', message: '.env.example exists' });
+  } else {
+    results.push({ status: 'warn', message: 'No .env.example \u2014 collaborators won\'t know what vars to set' });
+  }
+
+  const clientFiles: string[] = [];
+  for (const clientDir of CLIENT_SIDE_DIRS) {
+    const fullDir = path.join(dir, clientDir);
+    if (fs.existsSync(fullDir)) {
+      const files = await glob(`${fullDir}/**/*.{ts,tsx,js,jsx}`, { ignore: ['**/node_modules/**'] });
+      clientFiles.push(...files);
+    }
+  }
+
+  for (const file of clientFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+    for (const { pattern, label } of DANGEROUS_PATTERNS) {
+      for (let i = 0; i < lines.length; i++) {
+        if (pattern.test(lines[i]) && !lines[i].trim().startsWith('//') && !lines[i].trim().startsWith('*')) {
+          const relativePath = path.relative(dir, file);
+          results.push({
+            status: 'fail',
+            message: `${label} found in client-side code`,
+            file: relativePath,
+            line: i + 1,
+          });
+        }
+      }
+    }
+  }
+
+  if (clientFiles.length > 0 && !results.some(r => r.status === 'fail' && r.message.includes('found in client-side'))) {
+    results.push({ status: 'pass', message: 'No dangerous secrets found in client-side code' });
+  }
+
+  return results;
+}

package/src/checks/vulnerabilities.ts

@@ -0,0 +1,196 @@
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+import type { CheckResult } from '../scan';
+
+export async function runVulnerabilityChecks(dir: string): Promise<CheckResult[]> {
+  const results: CheckResult[] = [];
+
+  const allTsFiles = await glob(`${dir}/src/**/*.{ts,tsx,js,jsx}`, { ignore: ['**/node_modules/**', '**/.next/**'] });
+  const allFiles = await glob(`${dir}/**/*.{ts,tsx,js,jsx,json,env,yml,yaml,config.*}`, { ignore: ['**/node_modules/**', '**/.next/**', '**/dist/**'] });
+
+  // --- 1. XSS: dangerouslySetInnerHTML / innerHTML ---
+  let hasUnsafeHTML = false;
+  let unsafeHTMLFile: string | undefined;
+
+  for (const file of allTsFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (content.includes('dangerouslySetInnerHTML') || content.includes('.innerHTML =')) {
+      hasUnsafeHTML = true;
+      unsafeHTMLFile = path.relative(dir, file);
+      break;
+    }
+  }
+
+  results.push(
+    hasUnsafeHTML
+      ? { status: 'warn', message: 'dangerouslySetInnerHTML or innerHTML assignment found \u2014 potential XSS risk', file: unsafeHTMLFile }
+      : { status: 'pass', message: 'No dangerouslySetInnerHTML or innerHTML assignments found' }
+  );
+
+  // --- 2. eval() usage ---
+  let hasEval = false;
+  let evalFile: string | undefined;
+
+  for (const file of allTsFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const trimmed = lines[i].trim();
+      if (/eval\s*\(/.test(trimmed) && !trimmed.startsWith('//') && !trimmed.startsWith('*')) {
+        hasEval = true;
+        evalFile = path.relative(dir, file);
+        break;
+      }
+    }
+    if (hasEval) break;
+  }
+
+  results.push(
+    hasEval
+      ? { status: 'fail', message: 'eval() usage detected \u2014 arbitrary code execution risk', file: evalFile }
+      : { status: 'pass', message: 'No eval() usage detected' }
+  );
+
+  // --- 3. Sniffing protection: X-Content-Type-Options ---
+  const configFiles = [
+    'next.config.ts', 'next.config.js', 'next.config.mjs',
+    '.htaccess', 'nginx.conf', 'web.config',
+  ];
+
+  let hasNosniff = false;
+  let nosniffFile: string | undefined;
+
+  for (const cfg of configFiles) {
+    const cfgPath = path.join(dir, cfg);
+    if (fs.existsSync(cfgPath)) {
+      const content = fs.readFileSync(cfgPath, 'utf-8');
+      if (content.includes('nosniff') || content.includes('X-Content-Type-Options')) {
+        hasNosniff = true;
+        nosniffFile = cfg;
+        break;
+      }
+    }
+  }
+
+  results.push(
+    hasNosniff
+      ? { status: 'pass', message: 'X-Content-Type-Options: nosniff found \u2014 MIME sniffing protection enabled', file: nosniffFile }
+      : { status: 'warn', message: 'No X-Content-Type-Options: nosniff found \u2014 browser may MIME-sniff responses' }
+  );
+
+  // --- 4. HSTS ---
+  let hasHSTS = false;
+  let hstsFile: string | undefined;
+
+  for (const cfg of configFiles) {
+    const cfgPath = path.join(dir, cfg);
+    if (fs.existsSync(cfgPath)) {
+      const content = fs.readFileSync(cfgPath, 'utf-8');
+      if (content.includes('Strict-Transport-Security') || content.includes('HSTS') || content.includes('hsts')) {
+        hasHSTS = true;
+        hstsFile = cfg;
+        break;
+      }
+    }
+  }
+
+  results.push(
+    hasHSTS
+      ? { status: 'pass', message: 'HSTS (Strict-Transport-Security) configured', file: hstsFile }
+      : { status: 'warn', message: 'No HSTS header found \u2014 users may connect over HTTP instead of HTTPS' }
+  );
+
+  // --- 5. Mixed content: http:// URLs in source ---
+  let hasMixedContent = false;
+  const mixedContentFiles: string[] = [];
+
+  for (const file of allTsFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    const httpMatches = content.match(/https?:\/\/(?!localhost)(?!127\.0\.0\.1)(?![\w.-]*\.\w{2,}\/)[^\s"'`)*]+/g);
+    if (httpMatches) {
+      const insecureUrls = httpMatches.filter(u => u.startsWith('http://'));
+      if (insecureUrls.length > 0) {
+        hasMixedContent = true;
+        mixedContentFiles.push(path.relative(dir, file));
+      }
+    }
+  }
+
+  results.push(
+    hasMixedContent
+      ? { status: 'warn', message: `http:// URLs found in ${mixedContentFiles.length} file(s) \u2014 mixed content vulnerability`, file: mixedContentFiles[0] }
+      : { status: 'pass', message: 'No mixed content (http:// URLs) detected in source' }
+  );
+
+  // --- 6. CSRF protection ---
+  const csrfPatterns = [
+    'csrf', 'CSRF', 'csrfToken', 'xsrf', 'XSRF',
+    'SameSite', 'sameSite', 'same-site',
+    'doubleSubmit', 'csrfProtection',
+  ];
+
+  let hasCSRF = false;
+  let csrfFile: string | undefined;
+
+  for (const file of allTsFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    for (const pattern of csrfPatterns) {
+      if (content.includes(pattern)) {
+        hasCSRF = true;
+        csrfFile = path.relative(dir, file);
+        break;
+      }
+    }
+    if (hasCSRF) break;
+  }
+
+  results.push(
+    hasCSRF
+      ? { status: 'pass', message: 'CSRF protection detected (token or SameSite cookie)', file: csrfFile }
+      : { status: 'warn', message: 'No CSRF protection detected \u2014 forms and API mutations may be vulnerable to cross-site requests' }
+  );
+
+  // --- 7. Debug mode / information disclosure ---
+  let hasDebugLeak = false;
+  let debugFile: string | undefined;
+
+  for (const file of allTsFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (
+        (line.includes('debug: true') || line.includes('debug = true') || line.includes('isDebug = true')) &&
+        !line.trim().startsWith('//')
+      ) {
+        hasDebugLeak = true;
+        debugFile = path.relative(dir, file);
+        break;
+      }
+    }
+    if (hasDebugLeak) break;
+  }
+
+  results.push(
+    hasDebugLeak
+      ? { status: 'warn', message: 'Debug mode enabled in source \u2014 may expose sensitive info in production', file: debugFile }
+      : { status: 'pass', message: 'No debug mode flags detected in source' }
+  );
+
+  // --- 8. Check .gitignore for common build artifacts ---
+  const gitignorePath = path.join(dir, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const gitignore = fs.readFileSync(gitignorePath, 'utf-8');
+    const expectedEntries = ['.next', 'dist', 'build', '.env.local', 'coverage', '.turbo'];
+    const missing = expectedEntries.filter(e => !gitignore.includes(e));
+
+    if (missing.length === 0) {
+      results.push({ status: 'pass', message: 'All common build artifacts are gitignored (.next, dist, build, .env.local)' });
+    } else {
+      results.push({ status: 'warn', message: `Build artifacts not gitignored: ${missing.join(', ')} \u2014 they may leak in the repo` });
+    }
+  }
+
+  return results;
+}

package/src/checks/web.ts

@@ -0,0 +1,65 @@
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+import type { CheckResult } from '../scan';
+
+export async function runWebChecks(dir: string): Promise<CheckResult[]> {
+  const results: CheckResult[] = [];
+
+  const nextConfigPaths = [
+    path.join(dir, 'next.config.ts'),
+    path.join(dir, 'next.config.js'),
+    path.join(dir, 'next.config.mjs'),
+  ];
+
+  const existingConfigs = nextConfigPaths.filter(fs.existsSync);
+
+  if (existingConfigs.length > 0) {
+    const content = fs.readFileSync(existingConfigs[0], 'utf-8');
+    const hasCSP = content.includes('Content-Security-Policy') || content.includes('csp');
+    const hasFrameOptions = content.includes('X-Frame-Options') || content.includes('frame-ancestors');
+    const hasCORS = content.includes('cors') || content.includes('CORS') || content.includes('Access-Control');
+
+    if (hasCSP) {
+      results.push({ status: 'pass', message: 'Content Security Policy (CSP) configured', file: path.relative(dir, existingConfigs[0]) });
+    } else {
+      results.push({ status: 'warn', message: 'No Content Security Policy (CSP) found \u2014 your app is vulnerable to XSS' });
+    }
+
+    if (hasFrameOptions) {
+      results.push({ status: 'pass', message: 'Clickjacking protection found (X-Frame-Options / frame-ancestors)' });
+    } else {
+      results.push({ status: 'warn', message: 'No clickjacking protection \u2014 your app can be embedded in iframes' });
+    }
+
+    if (hasCORS) {
+      results.push({ status: 'pass', message: 'CORS configuration detected' });
+    } else {
+      results.push({ status: 'warn', message: 'No explicit CORS configuration found' });
+    }
+  } else {
+    results.push({ status: 'warn', message: 'No Next.js config found \u2014 skipping security header checks' });
+  }
+
+  const cookieFiles = await glob(`${dir}/**/*.ts`, { ignore: ['**/node_modules/**', '**/.next/**'] });
+  let hasSecureCookies = false;
+  let cookieFile: string | undefined;
+
+  for (const file of cookieFiles) {
+    const content = fs.readFileSync(file, 'utf-8');
+    const hasCookie = content.includes('cookie') || content.includes('Cookie') || content.includes('cookies');
+    if (hasCookie && (content.includes('httpOnly') || content.includes('secure') || content.includes('sameSite'))) {
+      hasSecureCookies = true;
+      cookieFile = path.relative(dir, file);
+      break;
+    }
+  }
+
+  results.push(
+    hasSecureCookies
+      ? { status: 'pass', message: 'Cookie security flags (httpOnly/secure/sameSite) detected', file: cookieFile }
+      : { status: 'warn', message: 'No secure cookie flags detected \u2014 cookies may be accessible to JavaScript' }
+  );
+
+  return results;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { runScan } from './scan';
+
+const program = new Command();
+
+program
+  .name('preflight')
+  .description('Pre-deploy checklist CLI for vibe coders')
+  .version('0.1.0');
+
+program
+  .command('scan [dir]')
+  .description('Scan a project for common pre-deploy issues')
+  .option('--json', 'Output results as JSON')
+  .option('--strict', 'Exit with code 1 if any checks fail')
+  .option('--only <category>', 'Run only one category: security|auth|payments|database|api|web|graphql|realtime|vulnerabilities')
+  .action(async (dir: string = '.', options) => {
+    await runScan(dir, options);
+  });
+
+program.parse();

package/src/reporter.ts

@@ -0,0 +1,47 @@
+import chalk from 'chalk';
+import type { CategoryResult, CheckResult } from './scan';
+
+function icon(status: CheckResult['status']) {
+  if (status === 'pass') return chalk.green('\u2705');
+  if (status === 'fail') return chalk.red('\u274C');
+  return chalk.yellow('\u26A0\uFE0F');
+}
+
+function score(categories: CategoryResult[]) {
+  const all = categories.flatMap((c) => c.checks);
+  const passed = all.filter((c) => c.status === 'pass').length;
+  return { passed, total: all.length };
+}
+
+export function renderReport(dir: string, categories: CategoryResult[]) {
+  console.log('');
+  console.log(chalk.bold('\u{1F6EB} Agent Preflight \u2014 Pre-Deploy Scan'));
+  console.log(chalk.dim(`Scanning: ${dir}`));
+  console.log('');
+
+  for (const category of categories) {
+    console.log(chalk.bold(`  ${category.name}`));
+    for (const check of category.checks) {
+      const location =
+        check.file
+          ? chalk.dim(` (${check.file}${check.line ? `:${check.line}` : ''})`)
+          : '';
+      console.log(`  ${icon(check.status)}  ${check.message}${location}`);
+    }
+    console.log('');
+  }
+
+  const { passed, total } = score(categories);
+  const ratio = `${passed}/${total}`;
+  const fails = categories.flatMap((c) => c.checks).filter((c) => c.status === 'fail');
+
+  if (fails.length === 0) {
+    console.log(chalk.green(`Score: ${ratio} \u2014 All clear. Ready to deploy. \u{1F680}`));
+  } else {
+    console.log(
+      chalk.red(`Score: ${ratio} \u2014 Fix ${fails.length} critical issue${fails.length > 1 ? 's' : ''} before deploying.`)
+    );
+  }
+
+  console.log('');
+}