guardrail-ship 1.0.0

package/src/reality-mode/explorer/templates/github-action.yml

@@ -0,0 +1,132 @@
+# Guardrail Reality Mode - GitHub Actions Workflow
+#
+# This workflow runs Reality Mode tests on every PR and deployment.
+# Copy this to .github/workflows/reality-mode.yml in your repo.
+#
+# Prerequisites:
+# - Set REALITY_TEST_URL secret (your staging/preview URL)
+# - Set REALITY_AUTH secret (optional: email:password for auth)
+
+name: Reality Mode Tests
+
+on:
+  pull_request:
+    branches: [main, master]
+  deployment_status:
+  workflow_dispatch:
+    inputs:
+      url:
+        description: "URL to test"
+        required: true
+        type: string
+
+jobs:
+  reality-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Playwright
+        run: |
+          npm install -D @playwright/test
+          npx playwright install chromium --with-deps
+
+      - name: Install Guardrail
+        run: npm install -g guardrail
+
+      - name: Determine URL
+        id: url
+        run: |
+          if [ -n "${{ github.event.inputs.url }}" ]; then
+            echo "url=${{ github.event.inputs.url }}" >> $GITHUB_OUTPUT
+          elif [ -n "${{ secrets.REALITY_TEST_URL }}" ]; then
+            echo "url=${{ secrets.REALITY_TEST_URL }}" >> $GITHUB_OUTPUT
+          elif [ "${{ github.event.deployment_status.state }}" == "success" ]; then
+            echo "url=${{ github.event.deployment_status.target_url }}" >> $GITHUB_OUTPUT
+          else
+            echo "url=" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run Reality Mode
+        if: steps.url.outputs.url != ''
+        run: |
+          guardrail reality \
+            --url "${{ steps.url.outputs.url }}" \
+            ${{ secrets.REALITY_AUTH && format('--auth "{0}"', secrets.REALITY_AUTH) || '' }} \
+            --junit \
+            --output .guardrail/reality
+        continue-on-error: true
+
+      - name: Upload Results
+        if: always() && steps.url.outputs.url != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: reality-mode-results
+          path: |
+            .guardrail/reality/reality-report.html
+            .guardrail/reality/explorer-results.json
+            .guardrail/reality/videos/
+            .guardrail/reality/trace.zip
+          retention-days: 14
+
+      - name: Upload JUnit Results
+        if: always() && steps.url.outputs.url != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results
+          path: .guardrail/reality/junit-results.xml
+
+      - name: Publish Test Results
+        if: always() && steps.url.outputs.url != ''
+        uses: dorny/test-reporter@v1
+        with:
+          name: Reality Mode Tests
+          path: .guardrail/reality/junit-results.xml
+          reporter: java-junit
+          fail-on-error: false
+
+      - name: Comment on PR
+        if: github.event_name == 'pull_request' && steps.url.outputs.url != ''
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = '.guardrail/reality/explorer-results.json';
+
+            if (!fs.existsSync(path)) {
+              console.log('No results file found');
+              return;
+            }
+
+            const results = JSON.parse(fs.readFileSync(path, 'utf8'));
+            const score = results.score || 0;
+            const emoji = score >= 80 ? '🟢' : score >= 60 ? '🟡' : '🔴';
+
+            const body = `## ${emoji} Reality Mode Score: ${score}/100
+
+            | Metric | Result |
+            |--------|--------|
+            | Routes | ${results.coverage?.routes || 0}/${results.routes?.length || 0} working |
+            | Elements | ${results.coverage?.elements || 0}/${results.elements?.length || 0} working |
+            | Forms | ${results.coverage?.forms || 0}/${results.forms?.length || 0} working |
+            | Errors | ${results.errors?.length || 0} captured |
+
+            ${score >= 80 ? '✅ **Ready to ship!**' : score >= 60 ? '⚠️ **Needs some work**' : '❌ **Critical issues found**'}
+
+            📊 [View Full Report](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})
+            `;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body
+            });

package/src/reality-mode/explorer/types.ts

@@ -0,0 +1,356 @@
+/**
+ * Reality Explorer Types
+ *
+ * Types for the comprehensive app exploration system that actually
+ * tests everything - buttons, forms, modals, auth flows, etc.
+ */
+
+// ============================================================================
+// App Surface Discovery
+// ============================================================================
+
+export interface DiscoveredRoute {
+  path: string;
+  method: "GET" | "POST" | "PUT" | "DELETE";
+  source: "link" | "router" | "api-call" | "redirect";
+  requiresAuth: boolean;
+  visited: boolean;
+  status?: number;
+  error?: string;
+}
+
+export interface DiscoveredElement {
+  id: string;
+  selector: string;
+  type:
+    | "button"
+    | "link"
+    | "input"
+    | "form"
+    | "modal-trigger"
+    | "dropdown"
+    | "tab"
+    | "accordion";
+  text: string;
+  page: string;
+  isDestructive: boolean;
+  tested: boolean;
+  result?: ElementTestResult;
+}
+
+export interface DiscoveredForm {
+  id: string;
+  selector: string;
+  page: string;
+  action?: string;
+  method: string;
+  fields: FormField[];
+  submitButton?: string;
+  tested: boolean;
+  result?: FormTestResult;
+}
+
+export interface FormField {
+  name: string;
+  type: string;
+  required: boolean;
+  selector: string;
+  placeholder?: string;
+  pattern?: string;
+}
+
+export interface DiscoveredAPI {
+  url: string;
+  method: string;
+  calledFrom: string;
+  status?: number;
+  responseTime?: number;
+  error?: string;
+}
+
+export interface AppSurface {
+  routes: DiscoveredRoute[];
+  elements: DiscoveredElement[];
+  forms: DiscoveredForm[];
+  apis: DiscoveredAPI[];
+  timestamp: string;
+}
+
+// ============================================================================
+// Test Results
+// ============================================================================
+
+export interface ElementTestResult {
+  success: boolean;
+  action: "click" | "hover" | "focus";
+  beforeState: PageState;
+  afterState: PageState;
+  changes: StateChange[];
+  errors: CapturedError[];
+  networkCalls: NetworkCall[];
+  duration: number;
+  screenshot?: string;
+}
+
+export interface FormTestResult {
+  success: boolean;
+  fieldsFilledCount: number;
+  submitAttempted: boolean;
+  submitSucceeded: boolean;
+  validationErrors: string[];
+  networkCalls: NetworkCall[];
+  errors: CapturedError[];
+  duration: number;
+  screenshot?: string;
+}
+
+export interface PageState {
+  url: string;
+  title: string;
+  modalsOpen: number;
+  loadingIndicators: number;
+  errorMessages: string[];
+  domHash: string;
+}
+
+export interface StateChange {
+  type: "url" | "modal" | "dom" | "console" | "network";
+  description: string;
+  significance: "major" | "minor" | "none";
+}
+
+export interface CapturedError {
+  type: "console" | "network" | "uncaught" | "react-boundary";
+  message: string;
+  stack?: string;
+  url?: string;
+  timestamp: number;
+}
+
+export interface NetworkCall {
+  url: string;
+  method: string;
+  status: number;
+  duration: number;
+  requestBody?: string;
+  responsePreview?: string;
+  error?: string;
+}
+
+// ============================================================================
+// Critical Flows
+// ============================================================================
+
+export interface CriticalFlow {
+  id: string;
+  name: string;
+  description: string;
+  steps: FlowStep[];
+  assertions: FlowAssertion[];
+  required: boolean;
+}
+
+export interface FlowStep {
+  action: "navigate" | "click" | "fill" | "wait" | "assert";
+  target?: string;
+  value?: string;
+  timeout?: number;
+}
+
+export interface FlowAssertion {
+  type:
+    | "url-contains"
+    | "element-visible"
+    | "element-hidden"
+    | "cookie-exists"
+    | "localstorage-has"
+    | "network-success"
+    | "no-errors";
+  value: string;
+  critical: boolean;
+}
+
+export interface FlowResult {
+  flow: CriticalFlow;
+  success: boolean;
+  stepsCompleted: number;
+  stepsTotal: number;
+  assertionsPassed: number;
+  assertionsTotal: number;
+  failedAt?: string;
+  errors: CapturedError[];
+  duration: number;
+  trace?: string;
+  video?: string;
+}
+
+// ============================================================================
+// Coverage & Scoring
+// ============================================================================
+
+export interface CoverageMetrics {
+  routes: {
+    discovered: number;
+    visited: number;
+    successful: number;
+    blocked: number;
+    percentage: number;
+  };
+  elements: {
+    discovered: number;
+    tested: number;
+    successful: number;
+    skippedDestructive: number;
+    percentage: number;
+  };
+  forms: {
+    discovered: number;
+    tested: number;
+    successful: number;
+    blockedByAuth: number;
+    percentage: number;
+  };
+  apis: {
+    discovered: number;
+    called: number;
+    successful: number;
+    failed: number;
+    percentage: number;
+  };
+  flows: {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    percentage: number;
+  };
+}
+
+export interface RealityScore {
+  overall: number; // 0-100
+  breakdown: {
+    coverage: number; // 40 points max
+    functionality: number; // 35 points max
+    stability: number; // 15 points max
+    ux: number; // 10 points max
+  };
+  grade: "A" | "B" | "C" | "D" | "F";
+  verdict: "ship-it" | "needs-work" | "broken";
+}
+
+// ============================================================================
+// Explorer Config
+// ============================================================================
+
+export interface ExplorerConfig {
+  baseUrl: string;
+  maxPages: number;
+  maxActionsPerPage: number;
+  timeout: number;
+  headless: boolean;
+
+  // Auth config
+  auth?: {
+    loginUrl: string;
+    credentials: {
+      emailField: string;
+      passwordField: string;
+      email: string;
+      password: string;
+    };
+    successIndicator: string;
+  };
+
+  // Safety
+  allowDestructive: boolean;
+  destructivePatterns: string[];
+
+  // Output
+  outputDir: string;
+  captureVideo: boolean;
+  captureTrace: boolean;
+  captureScreenshots: boolean;
+
+  // Custom flows
+  flows?: CriticalFlow[];
+}
+
+// ============================================================================
+// Final Report
+// ============================================================================
+
+export interface ExplorerReport {
+  summary: {
+    score: RealityScore;
+    coverage: CoverageMetrics;
+    duration: number;
+    timestamp: string;
+  };
+
+  surface: AppSurface;
+
+  results: {
+    routes: RouteResult[];
+    elements: ElementResult[];
+    forms: FormResult[];
+    flows: FlowResult[];
+  };
+
+  failures: {
+    critical: FailureReport[];
+    warnings: FailureReport[];
+  };
+
+  recommendations: Recommendation[];
+
+  artifacts: {
+    traces: string[];
+    videos: string[];
+    screenshots: string[];
+  };
+}
+
+export interface RouteResult {
+  route: DiscoveredRoute;
+  status: "success" | "error" | "blocked" | "skipped";
+  responseTime?: number;
+  errors: CapturedError[];
+}
+
+export interface ElementResult {
+  element: DiscoveredElement;
+  status: "success" | "error" | "no-change" | "skipped";
+  result?: ElementTestResult;
+}
+
+export interface FormResult {
+  form: DiscoveredForm;
+  status:
+    | "success"
+    | "validation-error"
+    | "submit-error"
+    | "blocked"
+    | "skipped";
+  result?: FormTestResult;
+}
+
+export interface FailureReport {
+  id: string;
+  type: "route" | "element" | "form" | "flow" | "api";
+  severity: "critical" | "warning";
+  title: string;
+  description: string;
+  location: string;
+  rootCause?: string;
+  reproduction: string[];
+  screenshot?: string;
+  trace?: string;
+}
+
+export interface Recommendation {
+  priority: "high" | "medium" | "low";
+  category: "functionality" | "auth" | "ux" | "performance" | "stability";
+  title: string;
+  description: string;
+  fix?: string;
+}

package/src/reality-mode/fake-success-detector.ts

@@ -0,0 +1,89 @@
+import { ReplayStep, FakeSuccessResult } from "./types";
+
+export class FakeSuccessDetector {
+  /**
+   * Analyze a replay to find "Fake Success" patterns
+   * i.e., User clicked "Save" -> UI showed success -> No backend write happened
+   */
+  detect(replay: ReplayStep[]): FakeSuccessResult[] {
+    const results: FakeSuccessResult[] = [];
+    const saveActionPatterns = [
+      /save/i,
+      /update/i,
+      /create/i,
+      /submit/i,
+      /confirm/i,
+      /send/i,
+      /pay/i,
+    ];
+
+    // Iterate through replay to find "Write" actions
+    for (let i = 0; i < replay.length; i++) {
+      const step = replay[i];
+      if (!step || step.type !== "action" || !step.data?.selector) continue;
+
+      const selector = step.data.selector;
+      const isWriteAction = saveActionPatterns.some((p) => p.test(selector));
+
+      if (isWriteAction) {
+        // Look ahead for network activity (next 5 seconds or until next action)
+        const subsequentSteps = this.getSubsequentSteps(replay, i, 5000);
+        const writeRequests = subsequentSteps.filter(
+          (s) =>
+            s.type === "request" &&
+            ["POST", "PUT", "PATCH", "DELETE"].includes(s.data.method),
+        );
+
+        if (writeRequests.length === 0) {
+          // No write request found!
+          // But maybe it's a client-side only app?
+          // Or maybe the request happened but we missed it?
+          // Or maybe it's "Fake Success".
+
+          results.push({
+            isFake: true,
+            score: 0,
+            evidence: [
+              `Clicked "${selector}" but no POST/PUT/PATCH/DELETE request followed.`,
+            ],
+            actionStep: step,
+          });
+        } else {
+          // Write request found. Check if it looked real.
+          // (TrafficClassifier handles the quality of the request/response)
+          results.push({
+            isFake: false,
+            score: 100,
+            evidence: [
+              `Clicked "${selector}" triggered ${writeRequests.length} write request(s).`,
+            ],
+            actionStep: step,
+          });
+        }
+      }
+    }
+
+    return results;
+  }
+
+  private getSubsequentSteps(
+    replay: ReplayStep[],
+    startIndex: number,
+    timeWindow: number,
+  ): ReplayStep[] {
+    const steps: ReplayStep[] = [];
+    const startStep = replay[startIndex];
+    if (!startStep) return steps;
+
+    const startTime = startStep.timestamp;
+
+    for (let i = startIndex + 1; i < replay.length; i++) {
+      const step = replay[i];
+      if (!step) break;
+      if (step.timestamp - startStep.timestamp > timeWindow) break;
+      steps.push(step);
+    }
+
+    return steps;
+  }
+}

package/src/reality-mode/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Reality Mode - Runtime Fake Detection
+ *
+ * "Stop shipping pretend features. Guardrail runs your app and catches the lies."
+ *
+ * A literal "flight recorder" for fake apps.
+ */
+
+export {
+  RealityScanner,
+  realityScanner,
+  DEFAULT_FAKE_PATTERNS,
+} from "./reality-scanner";
+
+export * from "./types";
+export { ReportGenerator } from "./report-generator";
+export { TrafficClassifier } from "./traffic-classifier";
+export { FakeSuccessDetector } from "./fake-success-detector";
+export { AuthEnforcer } from "./auth-enforcer";

package/src/reality-mode/reality-scanner.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Reality Mode - Runtime Fake Detection
+ *
+ * "Stop shipping pretend features. Guardrail runs your app and catches the lies."
+ *
+ * This module spins up the app, intercepts network calls, clicks through the UI,
+ * and detects:
+ * - Calls to localhost, jsonplaceholder, staging domains, ngrok
+ * - Routes returning demo/placeholder responses
+ * - Silent fallback success patterns
+ * - Mock billing and fake invoice IDs
+ *
+ * The killer feature: a "flight recorder" replay showing exactly what happened.
+ */
+export interface FakePattern {
+  id: string;
+  name: string;
+  description: string;
+  severity: "critical" | "warning" | "info";
+  detect: (request: InterceptedRequest | InterceptedResponse) => boolean;
+}
+export interface InterceptedRequest {
+  type: "request";
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+  timestamp: number;
+}
+export interface InterceptedResponse {
+  type: "response";
+  url: string;
+  status: number;
+  headers: Record<string, string>;
+  body?: string;
+  timestamp: number;
+}
+export interface UserAction {
+  type: "click" | "input" | "navigation" | "scroll";
+  selector?: string;
+  value?: string;
+  url?: string;
+  timestamp: number;
+  screenshot?: string;
+}
+export interface FakeDetection {
+  pattern: FakePattern;
+  request?: InterceptedRequest;
+  response?: InterceptedResponse;
+  action?: UserAction;
+  timestamp: number;
+  evidence: string;
+}
+export interface ReplayStep {
+  timestamp: number;
+  action?: UserAction;
+  request?: InterceptedRequest;
+  response?: InterceptedResponse;
+  detections: FakeDetection[];
+  screenshot?: string;
+}
+export interface RealityModeResult {
+  verdict: "real" | "fake" | "suspicious";
+  score: number;
+  detections: FakeDetection[];
+  replay: ReplayStep[];
+  summary: {
+    totalRequests: number;
+    fakeRequests: number;
+    totalActions: number;
+    criticalIssues: number;
+    warnings: number;
+  };
+  timestamp: string;
+  duration: number;
+}
+export interface RealityModeConfig {
+  baseUrl: string;
+  timeout: number;
+  patterns: FakePattern[];
+  clickPaths: string[][];
+  screenshotOnDetection: boolean;
+  headless: boolean;
+}
+export declare const DEFAULT_FAKE_PATTERNS: FakePattern[];
+export declare class RealityScanner {
+  private config;
+  private replay;
+  private detections;
+  private requests;
+  private responses;
+  private actions;
+  constructor(config?: Partial<RealityModeConfig>);
+  /**
+   * Generate Playwright test code for Reality Mode scanning
+   */
+  generatePlaywrightTest(config: {
+    baseUrl: string;
+    clickPaths: string[][];
+    outputDir: string;
+  }): string;
+  /**
+   * Analyze intercepted network traffic for fake patterns
+   */
+  analyzeTraffic(
+    requests: InterceptedRequest[],
+    responses: InterceptedResponse[],
+  ): FakeDetection[];
+  /**
+   * Generate evidence description for a detection
+   */
+  private getEvidence;
+  /**
+   * Generate a human-readable Reality Mode report
+   */
+  generateReport(result: RealityModeResult): string;
+  /**
+   * Generate common click paths for testing
+   */
+  generateDefaultClickPaths(): string[][];
+}
+export declare const realityScanner: RealityScanner;
+//# sourceMappingURL=reality-scanner.d.ts.map