vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/ship-manifest.js

@@ -0,0 +1,1153 @@
+/**
+ * Ship Manifest - Deterministic Artifact System
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * THE SHIP GATE ARTIFACT - TRUSTWORTHY, FINAL, DETERMINISTIC
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Creates a cryptographically signed manifest that guarantees:
+ * - Same repo state → Same verdict (deterministic)
+ * - Evidence-backed decisions (traceable)
+ * - CI-friendly outputs (badges, receipts)
+ * 
+ * Used by `vibecheck ship` and `vibecheck seal` commands.
+ * 
+ * @module ship-manifest
+ * @version 1.1.0 - Hardened
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { execSync } = require("child_process");
+const os = require("os");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ERROR TYPES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+class ManifestError extends Error {
+  constructor(message, code, details = {}) {
+    super(message);
+    this.name = "ManifestError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+class ValidationError extends ManifestError {
+  constructor(message, field, value) {
+    super(message, "VALIDATION_ERROR", { field, value });
+    this.name = "ValidationError";
+  }
+}
+
+class FileSystemError extends ManifestError {
+  constructor(message, operation, path) {
+    super(message, "FS_ERROR", { operation, path });
+    this.name = "FileSystemError";
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const MANIFEST_VERSION = "1.1.0";
+const MANIFEST_SCHEMA = "vibecheck/ship-manifest/v1";
+
+// Maximum file size to read (prevent DoS on large files)
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+
+// Maximum findings to include in manifest
+const MAX_FINDINGS = 1000;
+
+// Git command timeout
+const GIT_TIMEOUT = 10000; // 10 seconds
+
+const VERDICTS = Object.freeze({
+  SHIP: Object.freeze({ code: 0, badge: "passing", color: "#22c55e", ci: "success" }),
+  WARN: Object.freeze({ code: 1, badge: "warnings", color: "#eab308", ci: "warning" }),
+  BLOCK: Object.freeze({ code: 2, badge: "blocked", color: "#ef4444", ci: "failure" }),
+});
+
+const VALID_VERDICTS = new Set(["SHIP", "WARN", "BLOCK"]);
+
+// Files used for repo fingerprint (critical config)
+const FINGERPRINT_FILES = Object.freeze([
+  "package.json",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+  "prisma/schema.prisma",
+  ".vibecheckrc",
+  ".vibecheck/contracts/routes.json",
+  ".vibecheck/contracts/env.json",
+  ".vibecheck/contracts/auth.json",
+]);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// INPUT VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Validate that a path is safe (no traversal, exists)
+ * @param {string} inputPath - Path to validate
+ * @param {string} context - Context for error messages
+ * @returns {string} Validated absolute path
+ */
+function validatePath(inputPath, context = "path") {
+  if (typeof inputPath !== "string" || !inputPath.trim()) {
+    throw new ValidationError(`${context} must be a non-empty string`, context, inputPath);
+  }
+
+  // Prevent null byte injection
+  if (inputPath.includes("\0")) {
+    throw new ValidationError(`${context} contains invalid characters`, context, "[contains null byte]");
+  }
+
+  const resolved = path.resolve(inputPath);
+
+  // Prevent traversal outside workspace (basic check)
+  const normalized = path.normalize(resolved);
+  if (normalized !== resolved) {
+    // Path contained .. or other traversal
+    // This is OK as long as it resolves to a valid absolute path
+  }
+
+  return resolved;
+}
+
+/**
+ * Validate verdict string
+ * @param {string} verdict - Verdict to validate
+ * @returns {string} Validated verdict
+ */
+function validateVerdict(verdict) {
+  const v = String(verdict || "").toUpperCase();
+  
+  if (!VALID_VERDICTS.has(v)) {
+    throw new ValidationError(
+      `Invalid verdict: ${verdict}. Must be one of: SHIP, WARN, BLOCK`,
+      "verdict",
+      verdict
+    );
+  }
+  
+  return v;
+}
+
+/**
+ * Validate score is in range
+ * @param {number} score - Score to validate
+ * @returns {number} Validated score (clamped to 0-100)
+ */
+function validateScore(score) {
+  const num = Number(score);
+  
+  if (isNaN(num)) {
+    return 0;
+  }
+  
+  return Math.max(0, Math.min(100, Math.round(num)));
+}
+
+/**
+ * Validate and sanitize findings array
+ * @param {Array} findings - Findings to validate
+ * @returns {Array} Sanitized findings
+ */
+function validateFindings(findings) {
+  if (!Array.isArray(findings)) {
+    return [];
+  }
+
+  // Limit number of findings
+  const limited = findings.slice(0, MAX_FINDINGS);
+
+  return limited.map((f, index) => {
+    if (!f || typeof f !== "object") {
+      return null;
+    }
+
+    return {
+      id: sanitizeString(f.id || f.fingerprint || `finding-${index}`),
+      category: sanitizeString(f.category || "Unknown"),
+      severity: sanitizeSeverity(f.severity),
+      title: sanitizeString(f.title || f.message || "Untitled finding", 500),
+      why: sanitizeString(f.why || f.explanation, 1000),
+      confidence: sanitizeConfidence(f.confidence),
+      evidence: sanitizeEvidence(f.evidence),
+      fixHints: sanitizeFixHints(f.fixHints),
+      fingerprint: sanitizeString(f.fingerprint, 64),
+    };
+  }).filter(Boolean);
+}
+
+/**
+ * Sanitize a string (prevent injection, limit length)
+ */
+function sanitizeString(str, maxLength = 200) {
+  if (str === null || str === undefined) {
+    return null;
+  }
+
+  const s = String(str)
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "") // Remove control chars
+    .trim();
+
+  return s.slice(0, maxLength) || null;
+}
+
+/**
+ * Sanitize severity
+ */
+function sanitizeSeverity(severity) {
+  const valid = ["BLOCK", "WARN", "INFO"];
+  const s = String(severity || "").toUpperCase();
+  return valid.includes(s) ? s : "INFO";
+}
+
+/**
+ * Sanitize confidence
+ */
+function sanitizeConfidence(confidence) {
+  const valid = ["high", "medium", "low"];
+  const c = String(confidence || "").toLowerCase();
+  return valid.includes(c) ? c : "medium";
+}
+
+/**
+ * Sanitize evidence array
+ */
+function sanitizeEvidence(evidence) {
+  if (!Array.isArray(evidence)) {
+    return [];
+  }
+
+  return evidence.slice(0, 5).map(e => {
+    if (!e || typeof e !== "object") return null;
+    return {
+      file: sanitizeString(e.file || e.path, 500),
+      lines: sanitizeString(e.lines, 20),
+      snippet: sanitizeString(e.snippet, 200),
+      kind: sanitizeString(e.kind, 20) || "file",
+    };
+  }).filter(Boolean);
+}
+
+/**
+ * Sanitize fix hints
+ */
+function sanitizeFixHints(hints) {
+  if (!Array.isArray(hints)) {
+    return [];
+  }
+  return hints.slice(0, 5).map(h => sanitizeString(h, 500)).filter(Boolean);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// REPO FINGERPRINT - DETERMINISTIC STATE HASH
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a deterministic fingerprint for the current repo state.
+ * Same repo state always produces the same fingerprint.
+ * 
+ * @param {string} repoRoot - Repository root path
+ * @returns {Object} Fingerprint with components
+ * @throws {ValidationError} If repoRoot is invalid
+ */
+function generateRepoFingerprint(repoRoot) {
+  // Validate input
+  const validatedRoot = validatePath(repoRoot, "repoRoot");
+
+  // Verify directory exists
+  if (!fs.existsSync(validatedRoot)) {
+    throw new FileSystemError(
+      `Repository root does not exist: ${validatedRoot}`,
+      "stat",
+      validatedRoot
+    );
+  }
+
+  const stats = safeStatSync(validatedRoot);
+  if (!stats || !stats.isDirectory()) {
+    throw new FileSystemError(
+      `Repository root is not a directory: ${validatedRoot}`,
+      "stat",
+      validatedRoot
+    );
+  }
+
+  const components = {
+    commitHash: getGitCommitHash(validatedRoot),
+    headRef: getGitHeadRef(validatedRoot),
+    treeHash: getGitTreeHash(validatedRoot),
+    configHashes: {},
+    timestamp: null, // Not included in hash for determinism
+    gitAvailable: false,
+  };
+
+  // Check if git is available
+  components.gitAvailable = components.commitHash !== "unknown" || 
+                            fs.existsSync(path.join(validatedRoot, ".git"));
+
+  // Hash critical config files
+  for (const file of FINGERPRINT_FILES) {
+    const filePath = path.join(validatedRoot, file);
+    const content = safeReadFile(filePath, MAX_FILE_SIZE);
+    
+    if (content !== null) {
+      components.configHashes[file] = sha256(content).slice(0, 16);
+    }
+  }
+
+  // Compute combined fingerprint
+  // Use deterministic sorting to ensure same output
+  const sortedHashes = Object.entries(components.configHashes)
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([k, v]) => `${k}:${v}`);
+
+  const fingerprintInput = [
+    components.commitHash || "no-commit",
+    components.treeHash || "no-tree",
+    ...sortedHashes,
+  ].join("|");
+
+  return {
+    ...components,
+    fingerprint: sha256(fingerprintInput).slice(0, 32),
+    isDirty: isGitDirty(validatedRoot),
+  };
+}
+
+/**
+ * Safe stat that returns null on error
+ */
+function safeStatSync(filePath) {
+  try {
+    return fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Safe file read with size limit
+ */
+function safeReadFile(filePath, maxSize = MAX_FILE_SIZE) {
+  try {
+    // Check if file exists and get size
+    const stats = fs.statSync(filePath);
+    
+    if (!stats.isFile()) {
+      return null;
+    }
+
+    // Prevent reading huge files
+    if (stats.size > maxSize) {
+      // For large files, hash first 1MB + size
+      const fd = fs.openSync(filePath, "r");
+      try {
+        const buffer = Buffer.alloc(1024 * 1024);
+        const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);
+        return buffer.slice(0, bytesRead).toString("utf8") + `|size:${stats.size}`;
+      } finally {
+        fs.closeSync(fd);
+      }
+    }
+
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Execute a git command safely with timeout
+ * @param {string} command - Git command (without "git" prefix)
+ * @param {string} cwd - Working directory
+ * @returns {string|null} Command output or null on failure
+ */
+function safeGitExec(command, cwd) {
+  try {
+    return execSync(`git ${command}`, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: GIT_TIMEOUT,
+      maxBuffer: 1024 * 1024, // 1MB max output
+      windowsHide: true,
+    }).trim();
+  } catch (err) {
+    // Log in debug mode
+    if (process.env.DEBUG || process.env.VIBECHECK_DEBUG) {
+      console.error(`Git command failed: git ${command}`, err.message);
+    }
+    return null;
+  }
+}
+
+/**
+ * Get Git commit hash
+ * @param {string} repoRoot - Repository root
+ * @returns {string} Commit hash (12 chars) or "unknown"
+ */
+function getGitCommitHash(repoRoot) {
+  const result = safeGitExec("rev-parse HEAD", repoRoot);
+  
+  if (result && /^[a-f0-9]{40}$/i.test(result)) {
+    return result.slice(0, 12);
+  }
+  
+  return "unknown";
+}
+
+/**
+ * Get Git HEAD ref (branch name or detached HEAD)
+ * @param {string} repoRoot - Repository root
+ * @returns {string} Branch name or "HEAD" or "unknown"
+ */
+function getGitHeadRef(repoRoot) {
+  // Try reading HEAD file directly (faster, no subprocess)
+  const headPath = path.join(repoRoot, ".git", "HEAD");
+  const content = safeReadFile(headPath, 1024);
+  
+  if (content) {
+    const head = content.trim();
+    if (head.startsWith("ref: refs/heads/")) {
+      const branch = head.slice("ref: refs/heads/".length);
+      // Sanitize branch name
+      if (/^[\w\-./]+$/.test(branch)) {
+        return branch;
+      }
+    }
+    // Detached HEAD
+    if (/^[a-f0-9]{40}$/i.test(head)) {
+      return "HEAD";
+    }
+  }
+  
+  // Fallback to git command
+  const branch = safeGitExec("rev-parse --abbrev-ref HEAD", repoRoot);
+  if (branch && branch !== "HEAD" && /^[\w\-./]+$/.test(branch)) {
+    return branch;
+  }
+  
+  return "unknown";
+}
+
+/**
+ * Get Git tree hash (content-addressable hash of working tree)
+ * @param {string} repoRoot - Repository root
+ * @returns {string} Tree hash (12 chars) or "unknown"
+ */
+function getGitTreeHash(repoRoot) {
+  const result = safeGitExec("write-tree", repoRoot);
+  
+  if (result && /^[a-f0-9]{40}$/i.test(result)) {
+    return result.slice(0, 12);
+  }
+  
+  // Fallback: hash of HEAD tree
+  const treeRef = safeGitExec("rev-parse HEAD^{tree}", repoRoot);
+  if (treeRef && /^[a-f0-9]{40}$/i.test(treeRef)) {
+    return treeRef.slice(0, 12);
+  }
+  
+  return "unknown";
+}
+
+/**
+ * Check if Git working tree is dirty
+ * @param {string} repoRoot - Repository root
+ * @returns {boolean} True if dirty, false if clean or unknown
+ */
+function isGitDirty(repoRoot) {
+  const status = safeGitExec("status --porcelain", repoRoot);
+  
+  // null means git failed (not a repo, etc.) - treat as not dirty
+  if (status === null) {
+    return false;
+  }
+  
+  return status.length > 0;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SHIP MANIFEST GENERATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a ship manifest from verdict data.
+ * 
+ * The manifest is the authoritative artifact that proves:
+ * - What was checked
+ * - What verdict was reached
+ * - Why (evidence chain)
+ * - Who/when (audit trail)
+ * 
+ * @param {Object} options - Manifest options
+ * @returns {Object} Ship manifest
+ * @throws {ValidationError} If required options are invalid
+ */
+function generateShipManifest(options = {}) {
+  // Validate and extract options with defaults
+  const {
+    repoRoot = process.cwd(),
+    verdict: rawVerdict = "BLOCK",
+    score: rawScore = 0,
+    findings: rawFindings = [],
+    truthpack = null,
+    realityReport = null,
+    shieldStatus = null,
+    coverage = null,
+    durationMs = 0,
+  } = options || {};
+
+  // Validate inputs
+  const validatedRoot = validatePath(repoRoot, "repoRoot");
+  const verdict = validateVerdict(rawVerdict);
+  const score = validateScore(rawScore);
+  const findings = validateFindings(rawFindings);
+  const duration = Math.max(0, Math.round(Number(durationMs) || 0));
+
+  // Generate repo fingerprint (may throw on invalid path)
+  let repoFP;
+  try {
+    repoFP = generateRepoFingerprint(validatedRoot);
+  } catch (err) {
+    // If fingerprint fails, create a degraded one
+    repoFP = {
+      fingerprint: sha256(validatedRoot + Date.now()).slice(0, 32),
+      commitHash: "unknown",
+      headRef: "unknown",
+      treeHash: "unknown",
+      isDirty: false,
+      gitAvailable: false,
+      configHashes: {},
+    };
+    
+    if (process.env.DEBUG || process.env.VIBECHECK_DEBUG) {
+      console.error("Fingerprint generation failed:", err.message);
+    }
+  }
+
+  const now = new Date().toISOString();
+
+  // Build findings summary with safe counting
+  const findingsSummary = {
+    total: findings.length,
+    blockers: findings.filter(f => f.severity === "BLOCK").length,
+    warnings: findings.filter(f => f.severity === "WARN").length,
+    info: findings.filter(f => f.severity === "INFO").length,
+  };
+
+  // Build evidence map (top 3 blockers with evidence)
+  const whyTree = buildWhyTree(findings);
+
+  // Build coverage metrics with null safety
+  const coverageMetrics = sanitizeCoverage(coverage, truthpack, realityReport);
+
+  // Build manifest with all validated data
+  const manifest = {
+    version: MANIFEST_VERSION,
+    schema: MANIFEST_SCHEMA,
+    
+    // Verdict (the final word)
+    verdict: {
+      status: verdict,
+      exitCode: VERDICTS[verdict]?.code ?? 2,
+      score,
+      ciStatus: VERDICTS[verdict]?.ci ?? "failure",
+      canShip: verdict === "SHIP",
+    },
+    
+    // Repo state (for determinism)
+    repo: {
+      root: validatedRoot,
+      name: sanitizeString(path.basename(validatedRoot), 100) || "unknown",
+      fingerprint: repoFP.fingerprint,
+      commit: repoFP.commitHash,
+      branch: repoFP.headRef,
+      treeHash: repoFP.treeHash,
+      isDirty: Boolean(repoFP.isDirty),
+      gitAvailable: Boolean(repoFP.gitAvailable),
+    },
+    
+    // Evidence (why this verdict)
+    evidence: {
+      summary: findingsSummary,
+      whyTree,
+      coverage: coverageMetrics,
+    },
+    
+    // Source checks performed
+    checks: {
+      audit: {
+        ran: findings.length > 0 || truthpack !== null,
+        findingsCount: findings.length,
+        truthpackHash: sanitizeString(truthpack?.index?.hashes?.truthpackHash, 64),
+      },
+      reality: {
+        ran: realityReport !== null,
+        actionsCount: Math.max(0, Number(realityReport?.actions?.length) || 0),
+        requestsCount: Math.max(0, Number(realityReport?.requests?.length) || 0),
+      },
+      shield: {
+        ran: shieldStatus !== null,
+        mode: sanitizeString(shieldStatus?.mode, 20) || "unknown",
+        enforcing: shieldStatus?.mode === "enforce",
+        locked: Boolean(shieldStatus?.locked),
+      },
+    },
+    
+    // Metadata
+    meta: {
+      generatedAt: now,
+      durationMs: duration,
+      tool: "vibecheck",
+      toolVersion: getVibeCheckVersion(),
+      platform: `${os.platform()}-${os.arch()}`,
+      nodeVersion: process.version,
+    },
+    
+    // Signature (for verification)
+    signature: null, // Will be computed below
+  };
+
+  // Compute manifest signature
+  manifest.signature = computeManifestSignature(manifest);
+
+  // Freeze the manifest to prevent accidental mutation
+  return deepFreeze(manifest);
+}
+
+/**
+ * Sanitize coverage metrics
+ */
+function sanitizeCoverage(coverage, truthpack, realityReport) {
+  if (coverage && typeof coverage === "object") {
+    return {
+      routeCoverage: validateScore(coverage.routeCoverage),
+      envCoverage: validateScore(coverage.envCoverage),
+      authCoverage: coverage.authCoverage === null ? null : validateScore(coverage.authCoverage),
+      runtimeCoverage: coverage.runtimeCoverage === null ? null : Math.max(0, Number(coverage.runtimeCoverage) || 0),
+    };
+  }
+
+  // Compute from truthpack/reality
+  const serverRoutes = Array.isArray(truthpack?.routes?.server) ? truthpack.routes.server.length : 0;
+  const envVars = Array.isArray(truthpack?.env?.vars) ? truthpack.env.vars.length : 0;
+  const envDeclared = Array.isArray(truthpack?.env?.declared) ? truthpack.env.declared.length : 0;
+
+  return {
+    routeCoverage: serverRoutes > 0 ? 100 : 0,
+    envCoverage: envVars > 0 ? Math.round((envDeclared / envVars) * 100) : 100,
+    authCoverage: null,
+    runtimeCoverage: realityReport ? Math.max(0, Number(realityReport.requests?.length) || 0) : null,
+  };
+}
+
+/**
+ * Deep freeze an object to prevent mutation
+ */
+function deepFreeze(obj) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+
+  Object.freeze(obj);
+
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+      deepFreeze(value);
+    }
+  }
+
+  return obj;
+}
+
+/**
+ * Build the "why tree" - top blockers with evidence chains.
+ * This is the key artifact for understanding WHY a verdict was reached.
+ */
+function buildWhyTree(findings) {
+  const blockers = findings
+    .filter(f => f.severity === "BLOCK")
+    .sort((a, b) => {
+      // Sort by confidence (high first), then by category importance
+      const confA = a.confidence === "high" ? 3 : a.confidence === "medium" ? 2 : 1;
+      const confB = b.confidence === "high" ? 3 : b.confidence === "medium" ? 2 : 1;
+      return confB - confA;
+    })
+    .slice(0, 3);
+
+  if (blockers.length === 0) {
+    // No blockers - verdict should be SHIP or WARN
+    const warnings = findings
+      .filter(f => f.severity === "WARN")
+      .slice(0, 3);
+
+    if (warnings.length === 0) {
+      return {
+        summary: "All checks passed",
+        topIssues: [],
+        fixMissions: [],
+      };
+    }
+
+    return {
+      summary: `${warnings.length} warning(s) to review`,
+      topIssues: warnings.map(w => ({
+        id: w.id || w.fingerprint || sha256(w.title || "").slice(0, 8),
+        category: w.category,
+        title: w.title || w.message,
+        evidence: formatEvidence(w),
+        fixHint: w.fixHints?.[0] || null,
+      })),
+      fixMissions: [],
+    };
+  }
+
+  return {
+    summary: `${blockers.length} blocker(s) must be fixed`,
+    topIssues: blockers.map(b => ({
+      id: b.id || b.fingerprint || sha256(b.title || "").slice(0, 8),
+      category: b.category,
+      title: b.title || b.message,
+      why: b.why || null,
+      evidence: formatEvidence(b),
+      fixHint: b.fixHints?.[0] || null,
+    })),
+    fixMissions: blockers.map(b => ({
+      target: b.evidence?.[0]?.file || "unknown",
+      action: b.fixHints?.[0] || `Fix ${b.category} issue`,
+      priority: "critical",
+    })),
+  };
+}
+
+/**
+ * Format evidence for display
+ */
+function formatEvidence(finding) {
+  if (!finding.evidence?.length) {
+    return null;
+  }
+
+  const ev = finding.evidence[0];
+  return {
+    file: ev.file || ev.path || null,
+    lines: ev.lines || (ev.line ? `${ev.line}` : null),
+    snippet: ev.snippet?.slice(0, 100) || null,
+    kind: ev.kind || "file",
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MANIFEST SIGNATURE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Compute a signature for the manifest.
+ * This allows verification that the manifest hasn't been tampered with.
+ */
+function computeManifestSignature(manifest) {
+  // Create a canonical representation (excluding signature field)
+  const signableContent = {
+    version: manifest.version,
+    verdict: manifest.verdict,
+    repo: manifest.repo,
+    evidence: manifest.evidence,
+    checks: manifest.checks,
+    meta: {
+      generatedAt: manifest.meta.generatedAt,
+      tool: manifest.meta.tool,
+      toolVersion: manifest.meta.toolVersion,
+    },
+  };
+
+  const canonical = JSON.stringify(signableContent, Object.keys(signableContent).sort());
+  const hash = sha256(canonical);
+
+  return {
+    algorithm: "sha256",
+    digest: hash.slice(0, 32),
+    // In a full implementation, this would include cryptographic signing
+    // For now, we use a deterministic hash that can be verified
+    verifiable: true,
+  };
+}
+
+/**
+ * Verify a manifest signature
+ */
+function verifyManifestSignature(manifest) {
+  if (!manifest.signature) {
+    return { valid: false, reason: "No signature present" };
+  }
+
+  const recomputed = computeManifestSignature({
+    ...manifest,
+    signature: null, // Exclude signature for recomputation
+  });
+
+  const matches = recomputed.digest === manifest.signature.digest;
+
+  return {
+    valid: matches,
+    reason: matches ? "Signature valid" : "Signature mismatch - manifest may have been modified",
+    recomputedDigest: recomputed.digest,
+    storedDigest: manifest.signature.digest,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CI OUTPUT FORMATS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a CI-friendly receipt (single line, parseable)
+ */
+function generateCIReceipt(manifest) {
+  const parts = [
+    `VERDICT=${manifest.verdict.status}`,
+    `EXIT_CODE=${manifest.verdict.exitCode}`,
+    `SCORE=${manifest.verdict.score}`,
+    `BLOCKERS=${manifest.evidence.summary.blockers}`,
+    `WARNINGS=${manifest.evidence.summary.warnings}`,
+    `COMMIT=${manifest.repo.commit}`,
+    `FINGERPRINT=${manifest.repo.fingerprint}`,
+    `DIRTY=${manifest.repo.isDirty}`,
+    `SIGNATURE=${manifest.signature.digest}`,
+  ];
+
+  return parts.join(" ");
+}
+
+/**
+ * Generate environment variables for CI
+ */
+function generateCIEnvVars(manifest) {
+  return {
+    VIBECHECK_VERDICT: manifest.verdict.status,
+    VIBECHECK_EXIT_CODE: String(manifest.verdict.exitCode),
+    VIBECHECK_SCORE: String(manifest.verdict.score),
+    VIBECHECK_CAN_SHIP: String(manifest.verdict.canShip),
+    VIBECHECK_BLOCKERS: String(manifest.evidence.summary.blockers),
+    VIBECHECK_WARNINGS: String(manifest.evidence.summary.warnings),
+    VIBECHECK_COMMIT: manifest.repo.commit,
+    VIBECHECK_BRANCH: manifest.repo.branch,
+    VIBECHECK_FINGERPRINT: manifest.repo.fingerprint,
+    VIBECHECK_SIGNATURE: manifest.signature.digest,
+    VIBECHECK_DIRTY: String(manifest.repo.isDirty),
+  };
+}
+
+/**
+ * Generate GitHub Actions output format
+ */
+function generateGitHubActionsOutput(manifest) {
+  const outputs = generateCIEnvVars(manifest);
+  const lines = [];
+
+  for (const [key, value] of Object.entries(outputs)) {
+    const name = key.replace("VIBECHECK_", "").toLowerCase();
+    lines.push(`${name}=${value}`);
+  }
+
+  return lines.join("\n");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// BADGE GENERATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate badge info for embedding in README
+ */
+function generateBadgeInfo(manifest) {
+  const verdictConfig = VERDICTS[manifest.verdict.status] || VERDICTS.BLOCK;
+
+  return {
+    label: "vibecheck",
+    message: manifest.verdict.status,
+    color: verdictConfig.color.replace("#", ""),
+    score: manifest.verdict.score,
+    url: {
+      shields: `https://img.shields.io/badge/vibecheck-${manifest.verdict.status}-${verdictConfig.color.replace("#", "")}?style=flat-square`,
+      badgen: `https://badgen.net/badge/vibecheck/${manifest.verdict.status}/${verdictConfig.color.replace("#", "")}`,
+    },
+    markdown: `[![Vibecheck](https://img.shields.io/badge/vibecheck-${manifest.verdict.status}-${verdictConfig.color.replace("#", "")}?style=flat-square)](https://vibecheckai.dev)`,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PERSISTENCE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Atomically write a file (write to temp, then rename)
+ * @param {string} targetPath - Final destination path
+ * @param {string} content - Content to write
+ */
+function atomicWriteFile(targetPath, content) {
+  const dir = path.dirname(targetPath);
+  const tempPath = path.join(dir, `.${path.basename(targetPath)}.tmp.${process.pid}`);
+
+  try {
+    // Ensure directory exists
+    fs.mkdirSync(dir, { recursive: true });
+
+    // Write to temp file
+    fs.writeFileSync(tempPath, content, { encoding: "utf8", mode: 0o644 });
+
+    // Atomically rename (overwrites existing)
+    fs.renameSync(tempPath, targetPath);
+  } catch (err) {
+    // Clean up temp file on error
+    try {
+      if (fs.existsSync(tempPath)) {
+        fs.unlinkSync(tempPath);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw new FileSystemError(
+      `Failed to write file: ${err.message}`,
+      "write",
+      targetPath
+    );
+  }
+}
+
+/**
+ * Write manifest to disk with atomic writes.
+ * 
+ * @param {string} repoRoot - Repository root path
+ * @param {Object} manifest - Ship manifest to write
+ * @returns {Object} Paths to written files
+ * @throws {FileSystemError} If write fails
+ */
+function writeShipManifest(repoRoot, manifest) {
+  // Validate inputs
+  const validatedRoot = validatePath(repoRoot, "repoRoot");
+  
+  if (!manifest || typeof manifest !== "object") {
+    throw new ValidationError("manifest must be an object", "manifest", manifest);
+  }
+
+  const dir = path.join(validatedRoot, ".vibecheck", "ship");
+  
+  // Prepare all content first (fail early if serialization fails)
+  let manifestJson, receipt, ghOutput;
+  
+  try {
+    manifestJson = JSON.stringify(manifest, null, 2);
+  } catch (err) {
+    throw new ManifestError(
+      `Failed to serialize manifest: ${err.message}`,
+      "SERIALIZATION_ERROR"
+    );
+  }
+
+  receipt = generateCIReceipt(manifest);
+  ghOutput = generateGitHubActionsOutput(manifest);
+
+  // Ensure directory exists
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
+  } catch (err) {
+    throw new FileSystemError(
+      `Failed to create directory: ${err.message}`,
+      "mkdir",
+      dir
+    );
+  }
+
+  // Write all files atomically
+  const paths = {
+    manifest: path.join(dir, "manifest.json"),
+    archive: null,
+    receipt: path.join(dir, "receipt.txt"),
+    githubOutput: path.join(dir, "github-output.txt"),
+  };
+
+  // Write main manifest
+  atomicWriteFile(paths.manifest, manifestJson);
+
+  // Write timestamped archive (best effort, don't fail on this)
+  try {
+    const timestamp = (manifest.meta?.generatedAt || new Date().toISOString())
+      .replace(/[:.]/g, "-")
+      .slice(0, 19);
+    
+    // Validate timestamp format
+    if (/^[\d-T]+$/.test(timestamp)) {
+      paths.archive = path.join(dir, `manifest-${timestamp}.json`);
+      atomicWriteFile(paths.archive, manifestJson);
+      
+      // Clean up old archives (keep last 10)
+      cleanupOldArchives(dir, 10);
+    }
+  } catch {
+    // Archive write failure is non-fatal
+    paths.archive = null;
+  }
+
+  // Write CI receipt
+  atomicWriteFile(paths.receipt, receipt);
+
+  // Write GitHub Actions output
+  atomicWriteFile(paths.githubOutput, ghOutput);
+
+  return paths;
+}
+
+/**
+ * Clean up old archive files, keeping the most recent N
+ */
+function cleanupOldArchives(dir, keepCount = 10) {
+  try {
+    const files = fs.readdirSync(dir)
+      .filter(f => f.startsWith("manifest-") && f.endsWith(".json"))
+      .map(f => ({
+        name: f,
+        path: path.join(dir, f),
+        mtime: fs.statSync(path.join(dir, f)).mtimeMs,
+      }))
+      .sort((a, b) => b.mtime - a.mtime);
+
+    // Delete files beyond keepCount
+    for (const file of files.slice(keepCount)) {
+      try {
+        fs.unlinkSync(file.path);
+      } catch {
+        // Ignore deletion errors
+      }
+    }
+  } catch {
+    // Ignore cleanup errors
+  }
+}
+
+/**
+ * Load latest manifest from disk with validation.
+ * 
+ * @param {string} repoRoot - Repository root path
+ * @returns {Object|null} Manifest or null if not found/invalid
+ */
+function loadShipManifest(repoRoot) {
+  let validatedRoot;
+  try {
+    validatedRoot = validatePath(repoRoot, "repoRoot");
+  } catch {
+    return null;
+  }
+
+  const manifestPath = path.join(validatedRoot, ".vibecheck", "ship", "manifest.json");
+
+  const content = safeReadFile(manifestPath, MAX_FILE_SIZE);
+  if (!content) {
+    return null;
+  }
+
+  try {
+    const manifest = JSON.parse(content);
+
+    // Basic validation
+    if (!manifest || typeof manifest !== "object") {
+      return null;
+    }
+
+    // Check schema version
+    if (manifest.schema && !manifest.schema.startsWith("vibecheck/ship-manifest/")) {
+      return null;
+    }
+
+    // Check required fields
+    if (!manifest.verdict?.status || !manifest.repo?.fingerprint) {
+      return null;
+    }
+
+    return manifest;
+  } catch {
+    // Invalid JSON
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function sha256(input) {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}
+
+function getVibeCheckVersion() {
+  try {
+    const pkgPath = path.join(__dirname, "../../../package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    return pkg.version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Core
+  generateShipManifest,
+  generateRepoFingerprint,
+  buildWhyTree,
+  
+  // Signature
+  computeManifestSignature,
+  verifyManifestSignature,
+  
+  // CI outputs
+  generateCIReceipt,
+  generateCIEnvVars,
+  generateGitHubActionsOutput,
+  
+  // Badge
+  generateBadgeInfo,
+  
+  // Persistence
+  writeShipManifest,
+  loadShipManifest,
+  
+  // Validation (for external use)
+  validatePath,
+  validateVerdict,
+  validateScore,
+  validateFindings,
+  
+  // Utility
+  safeReadFile,
+  safeGitExec,
+  atomicWriteFile,
+  
+  // Error classes
+  ManifestError,
+  ValidationError,
+  FileSystemError,
+  
+  // Constants
+  MANIFEST_VERSION,
+  MANIFEST_SCHEMA,
+  VERDICTS,
+  FINGERPRINT_FILES,
+  MAX_FILE_SIZE,
+  MAX_FINDINGS,
+  GIT_TIMEOUT,
+};