@vizzly-testing/cli 0.22.2 → 0.23.1

package/dist/utils/ci-env.js

@@ -4,6 +4,47 @@
  * Generic functions to extract git and PR information from any CI provider
  */
 
+import { readFileSync } from 'node:fs';
+
+// Cache for GitHub Actions event payload to avoid re-reading the file
+let _githubEventCache = null;
+
+/**
+ * Read and parse the GitHub Actions event payload from GITHUB_EVENT_PATH.
+ *
+ * GitHub Actions sets GITHUB_EVENT_PATH to a file containing the full webhook
+ * payload that triggered the workflow. This is essential for pull_request and
+ * pull_request_target events because GITHUB_SHA points to a merge commit,
+ * not the actual head commit.
+ *
+ * @returns {Object} Parsed event payload or empty object on failure
+ */
+export function getGitHubEvent() {
+  if (_githubEventCache !== null) {
+    return _githubEventCache;
+  }
+  let eventPath = process.env.GITHUB_EVENT_PATH;
+  if (!eventPath) {
+    _githubEventCache = {};
+    return _githubEventCache;
+  }
+  try {
+    let content = readFileSync(eventPath, 'utf8');
+    _githubEventCache = JSON.parse(content);
+  } catch {
+    // File doesn't exist or invalid JSON - fail silently with empty object
+    _githubEventCache = {};
+  }
+  return _githubEventCache;
+}
+
+/**
+ * Reset the GitHub event cache. Useful for testing.
+ */
+export function resetGitHubEventCache() {
+  _githubEventCache = null;
+}
+
 /**
  * Get the branch name from CI environment variables
  * @returns {string|null} Branch name or null if not available
@@ -45,15 +86,41 @@ export function getBranch() {
 }
 
 /**
- * Get the commit SHA from CI environment variables
+ * Get the commit SHA from CI environment variables.
+ *
+ * IMPORTANT: For GitHub Actions pull_request events, GITHUB_SHA points to a
+ * temporary merge commit, NOT the actual head commit of the PR. This function
+ * reads the event payload from GITHUB_EVENT_PATH to extract the correct SHA.
+ *
+ * See: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
+ * "GITHUB_SHA for this event is the last merge commit of the pull request merge branch.
+ * If you want to get the commit ID for the last commit to the head branch of the
+ * pull request, use github.event.pull_request.head.sha instead."
+ *
  * @returns {string|null} Commit SHA or null if not available
  */
 export function getCommit() {
-  return process.env.VIZZLY_COMMIT_SHA ||
-  // Vizzly override
-  process.env.GITHUB_SHA ||
-  // GitHub Actions
-  process.env.CI_COMMIT_SHA ||
+  // Vizzly override always takes priority
+  if (process.env.VIZZLY_COMMIT_SHA) {
+    return process.env.VIZZLY_COMMIT_SHA;
+  }
+
+  // GitHub Actions: extract the correct SHA based on event type
+  if (process.env.GITHUB_ACTIONS) {
+    let event = getGitHubEvent();
+
+    // For pull_request events, use the actual head commit SHA (not the merge commit)
+    // The event payload contains pull_request.head.sha which is what we want
+    if (event.pull_request?.head?.sha) {
+      return event.pull_request.head.sha;
+    }
+
+    // For push events or if event parsing failed, GITHUB_SHA is correct
+    return process.env.GITHUB_SHA || null;
+  }
+
+  // Other CI providers
+  return process.env.CI_COMMIT_SHA ||
   // GitLab CI
   process.env.CIRCLE_SHA1 ||
   // CircleCI
@@ -170,15 +237,30 @@ export function getPullRequestNumber() {
 }
 
 /**
- * Get the PR head SHA from CI environment variables
+ * Get the PR head SHA from CI environment variables.
+ *
+ * For GitHub Actions, this reads from the event payload to get the actual
+ * head commit SHA, not the merge commit that GITHUB_SHA points to.
+ *
  * @returns {string|null} PR head SHA or null if not available
  */
 export function getPullRequestHeadSha() {
-  return process.env.VIZZLY_PR_HEAD_SHA ||
-  // Vizzly override
-  process.env.GITHUB_SHA ||
-  // GitHub Actions
-  process.env.CI_COMMIT_SHA ||
+  // Vizzly override always takes priority
+  if (process.env.VIZZLY_PR_HEAD_SHA) {
+    return process.env.VIZZLY_PR_HEAD_SHA;
+  }
+
+  // GitHub Actions: extract from event payload for PRs
+  if (process.env.GITHUB_ACTIONS) {
+    let event = getGitHubEvent();
+    if (event.pull_request?.head?.sha) {
+      return event.pull_request.head.sha;
+    }
+    return process.env.GITHUB_SHA || null;
+  }
+
+  // Other CI providers
+  return process.env.CI_COMMIT_SHA ||
   // GitLab CI
   process.env.CIRCLE_SHA1 ||
   // CircleCI
@@ -200,13 +282,29 @@ export function getPullRequestHeadSha() {
 }
 
 /**
- * Get the PR base SHA from CI environment variables
+ * Get the PR base SHA from CI environment variables.
+ *
+ * For GitHub Actions, this reads from the event payload to get the base
+ * branch SHA that the PR is targeting.
+ *
  * @returns {string|null} PR base SHA or null if not available
  */
 export function getPullRequestBaseSha() {
-  return process.env.VIZZLY_PR_BASE_SHA ||
-  // Vizzly override
-  process.env.CI_MERGE_REQUEST_TARGET_BRANCH_SHA ||
+  // Vizzly override always takes priority
+  if (process.env.VIZZLY_PR_BASE_SHA) {
+    return process.env.VIZZLY_PR_BASE_SHA;
+  }
+
+  // GitHub Actions: extract from event payload
+  if (process.env.GITHUB_ACTIONS) {
+    let event = getGitHubEvent();
+    if (event.pull_request?.base?.sha) {
+      return event.pull_request.base.sha;
+    }
+  }
+
+  // Other CI providers
+  return process.env.CI_MERGE_REQUEST_TARGET_BRANCH_SHA ||
   // GitLab CI
   null // Most CIs don't provide this
   ;

package/dist/utils/session.js

@@ -0,0 +1,185 @@
+/**
+ * Session management for build context
+ *
+ * Tracks the current build ID so subsequent commands (like `vizzly preview`)
+ * can automatically attach to the right build without passing IDs around.
+ *
+ * Two mechanisms:
+ * 1. Session file (.vizzly/session.json) - for local dev and same CI job
+ * 2. GitHub Actions env ($GITHUB_ENV) - for cross-step persistence in GHA
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+let SESSION_DIR = '.vizzly';
+let SESSION_FILE = 'session.json';
+let SESSION_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
+
+/**
+ * Get the session file path
+ * @param {string} [cwd] - Working directory (defaults to process.cwd())
+ * @returns {string} Path to session file
+ */
+export function getSessionPath(cwd = process.cwd()) {
+  return join(cwd, SESSION_DIR, SESSION_FILE);
+}
+
+/**
+ * Write build context to session file and GitHub Actions env
+ *
+ * @param {Object} context - Build context
+ * @param {string} context.buildId - The build ID
+ * @param {string} [context.branch] - Git branch
+ * @param {string} [context.commit] - Git commit SHA
+ * @param {string} [context.parallelId] - Parallel build ID
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Working directory
+ * @param {Object} [options.env] - Environment variables (defaults to process.env)
+ */
+export function writeSession(context, options = {}) {
+  let {
+    cwd = process.cwd(),
+    env = process.env
+  } = options;
+  let session = {
+    buildId: context.buildId,
+    branch: context.branch || null,
+    commit: context.commit || null,
+    parallelId: context.parallelId || null,
+    createdAt: new Date().toISOString()
+  };
+
+  // Write session file
+  let sessionPath = getSessionPath(cwd);
+  let sessionDir = dirname(sessionPath);
+  if (!existsSync(sessionDir)) {
+    mkdirSync(sessionDir, {
+      recursive: true
+    });
+  }
+  writeFileSync(sessionPath, `${JSON.stringify(session, null, 2)}\n`, {
+    mode: 0o600
+  });
+
+  // Write to GitHub Actions environment
+  if (env.GITHUB_ENV) {
+    appendFileSync(env.GITHUB_ENV, `VIZZLY_BUILD_ID=${context.buildId}\n`);
+  }
+
+  // Also write to GitHub Actions output if we're in a step
+  if (env.GITHUB_OUTPUT) {
+    appendFileSync(env.GITHUB_OUTPUT, `build-id=${context.buildId}\n`);
+  }
+}
+
+/**
+ * Read build context from session file or environment
+ *
+ * Priority:
+ * 1. VIZZLY_BUILD_ID environment variable
+ * 2. Session file (if recent and optionally matching branch)
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Working directory
+ * @param {string} [options.currentBranch] - Current git branch (for validation)
+ * @param {Object} [options.env] - Environment variables
+ * @param {number} [options.maxAgeMs] - Max session age in ms
+ * @returns {Object|null} Session context or null if not found/invalid
+ */
+export function readSession(options = {}) {
+  let {
+    cwd = process.cwd(),
+    currentBranch = null,
+    env = process.env,
+    maxAgeMs = SESSION_MAX_AGE_MS
+  } = options;
+
+  // Check environment variable first
+  if (env.VIZZLY_BUILD_ID) {
+    return {
+      buildId: env.VIZZLY_BUILD_ID,
+      source: 'environment'
+    };
+  }
+
+  // Try session file
+  let sessionPath = getSessionPath(cwd);
+  if (!existsSync(sessionPath)) {
+    return null;
+  }
+  try {
+    let content = readFileSync(sessionPath, 'utf-8');
+    let session = JSON.parse(content);
+
+    // Validate required field
+    if (!session.buildId) {
+      return null;
+    }
+
+    // Check age
+    let createdAt = new Date(session.createdAt);
+    let age = Date.now() - createdAt.getTime();
+    if (age > maxAgeMs) {
+      return {
+        ...session,
+        source: 'session_file',
+        expired: true,
+        age
+      };
+    }
+
+    // Check branch match (if current branch provided)
+    let branchMismatch = false;
+    if (currentBranch && session.branch && session.branch !== currentBranch) {
+      branchMismatch = true;
+    }
+    return {
+      ...session,
+      source: 'session_file',
+      expired: false,
+      branchMismatch,
+      age
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clear the session file
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Working directory
+ */
+export function clearSession(options = {}) {
+  let {
+    cwd = process.cwd()
+  } = options;
+  let sessionPath = getSessionPath(cwd);
+  try {
+    if (existsSync(sessionPath)) {
+      writeFileSync(sessionPath, '');
+    }
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Format session age for display
+ *
+ * @param {number} ageMs - Age in milliseconds
+ * @returns {string} Human-readable age
+ */
+export function formatSessionAge(ageMs) {
+  let seconds = Math.floor(ageMs / 1000);
+  let minutes = Math.floor(seconds / 60);
+  let hours = Math.floor(minutes / 60);
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m ago`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ago`;
+  }
+  return `${seconds}s ago`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.22.2",
+  "version": "0.23.1",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",