vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/artifact-envelope.js

@@ -0,0 +1,540 @@
+/**
+ * Unified Artifact Envelope
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * Single envelope schema for ALL VibeCheck artifacts
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Used by: audit, ship, reality, shield, fix, packs
+ * 
+ * @module artifact-envelope
+ * @version 1.0.0
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+const path = require("path");
+const fs = require("fs");
+const { execSync } = require("child_process");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const ENVELOPE_VERSION = "1.0.0";
+const SCHEMA_URL = "https://vibecheck.dev/schemas/artifact-envelope.v1.json";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ARTIFACT TYPES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const ARTIFACT_TYPES = {
+  AUDIT: "audit",
+  SHIP: "ship",
+  REALITY: "reality",
+  SHIELD: "shield",
+  FIX: "fix",
+  PACK: "pack",
+  CHECKPOINT: "checkpoint",
+  INTENT: "intent",
+  VERDICT: "verdict",
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// REPO INFO
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get repository information for artifact envelope
+ * 
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Repository info
+ */
+function getRepoInfo(projectRoot) {
+  const info = {
+    root: projectRoot,
+    name: path.basename(projectRoot),
+    commit: null,
+    branch: null,
+    treeHash: null,
+    isDirty: true,
+    fingerprint: null,
+  };
+
+  try {
+    // Check if it's a git repo
+    execSync("git rev-parse --git-dir", { 
+      cwd: projectRoot, 
+      stdio: ["pipe", "pipe", "pipe"] 
+    });
+
+    // Get commit hash
+    info.commit = execSync("git rev-parse HEAD", { 
+      cwd: projectRoot, 
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    // Get branch name
+    try {
+      info.branch = execSync("git rev-parse --abbrev-ref HEAD", { 
+        cwd: projectRoot, 
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch {
+      info.branch = "detached";
+    }
+
+    // Get tree hash
+    info.treeHash = execSync("git rev-parse HEAD^{tree}", { 
+      cwd: projectRoot, 
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    // Check if dirty
+    const status = execSync("git status --porcelain", { 
+      cwd: projectRoot, 
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    info.isDirty = status.length > 0;
+
+    // Compute fingerprint
+    info.fingerprint = computeRepoFingerprint(projectRoot, info);
+
+  } catch {
+    // Not a git repo or git not available
+    info.fingerprint = computeNonGitFingerprint(projectRoot);
+  }
+
+  return info;
+}
+
+/**
+ * Compute deterministic repo fingerprint
+ * 
+ * Same repo state → Same fingerprint. Always.
+ */
+function computeRepoFingerprint(projectRoot, repoInfo) {
+  // Config files that affect fingerprint
+  const configFiles = [
+    ".vibecheckrc",
+    ".vibecheckrc.json",
+    "package.json",
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "yarn.lock",
+  ];
+
+  const configHashes = configFiles.map(f => {
+    const filePath = path.join(projectRoot, f);
+    if (fs.existsSync(filePath)) {
+      return crypto.createHash("sha256")
+        .update(fs.readFileSync(filePath))
+        .digest("hex")
+        .slice(0, 8);
+    }
+    return "missing";
+  }).join("|");
+
+  const input = `${repoInfo.commit}|${repoInfo.treeHash}|${configHashes}`;
+  
+  return `sha256:${crypto.createHash("sha256").update(input).digest("hex")}`;
+}
+
+/**
+ * Compute fingerprint for non-git projects
+ */
+function computeNonGitFingerprint(projectRoot) {
+  const input = `${projectRoot}|${Date.now()}`;
+  return `nongit:${crypto.createHash("sha256").update(input).digest("hex").slice(0, 32)}`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ARTIFACT CREATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create a new artifact envelope
+ * 
+ * @param {string} type - Artifact type (audit, ship, reality, etc.)
+ * @param {Object} payload - Command-specific payload
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} options - Additional options
+ * @returns {Object} Complete artifact envelope
+ */
+function createArtifactEnvelope(type, payload, projectRoot, options = {}) {
+  const timestamp = new Date().toISOString();
+  const randomId = crypto.randomBytes(4).toString("hex");
+  
+  const envelope = {
+    $schema: SCHEMA_URL,
+    version: ENVELOPE_VERSION,
+    
+    metadata: {
+      id: `${type}-${Date.now()}-${randomId}`,
+      type,
+      command: options.command || `vibecheck ${type}`,
+      generatedAt: timestamp,
+      durationMs: options.durationMs || 0,
+      tool: {
+        name: "vibecheck",
+        version: getToolVersion(),
+      },
+    },
+    
+    repo: getRepoInfo(projectRoot),
+    
+    payload,
+    
+    evidence: {
+      files: options.files || [],
+      proofs: options.proofs || [],
+    },
+    
+    signature: null, // Will be computed
+  };
+  
+  // Compute signature
+  envelope.signature = computeSignature(envelope);
+  
+  return envelope;
+}
+
+/**
+ * Get tool version from package.json
+ */
+function getToolVersion() {
+  try {
+    const pkgPath = path.join(__dirname, "..", "..", "..", "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SIGNATURE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Compute artifact signature
+ * 
+ * @param {Object} envelope - Artifact envelope (without signature)
+ * @returns {Object} Signature object
+ */
+function computeSignature(envelope) {
+  const fieldsToSign = ["metadata", "repo", "payload", "evidence"];
+  
+  // Create canonical JSON (no whitespace, deterministic key order)
+  const dataToSign = fieldsToSign.reduce((acc, field) => {
+    acc[field] = envelope[field];
+    return acc;
+  }, {});
+  
+  const canonical = JSON.stringify(dataToSign, Object.keys(dataToSign).sort(), 0);
+  
+  return {
+    algorithm: "sha256",
+    digest: crypto.createHash("sha256").update(canonical).digest("hex"),
+    signedFields: fieldsToSign,
+    verifiable: true,
+  };
+}
+
+/**
+ * Verify artifact signature
+ * 
+ * @param {Object} envelope - Artifact envelope with signature
+ * @returns {Object} Verification result
+ */
+function verifySignature(envelope) {
+  if (!envelope.signature) {
+    return { valid: false, reason: "No signature present" };
+  }
+  
+  // Recompute expected signature
+  const envelopeWithoutSig = { ...envelope, signature: null };
+  const expected = computeSignature(envelopeWithoutSig);
+  
+  if (envelope.signature.digest !== expected.digest) {
+    return { 
+      valid: false, 
+      reason: "Digest mismatch",
+      expected: expected.digest,
+      actual: envelope.signature.digest,
+    };
+  }
+  
+  return { valid: true };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ARTIFACT NAMING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate deterministic artifact filename
+ * 
+ * Pattern: {type}-{YYYYMMDD}-{HHMMSS}-{hash8}.json
+ * 
+ * @param {string} type - Artifact type
+ * @param {string} extension - File extension (default: json)
+ * @returns {string} Filename
+ */
+function generateArtifactFilename(type, extension = "json") {
+  const now = new Date();
+  const datePart = now.toISOString().slice(0, 10).replace(/-/g, "");
+  const timePart = now.toISOString().slice(11, 19).replace(/:/g, "");
+  const hash = crypto.randomBytes(4).toString("hex");
+  
+  return `${type}-${datePart}-${timePart}-${hash}.${extension}`;
+}
+
+/**
+ * Generate artifact directory path
+ * 
+ * @param {string} projectRoot - Project root
+ * @param {string} type - Artifact type
+ * @returns {string} Directory path
+ */
+function getArtifactDir(projectRoot, type) {
+  const typeToDir = {
+    [ARTIFACT_TYPES.AUDIT]: "audit",
+    [ARTIFACT_TYPES.SHIP]: "ship",
+    [ARTIFACT_TYPES.REALITY]: "reality",
+    [ARTIFACT_TYPES.SHIELD]: "shield",
+    [ARTIFACT_TYPES.FIX]: "fix",
+    [ARTIFACT_TYPES.PACK]: "packs",
+    [ARTIFACT_TYPES.CHECKPOINT]: "checkpoints",
+    [ARTIFACT_TYPES.INTENT]: "shield/intents",
+    [ARTIFACT_TYPES.VERDICT]: "shield/verdicts",
+  };
+  
+  const subdir = typeToDir[type] || type;
+  return path.join(projectRoot, ".vibecheck", subdir);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ARTIFACT I/O
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Save artifact to disk
+ * 
+ * @param {Object} envelope - Artifact envelope
+ * @param {string} projectRoot - Project root
+ * @param {Object} options - Save options
+ * @returns {Object} Save result with path
+ */
+function saveArtifact(envelope, projectRoot, options = {}) {
+  const dir = options.dir || getArtifactDir(projectRoot, envelope.metadata.type);
+  const filename = options.filename || generateArtifactFilename(envelope.metadata.type);
+  const filePath = path.join(dir, filename);
+  
+  // Ensure directory exists
+  fs.mkdirSync(dir, { recursive: true });
+  
+  // Write artifact
+  fs.writeFileSync(filePath, JSON.stringify(envelope, null, 2));
+  
+  // Also write "latest" symlink/copy
+  const latestPath = path.join(dir, `last_${envelope.metadata.type}.json`);
+  fs.writeFileSync(latestPath, JSON.stringify(envelope, null, 2));
+  
+  return {
+    success: true,
+    path: filePath,
+    latestPath,
+    id: envelope.metadata.id,
+  };
+}
+
+/**
+ * Load artifact from disk
+ * 
+ * @param {string} filePath - Full path to artifact
+ * @param {Object} options - Load options
+ * @returns {Object} Artifact envelope or null
+ */
+function loadArtifact(filePath, options = {}) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const envelope = JSON.parse(content);
+    
+    // Optionally verify signature
+    if (options.verify) {
+      const verification = verifySignature(envelope);
+      if (!verification.valid) {
+        return { 
+          envelope: null, 
+          error: `Invalid signature: ${verification.reason}`,
+        };
+      }
+    }
+    
+    return { envelope, error: null };
+  } catch (e) {
+    return { envelope: null, error: e.message };
+  }
+}
+
+/**
+ * Load latest artifact of a type
+ * 
+ * @param {string} projectRoot - Project root
+ * @param {string} type - Artifact type
+ * @param {Object} options - Load options
+ * @returns {Object} Artifact envelope or null
+ */
+function loadLatestArtifact(projectRoot, type, options = {}) {
+  const dir = getArtifactDir(projectRoot, type);
+  const latestPath = path.join(dir, `last_${type}.json`);
+  
+  if (!fs.existsSync(latestPath)) {
+    return { envelope: null, error: "No artifact found" };
+  }
+  
+  return loadArtifact(latestPath, options);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EVIDENCE HELPERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create file evidence entry
+ * 
+ * @param {string} filePath - Relative file path
+ * @param {string} lines - Line range (e.g., "42-45")
+ * @param {string} projectRoot - Project root for hashing
+ * @returns {Object} File evidence entry
+ */
+function createFileEvidence(filePath, lines, projectRoot) {
+  const fullPath = path.join(projectRoot, filePath);
+  let snippetHash = null;
+  
+  if (fs.existsSync(fullPath) && lines) {
+    try {
+      const content = fs.readFileSync(fullPath, "utf-8");
+      const [start, end] = lines.split("-").map(n => parseInt(n, 10));
+      const snippet = content.split("\n").slice(start - 1, end).join("\n");
+      snippetHash = `sha256:${crypto.createHash("sha256").update(snippet).digest("hex").slice(0, 16)}`;
+    } catch {
+      // Ignore errors
+    }
+  }
+  
+  return {
+    path: filePath,
+    lines,
+    snippetHash,
+  };
+}
+
+/**
+ * Create proof entry
+ * 
+ * @param {string} type - Proof type (file_citation, runtime, assertion)
+ * @param {boolean} verified - Whether proof verified
+ * @param {Object} details - Additional details
+ * @returns {Object} Proof entry
+ */
+function createProof(type, verified, details = {}) {
+  return {
+    id: `prf-${type.slice(0, 5)}-${crypto.randomBytes(4).toString("hex")}`,
+    type,
+    status: verified ? "verified" : "failed",
+    verifiedAt: new Date().toISOString(),
+    ...details,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CROSS-REFERENCES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create cross-reference to another artifact
+ * 
+ * @param {string} type - Referenced artifact type
+ * @param {string} projectRoot - Project root
+ * @returns {Object} Cross-reference object
+ */
+function createCrossRef(type, projectRoot) {
+  const dir = getArtifactDir(projectRoot, type);
+  const latestPath = path.join(dir, `last_${type}.json`);
+  
+  // Use relative path
+  const relativePath = path.relative(
+    path.join(projectRoot, ".vibecheck"),
+    latestPath
+  );
+  
+  return {
+    $ref: `./${relativePath}`,
+    type,
+    exists: fs.existsSync(latestPath),
+  };
+}
+
+/**
+ * Build receipts object with cross-references
+ * 
+ * @param {string} projectRoot - Project root
+ * @param {string[]} types - Types to include
+ * @returns {Object} Receipts object
+ */
+function buildReceiptsObject(projectRoot, types = ["audit", "ship", "reality", "shield"]) {
+  const receipts = {};
+  
+  for (const type of types) {
+    const ref = createCrossRef(type, projectRoot);
+    if (ref.exists) {
+      receipts[type] = ref;
+    }
+  }
+  
+  return receipts;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Constants
+  ENVELOPE_VERSION,
+  SCHEMA_URL,
+  ARTIFACT_TYPES,
+  
+  // Core functions
+  createArtifactEnvelope,
+  computeSignature,
+  verifySignature,
+  
+  // Repo info
+  getRepoInfo,
+  computeRepoFingerprint,
+  
+  // Naming
+  generateArtifactFilename,
+  getArtifactDir,
+  
+  // I/O
+  saveArtifact,
+  loadArtifact,
+  loadLatestArtifact,
+  
+  // Evidence
+  createFileEvidence,
+  createProof,
+  
+  // Cross-references
+  createCrossRef,
+  buildReceiptsObject,
+};