♻️ Split uploader boundaries (#262)

Why: merge the uploader boundary cleanup into the remaining audit integration base so the final PR can verify the full tail together.\n\nWhat changed:\n- Moved uploader implementation into the uploader module boundary.\n- Updated public/command/SDK imports to the new uploader boundary.\n- Replaced old service tests with uploader boundary tests.\n\nVerification:\n- node --test tests/uploader/index.test.js tests/commands/upload.test.js tests/commands/run.test.js tests/sdk/index.test.js\n- Final verification will happen on the last PR back to main.

Author: Robdel12

src/commands/run.js

@@ -14,7 +14,7 @@ import {
 import { VizzlyError } from '../errors/vizzly-error.js';
 import { createServerManager as defaultCreateServerManager } from '../server-manager/index.js';
 import { createBuildObject as defaultCreateBuildObject } from '../services/build-manager.js';
-import { createUploader as defaultCreateUploader } from '../services/uploader.js';
+import { createUploader as defaultCreateUploader } from '../uploader/index.js';
 import {
   finalizeBuild as defaultFinalizeBuild,
   runTests as defaultRunTests,

src/commands/upload.js

@@ -3,7 +3,7 @@ import {
   finalizeBuild as defaultFinalizeBuild,
   getTokenContext as defaultGetTokenContext,
 } from '../api/index.js';
-import { createUploader as defaultCreateUploader } from '../services/uploader.js';
+import { createUploader as defaultCreateUploader } from '../uploader/index.js';
 import { getAppBaseUrl } from '../utils/api-url.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import {

src/index.js

@@ -16,7 +16,7 @@ export { UploadError } from './errors/vizzly-error.js';
 export { createVizzly } from './sdk/index.js';
 export { createServices } from './services/index.js';
 // Core services (for advanced usage)
-export { createUploader } from './services/uploader.js';
+export { createUploader } from './uploader/index.js';
 export { createTDDService } from './tdd/tdd-service.js';
 // Configuration helper
 export { defineConfig } from './utils/config-helpers.js';

src/sdk/index.js

@@ -18,7 +18,7 @@ import {
   startServer as startScreenshotServer,
   stopServer as stopScreenshotServer,
 } from '../screenshot-server/index.js';
-import { createUploader } from '../services/uploader.js';
+import { createUploader } from '../uploader/index.js';
 import { createTDDService } from '../tdd/tdd-service.js';
 import { loadConfig } from '../utils/config-loader.js';
 import { resolveImageBuffer } from '../utils/file-helpers.js';
@@ -449,7 +449,7 @@ export class VizzlySDK extends EventEmitter {
 }
 
 // Export service creators for advanced usage
-export { createUploader } from '../services/uploader.js';
+export { createUploader } from '../uploader/index.js';
 export { createTDDService } from '../tdd/tdd-service.js';
 // Re-export key utilities and errors
 export { loadConfig } from '../utils/config-loader.js';

src/services/uploader.js

@@ -14,6 +14,7 @@ import { basename } from 'node:path';
 export const DEFAULT_BATCH_SIZE = 50;
 export const DEFAULT_SHA_CHECK_BATCH_SIZE = 100;
 export const DEFAULT_TIMEOUT = 30000; // 30 seconds
+export const DEFAULT_BUILD_POLL_INTERVAL = 1000; // 1 second
 
 // ============================================================================
 // Validation
@@ -340,17 +341,17 @@ export function resolveTimeout(options, uploadConfig) {
  * @param {number} timeout - Timeout in ms
  * @returns {boolean} True if timed out
  */
-export function isTimedOut(startTime, timeout) {
-  return Date.now() - startTime >= timeout;
+export function isTimedOut(startTime, timeout, now = Date.now()) {
+  return now - startTime >= timeout;
 }
 
 /**
  * Get elapsed time since start
  * @param {number} startTime - Start timestamp
  * @returns {number} Elapsed time in ms
  */
-export function getElapsedTime(startTime) {
-  return Date.now() - startTime;
+export function getElapsedTime(startTime, now = Date.now()) {
+  return now - startTime;
 }
 
 /**

src/uploader/core.js

@@ -1,9 +1,91 @@
 /**
  * Uploader Module
  *
- * Exports pure functions (core) and I/O operations for screenshot uploading.
+ * Exports pure functions (core), I/O operations, and the public uploader
+ * factory for screenshot uploading.
  */
 
+import { readFile, stat } from 'node:fs/promises';
+import { glob } from 'glob';
+import { checkShas, createApiClient, createBuild } from '../api/index.js';
+import {
+  TimeoutError,
+  UploadError,
+  ValidationError,
+} from '../errors/vizzly-error.js';
+import { getDefaultBranch } from '../utils/git.js';
+import * as output from '../utils/output.js';
+import { resolveBatchSize, resolveTimeout } from './core.js';
+import {
+  upload as uploadOperation,
+  waitForBuild as waitForBuildOperation,
+} from './operations.js';
+
+export function createUploader(
+  { apiKey, apiUrl, userAgent, command, upload: uploadConfig = {} } = {},
+  options = {}
+) {
+  let signal = options.signal || new AbortController().signal;
+  let client = createApiClient({
+    baseUrl: apiUrl,
+    token: apiKey,
+    command: command || 'upload',
+    sdkUserAgent: userAgent,
+    allowNoToken: true,
+  });
+
+  let batchSize = resolveBatchSize(options, uploadConfig);
+  let timeout = resolveTimeout(options, uploadConfig);
+  let deps = options.deps || {
+    client,
+    createBuild,
+    getDefaultBranch,
+    glob,
+    readFile,
+    stat,
+    checkShas,
+    createError: (message, code, context) => {
+      let error = new UploadError(message, context);
+      error.code = code;
+      return error;
+    },
+    createValidationError: (message, context) =>
+      new ValidationError(message, context),
+    createUploadError: (message, context) => new UploadError(message, context),
+    createTimeoutError: (message, context) =>
+      new TimeoutError(message, context),
+    output,
+  };
+
+  async function upload(uploadOptions) {
+    return uploadOperation({
+      uploadOptions,
+      config: { apiKey, apiUrl },
+      signal,
+      batchSize,
+      deps: {
+        ...deps,
+        client: deps.client || client,
+      },
+    });
+  }
+
+  async function waitForBuild(buildId, waitTimeout = timeout) {
+    return waitForBuildOperation({
+      buildId,
+      timeout: waitTimeout,
+      signal,
+      client: deps.client || client,
+      deps: {
+        createError: deps.createError,
+        createTimeoutError: deps.createTimeoutError,
+      },
+    });
+  }
+
+  return { upload, waitForBuild };
+}
+
 // Core - pure functions
 export {
   buildBuildInfo,
@@ -18,6 +100,7 @@ export {
   buildWaitResult,
   computeSha256,
   DEFAULT_BATCH_SIZE,
+  DEFAULT_BUILD_POLL_INTERVAL,
   DEFAULT_SHA_CHECK_BATCH_SIZE,
   DEFAULT_TIMEOUT,
   extractBrowserFromFilename,

src/uploader/index.js

@@ -15,6 +15,7 @@ import {
   buildUploadingProgress,
   buildUploadResult,
   buildWaitResult,
+  DEFAULT_BUILD_POLL_INTERVAL,
   DEFAULT_SHA_CHECK_BATCH_SIZE,
   extractStatusCodeFromError,
   fileToScreenshotFormat,
@@ -27,6 +28,38 @@ import {
   validateScreenshotsDir,
 } from './core.js';
 
+function delay(ms, signal) {
+  if (ms <= 0) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve, reject) => {
+    let timeoutId;
+
+    function cleanup() {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener?.('abort', handleAbort);
+    }
+
+    function handleAbort() {
+      cleanup();
+      reject(new Error('Operation cancelled'));
+    }
+
+    timeoutId = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+
+    if (signal?.aborted) {
+      handleAbort();
+      return;
+    }
+
+    signal?.addEventListener?.('abort', handleAbort, { once: true });
+  });
+}
+
 // ============================================================================
 // File Discovery
 // ============================================================================
@@ -232,10 +265,16 @@ export async function uploadFiles({
  * @returns {Promise<Object>} Build result
  */
 export async function waitForBuild({ buildId, timeout, signal, client, deps }) {
-  let { createError, createTimeoutError } = deps;
-  let startTime = Date.now();
+  let {
+    createError,
+    createTimeoutError,
+    now = () => Date.now(),
+    pollInterval = DEFAULT_BUILD_POLL_INTERVAL,
+    wait = delay,
+  } = deps;
+  let startTime = now();
 
-  while (!isTimedOut(startTime, timeout)) {
+  while (!isTimedOut(startTime, timeout, now())) {
     if (signal.aborted) {
       throw createError('Operation cancelled', 'UPLOAD_CANCELLED', { buildId });
     }
@@ -263,12 +302,19 @@ export async function waitForBuild({ buildId, timeout, signal, client, deps }) {
         'BUILD_FAILED'
       );
     }
+
+    let remaining = timeout - getElapsedTime(startTime, now());
+    if (remaining <= 0) {
+      break;
+    }
+
+    await wait(Math.min(pollInterval, remaining), signal);
   }
 
   throw createTimeoutError(`Build timed out after ${timeout}ms`, {
     buildId,
     timeout,
-    elapsed: getElapsedTime(startTime),
+    elapsed: getElapsedTime(startTime, now()),
   });
 }