@vizzly-testing/cli 0.30.0 → 0.31.0

package/dist/commands/login.js

@@ -7,18 +7,127 @@ import { completeDeviceFlow, createAuthClient, createTokenStore, initiateDeviceF
 import { openBrowser } from '../utils/browser.js';
 import { getApiUrl } from '../utils/environment-config.js';
 import * as output from '../utils/output.js';
+function createLoginDeps(deps = {}) {
+  return {
+    completeDeviceFlow: deps.completeDeviceFlow || completeDeviceFlow,
+    createAuthClient: deps.createAuthClient || createAuthClient,
+    createTokenStore: deps.createTokenStore || createTokenStore,
+    getApiUrl: deps.getApiUrl || getApiUrl,
+    initiateDeviceFlow: deps.initiateDeviceFlow || initiateDeviceFlow,
+    now: deps.now || (() => Date.now()),
+    openBrowser: deps.openBrowser || openBrowser,
+    output: deps.output || output,
+    pollDeviceAuthorization: deps.pollDeviceAuthorization || pollDeviceAuthorization,
+    waitForEnter: deps.waitForEnter || waitForEnter,
+    exit: deps.exit || (code => process.exit(code))
+  };
+}
+function configureOutput(output, globalOptions) {
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+}
+export function normalizeDeviceFlowResponse(deviceFlow) {
+  let verificationUri = deviceFlow.verification_uri || deviceFlow.verificationUri;
+  let userCode = deviceFlow.user_code || deviceFlow.userCode;
+  let deviceCode = deviceFlow.device_code || deviceFlow.deviceCode;
+  if (!verificationUri || !userCode || !deviceCode) {
+    throw new Error('Invalid device flow response from server');
+  }
+  return {
+    verificationUri,
+    userCode,
+    deviceCode,
+    urlWithCode: `${verificationUri}?code=${encodeURIComponent(userCode)}`
+  };
+}
+export function resolveAuthorizedTokenData(pollResponse) {
+  let accessToken = pollResponse.tokens?.accessToken || pollResponse.tokens?.access_token;
+  if (accessToken) {
+    return pollResponse;
+  }
+  if (pollResponse.status === 'pending') {
+    throw new Error('Authorization not complete yet. Please complete the authorization in your browser and try running "vizzly login" again.');
+  }
+  if (pollResponse.status === 'expired') {
+    throw new Error('Device code expired. Please try logging in again.');
+  }
+  if (pollResponse.status === 'denied') {
+    throw new Error('Authorization denied. Please try logging in again.');
+  }
+  throw new Error('Unexpected response from authorization server. Please try logging in again.');
+}
+export function buildTokens(tokenData, now = Date.now()) {
+  let tokensData = tokenData.tokens || tokenData;
+  let tokenExpiresIn = tokensData.expiresIn || tokensData.expires_in;
+  let tokenExpiresAt = tokenExpiresIn ? new Date(now + tokenExpiresIn * 1000).toISOString() : tokenData.expires_at || tokenData.expiresAt;
+  return {
+    accessToken: tokensData.accessToken || tokensData.access_token,
+    refreshToken: tokensData.refreshToken || tokensData.refresh_token,
+    expiresAt: tokenExpiresAt,
+    user: tokenData.user,
+    organizations: tokenData.organizations
+  };
+}
+export function getTokenExpiryHint(expiresAt, now = Date.now()) {
+  if (!expiresAt) {
+    return null;
+  }
+  let expiry = new Date(expiresAt);
+  let msUntilExpiry = expiry.getTime() - now;
+  let daysUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60 * 60 * 24));
+  let hoursUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60 * 60));
+  let minutesUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60));
+  if (daysUntilExpiry > 0) {
+    return `Token expires in ${daysUntilExpiry} day${daysUntilExpiry !== 1 ? 's' : ''}`;
+  }
+  if (hoursUntilExpiry > 0) {
+    return `Token expires in ${hoursUntilExpiry} hour${hoursUntilExpiry !== 1 ? 's' : ''}`;
+  }
+  if (minutesUntilExpiry > 0) {
+    return `Token expires in ${minutesUntilExpiry} minute${minutesUntilExpiry !== 1 ? 's' : ''}`;
+  }
+  return null;
+}
+export async function waitForEnter(stdin = process.stdin) {
+  await new Promise(resolve => {
+    let canSetRawMode = typeof stdin.setRawMode === 'function';
+    if (canSetRawMode) {
+      stdin.setRawMode(true);
+    }
+    stdin.resume();
+    stdin.once('data', () => {
+      if (canSetRawMode) {
+        stdin.setRawMode(false);
+      }
+      stdin.pause();
+      resolve();
+    });
+  });
+}
 
 /**
  * Login command implementation using OAuth device flow
  * @param {Object} options - Command options
  * @param {Object} globalOptions - Global CLI options
  */
-export async function loginCommand(options = {}, globalOptions = {}) {
-  output.configure({
-    json: globalOptions.json,
-    verbose: globalOptions.verbose,
-    color: !globalOptions.noColor
-  });
+export async function loginCommand(options = {}, globalOptions = {}, deps = {}) {
+  let {
+    completeDeviceFlow,
+    createAuthClient,
+    createTokenStore,
+    getApiUrl,
+    initiateDeviceFlow,
+    now,
+    openBrowser,
+    output,
+    pollDeviceAuthorization,
+    waitForEnter,
+    exit
+  } = createLoginDeps(deps);
+  configureOutput(output, globalOptions);
   let colors = output.getColors();
   try {
     output.header('login');
@@ -35,15 +144,11 @@ export async function loginCommand(options = {}, globalOptions = {}) {
     output.stopSpinner();
 
     // Handle both snake_case and camelCase field names
-    let verificationUri = deviceFlow.verification_uri || deviceFlow.verificationUri;
-    let userCode = deviceFlow.user_code || deviceFlow.userCode;
-    let deviceCode = deviceFlow.device_code || deviceFlow.deviceCode;
-    if (!verificationUri || !userCode || !deviceCode) {
-      throw new Error('Invalid device flow response from server');
-    }
-
-    // Build URL with pre-filled code
-    let urlWithCode = `${verificationUri}?code=${userCode}`;
+    let {
+      deviceCode,
+      urlWithCode,
+      userCode
+    } = normalizeDeviceFlowResponse(deviceFlow);
 
     // Display user code prominently in a box
     output.printBox(['Visit this URL to authorize:', '', colors.brand.info(urlWithCode), '', 'Your code:', '', colors.bold(colors.brand.amber(userCode))], {
@@ -64,48 +169,17 @@ export async function loginCommand(options = {}, globalOptions = {}) {
     output.hint('After authorizing, press Enter to continue...');
 
     // Wait for user to press Enter
-    await new Promise(resolve => {
-      process.stdin.setRawMode(true);
-      process.stdin.resume();
-      process.stdin.once('data', () => {
-        process.stdin.setRawMode(false);
-        process.stdin.pause();
-        resolve();
-      });
-    });
+    await waitForEnter();
 
     // Check authorization status
     output.startSpinner('Checking authorization...');
     let pollResponse = await pollDeviceAuthorization(client, deviceCode);
     output.stopSpinner();
-    let tokenData = null;
-
-    // Check if authorization was successful by looking for tokens
-    if (pollResponse.tokens?.accessToken) {
-      // Success! We got tokens
-      tokenData = pollResponse;
-    } else if (pollResponse.status === 'pending') {
-      throw new Error('Authorization not complete yet. Please complete the authorization in your browser and try running "vizzly login" again.');
-    } else if (pollResponse.status === 'expired') {
-      throw new Error('Device code expired. Please try logging in again.');
-    } else if (pollResponse.status === 'denied') {
-      throw new Error('Authorization denied. Please try logging in again.');
-    } else {
-      throw new Error('Unexpected response from authorization server. Please try logging in again.');
-    }
+    let tokenData = resolveAuthorizedTokenData(pollResponse);
 
     // Complete device flow and save tokens
     // Handle both snake_case and camelCase for token data, and nested tokens object
-    let tokensData = tokenData.tokens || tokenData;
-    let tokenExpiresIn = tokensData.expiresIn || tokensData.expires_in;
-    let tokenExpiresAt = tokenExpiresIn ? new Date(Date.now() + tokenExpiresIn * 1000).toISOString() : tokenData.expires_at || tokenData.expiresAt;
-    let tokens = {
-      accessToken: tokensData.accessToken || tokensData.access_token,
-      refreshToken: tokensData.refreshToken || tokensData.refresh_token,
-      expiresAt: tokenExpiresAt,
-      user: tokenData.user,
-      organizations: tokenData.organizations
-    };
+    let tokens = buildTokens(tokenData, now());
     await completeDeviceFlow(tokenStore, tokens);
 
     // Display success
@@ -131,21 +205,13 @@ export async function loginCommand(options = {}, globalOptions = {}) {
     // Show token expiry info
     if (tokens.expiresAt) {
       output.blank();
-      let expiresAt = new Date(tokens.expiresAt);
-      let msUntilExpiry = expiresAt.getTime() - Date.now();
-      let daysUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60 * 60 * 24));
-      let hoursUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60 * 60));
-      let minutesUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60));
-      if (daysUntilExpiry > 0) {
-        output.hint(`Token expires in ${daysUntilExpiry} day${daysUntilExpiry !== 1 ? 's' : ''}`);
-      } else if (hoursUntilExpiry > 0) {
-        output.hint(`Token expires in ${hoursUntilExpiry} hour${hoursUntilExpiry !== 1 ? 's' : ''}`);
-      } else if (minutesUntilExpiry > 0) {
-        output.hint(`Token expires in ${minutesUntilExpiry} minute${minutesUntilExpiry !== 1 ? 's' : ''}`);
+      let expiryHint = getTokenExpiryHint(tokens.expiresAt, now());
+      if (expiryHint) {
+        output.hint(expiryHint);
       }
     }
     output.blank();
-    output.hint('You can now use Vizzly CLI commands without VIZZLY_TOKEN');
+    output.hint('Run "vizzly project link <org>/<project>" to enable cloud uploads');
     output.cleanup();
   } catch (error) {
     output.stopSpinner();
@@ -156,15 +222,18 @@ export async function loginCommand(options = {}, globalOptions = {}) {
       output.blank();
       output.hint('Please try logging in again');
       output.hint("If you don't have an account, sign up at https://vizzly.dev");
-      process.exit(1);
+      output.cleanup();
+      exit(1);
     } else if (error.code === 'RATE_LIMIT_ERROR') {
       output.error('Too many login attempts', error);
       output.blank();
       output.hint('Please wait a few minutes before trying again');
-      process.exit(1);
+      output.cleanup();
+      exit(1);
     } else {
       output.error('Login failed', error);
-      process.exit(1);
+      output.cleanup();
+      exit(1);
     }
   }
 }
@@ -174,7 +243,7 @@ export async function loginCommand(options = {}, globalOptions = {}) {
  * @param {Object} options - Command options
  */
 export function validateLoginOptions() {
-  const errors = [];
+  let errors = [];
 
   // No specific validation needed for login command
   // OAuth device flow handles everything via browser

package/dist/commands/logout.js

@@ -3,16 +3,26 @@
  * Clears stored authentication tokens
  */
 
-import { createAuthClient, createTokenStore, getAuthTokens, logout } from '../auth/index.js';
-import { getApiUrl } from '../utils/environment-config.js';
-import * as output from '../utils/output.js';
+import { createAuthClient as defaultCreateAuthClient, createTokenStore as defaultCreateTokenStore, getAuthTokens as defaultGetAuthTokens, logout as defaultLogout } from '../auth/index.js';
+import { getApiUrl as defaultGetApiUrl } from '../utils/environment-config.js';
+import * as defaultOutput from '../utils/output.js';
 
 /**
  * Logout command implementation
  * @param {Object} options - Command options
  * @param {Object} globalOptions - Global CLI options
+ * @param {Object} deps - Dependencies for testing
  */
-export async function logoutCommand(options = {}, globalOptions = {}) {
+export async function logoutCommand(options = {}, globalOptions = {}, deps = {}) {
+  let {
+    createAuthClient = defaultCreateAuthClient,
+    createTokenStore = defaultCreateTokenStore,
+    getApiUrl = defaultGetApiUrl,
+    getAuthTokens = defaultGetAuthTokens,
+    logout = defaultLogout,
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
   output.configure({
     json: globalOptions.json,
     verbose: globalOptions.verbose,
@@ -57,7 +67,8 @@ export async function logoutCommand(options = {}, globalOptions = {}) {
   } catch (error) {
     output.stopSpinner();
     output.error('Logout failed', error);
-    process.exit(1);
+    output.cleanup();
+    exit(1);
   }
 }
 
@@ -66,7 +77,7 @@ export async function logoutCommand(options = {}, globalOptions = {}) {
  * @param {Object} options - Command options
  */
 export function validateLogoutOptions() {
-  const errors = [];
+  let errors = [];
 
   // No specific validation needed for logout command
 

package/dist/commands/preview.js

@@ -5,10 +5,10 @@
  * The build is automatically detected from session file or environment.
  */
 
-import { exec, execSync } from 'node:child_process';
+import { execFile, execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { existsSync, statSync } from 'node:fs';
-import { readFile, realpath, stat, unlink } from 'node:fs/promises';
+import { readdir, readFile, realpath, stat, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { promisify } from 'node:util';
@@ -17,23 +17,13 @@ import { openBrowser as defaultOpenBrowser } from '../utils/browser.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import { detectBranch as defaultDetectBranch } from '../utils/git.js';
 import * as defaultOutput from '../utils/output.js';
+import { createWildcardMatcher } from '../utils/patterns.js';
 import { formatSessionAge as defaultFormatSessionAge, readSession as defaultReadSession } from '../utils/session.js';
-let execAsync = promisify(exec);
+let execFileAsync = promisify(execFile);
 
 // Maximum files to show in dry-run output (use --verbose for all)
 let DRY_RUN_FILE_LIMIT = 50;
 
-/**
- * Validate path for shell safety - prevents command injection
- * @param {string} path - Path to validate
- * @returns {boolean} true if path is safe for shell use
- */
-function isPathSafe(path) {
-  // Reject paths with shell metacharacters that could enable command injection
-  let dangerousChars = /[`$;&|<>(){}[\]\\!*?'"]/;
-  return !dangerousChars.test(path);
-}
-
 /**
  * Check if a command exists on the system
  * @param {string} command - Command to check
@@ -42,7 +32,7 @@ function isPathSafe(path) {
 function commandExists(command) {
   try {
     let checkCmd = process.platform === 'win32' ? 'where' : 'which';
-    execSync(`${checkCmd} ${command}`, {
+    execFileSync(checkCmd, [command], {
       stdio: 'ignore'
     });
     return true;
@@ -50,6 +40,9 @@ function commandExists(command) {
     return false;
   }
 }
+function quotePowerShellString(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
 
 /**
  * Get the appropriate zip command for the current platform
@@ -92,9 +85,10 @@ let DEFAULT_EXCLUDED_FILES = ['package.json', 'package-lock.json', 'yarn.lock',
 function matchesPattern(filename, patterns) {
   for (let pattern of patterns) {
     if (pattern.includes('*')) {
-      // Simple glob matching - convert to regex
-      let regex = new RegExp(`^${pattern.replace(/\./g, '\\.').replace(/\*/g, '.*')}$`);
-      if (regex.test(filename)) return true;
+      let matches = createWildcardMatcher(pattern, {
+        anchored: true
+      });
+      if (matches(filename)) return true;
     } else {
       if (filename === pattern) return true;
     }
@@ -123,48 +117,37 @@ async function createZipWithSystem(sourceDir, outputPath, exclusions = {}) {
   if (!available) {
     throw new Error('No zip command found. Please install zip or use PowerShell on Windows.');
   }
-
-  // Validate paths to prevent command injection
-  // Note: outputPath is internally generated (tmpdir + random), so always safe
-  // sourceDir comes from user input, so we validate it
-  if (!isPathSafe(sourceDir)) {
-    throw new Error('Path contains unsupported characters. Please use a path without special shell characters.');
-  }
-
-  // Validate exclusion patterns to prevent command injection
-  // Only allow safe characters in patterns: alphanumeric, dots, asterisks, underscores, hyphens, slashes
-  let safePatternRegex = /^[a-zA-Z0-9.*_\-/]+$/;
-  for (let pattern of [...dirs, ...files]) {
-    if (!safePatternRegex.test(pattern)) {
-      throw new Error(`Exclusion pattern contains unsafe characters: ${pattern}. Only alphanumeric, ., *, _, -, / are allowed.`);
-    }
-  }
   if (command === 'zip') {
     // Standard zip command - create ZIP from directory contents
-    // Using cwd option is safe as it's not part of the command string
     // -r: recursive, -q: quiet, -x: exclude patterns
-    let excludeArgs = [...dirs.map(dir => `-x "${dir}/*"`), ...files.map(pattern => `-x "${pattern}"`)].join(' ');
-    await execAsync(`zip -r -q "${outputPath}" . ${excludeArgs}`, {
+    let excludeArgs = [];
+    for (let dir of dirs) {
+      excludeArgs.push('-x', `${dir}/*`);
+    }
+    for (let pattern of files) {
+      excludeArgs.push('-x', pattern);
+    }
+    await execFileAsync('zip', ['-r', '-q', outputPath, '.', ...excludeArgs], {
       cwd: sourceDir,
       maxBuffer: 1024 * 1024 * 100 // 100MB buffer
     });
   } else if (command === 'powershell') {
     // Windows PowerShell - Compress-Archive doesn't support exclusions,
     // so we create a temp directory with only the files we want
-    let safeSrcDir = sourceDir.replace(/'/g, "''");
-    let safeOutPath = outputPath.replace(/'/g, "''");
+    let safeSrcDir = quotePowerShellString(sourceDir);
+    let safeOutPath = quotePowerShellString(outputPath);
 
     // Build exclusion filter for PowerShell
     // We use Get-ChildItem with -Exclude and pipe to Compress-Archive
-    let excludePatterns = [...dirs, ...files].map(p => `'${p}'`).join(',');
+    let excludePatterns = [...dirs, ...files].map(quotePowerShellString).join(',');
     if (excludePatterns) {
       // Use robocopy to copy files excluding patterns, then zip
       // This is more reliable than PowerShell's native filtering
-      await execAsync(`powershell -Command "` + `$src = '${safeSrcDir}'; ` + `$dst = '${safeOutPath}'; ` + `$exclude = @(${excludePatterns}); ` + `$items = Get-ChildItem -Path $src -Recurse -File | Where-Object { ` + `$rel = $_.FullName.Substring($src.Length + 1); ` + `$dominated = $false; ` + `foreach ($ex in $exclude) { if ($rel -like $ex -or $rel -like \\"$ex/*\\" -or $_.Name -like $ex) { $dominated = $true; break } }; ` + `-not $dominated ` + `}; ` + `if ($items) { $items | Compress-Archive -DestinationPath $dst -Force }"`, {
+      await execFileAsync('powershell', ['-Command', `$src = ${safeSrcDir}; ` + `$dst = ${safeOutPath}; ` + `$exclude = @(${excludePatterns}); ` + `$items = Get-ChildItem -Path $src -Recurse -File | Where-Object { ` + `$rel = $_.FullName.Substring($src.Length + 1); ` + `$dominated = $false; ` + `foreach ($ex in $exclude) { if ($rel -like $ex -or $rel -like "$ex/*" -or $_.Name -like $ex) { $dominated = $true; break } }; ` + `-not $dominated ` + `}; ` + `if ($items) { $items | Compress-Archive -DestinationPath $dst -Force }`], {
         maxBuffer: 1024 * 1024 * 100
       });
     } else {
-      await execAsync(`powershell -Command "Compress-Archive -LiteralPath '${safeSrcDir}\\*' -DestinationPath '${safeOutPath}' -Force"`, {
+      await execFileAsync('powershell', ['-Command', `Compress-Archive -LiteralPath ${quotePowerShellString(`${sourceDir}\\*`)} -DestinationPath ${safeOutPath} -Force`], {
         maxBuffer: 1024 * 1024 * 100
       });
     }
@@ -182,9 +165,6 @@ async function createZipWithSystem(sourceDir, outputPath, exclusions = {}) {
  * @returns {Promise<{ count: number, totalSize: number, files?: Array<{path: string, size: number}> }>}
  */
 async function countFiles(dir, options = {}) {
-  let {
-    readdir
-  } = await import('node:fs/promises');
   let {
     collectPaths = false,
     excludedDirs = DEFAULT_EXCLUDED_DIRS,
@@ -327,15 +307,6 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
     // Resolve build ID
     let buildId = options.build;
     let buildSource = 'flag';
-    if (!buildId && options.parallelId) {
-      // TODO: Look up build by parallel ID
-      output.error('Parallel ID lookup not yet implemented. Use --build to specify build ID directly.');
-      exit(1);
-      return {
-        success: false,
-        reason: 'parallel-id-not-implemented'
-      };
-    }
     if (!buildId) {
       // Try to read from session
       let currentBranch = await detectBranch();
@@ -583,8 +554,9 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       // Always clean up temp file
       await unlink(zipPath).catch(() => {});
     }
-    let compressionRatio = ((1 - zipBuffer.length / totalSize) * 100).toFixed(0);
-    output.updateSpinner(`Compressed to ${formatBytes(zipBuffer.length)} (${compressionRatio}% smaller)`);
+    let compressionRatio = 1 - zipBuffer.length / totalSize;
+    let compressionPercent = Math.round(compressionRatio * 100);
+    output.updateSpinner(`Compressed to ${formatBytes(zipBuffer.length)} (${compressionPercent}% smaller)`);
 
     // Upload (reuse client created earlier)
     output.updateSpinner('Uploading preview...');
@@ -600,7 +572,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
         files: result.uploaded || fileCount,
         bytes: totalSize,
         compressedBytes: zipBuffer.length,
-        compressionRatio: parseFloat(compressionRatio) / 100,
+        compressionRatio,
         newBytes: result.newBytes,
         reusedBlobs: result.reusedBlobs || 0,
         deduplicationRatio: result.deduplicationRatio,

package/dist/commands/project.js

@@ -0,0 +1,120 @@
+import { createApiClient as defaultCreateApiClient } from '../api/client.js';
+import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
+import { getApiUrl as defaultGetApiUrl } from '../utils/environment-config.js';
+import { getAccessToken as defaultGetAccessToken } from '../utils/global-config.js';
+import * as defaultOutput from '../utils/output.js';
+import { saveProjectLink as defaultSaveProjectLink } from '../utils/project-link-store.js';
+export function parseProjectSelector(selector, options = {}) {
+  let organizationSlug = options.org || null;
+  let projectSlug = options.project || null;
+  if (selector) {
+    let parts = selector.split('/');
+    if (parts.length === 2) {
+      organizationSlug = organizationSlug || parts[0];
+      projectSlug = projectSlug || parts[1];
+    } else if (parts.length === 1) {
+      projectSlug = projectSlug || parts[0];
+    }
+  }
+  return {
+    organizationSlug,
+    projectSlug
+  };
+}
+export function validateProjectLinkOptions(selector, options = {}) {
+  let errors = [];
+  let {
+    organizationSlug,
+    projectSlug
+  } = parseProjectSelector(selector, options);
+  if (!organizationSlug) {
+    errors.push('Organization is required. Use <org>/<project> or --org <slug>.');
+  }
+  if (!projectSlug) {
+    errors.push('Project is required. Use <org>/<project> or --project <slug>.');
+  }
+  return errors;
+}
+export async function projectLinkCommand(selector, options = {}, globalOptions = {}, deps = {}) {
+  let {
+    createApiClient = defaultCreateApiClient,
+    getAccessToken = defaultGetAccessToken,
+    getApiUrl = defaultGetApiUrl,
+    loadConfig = defaultLoadConfig,
+    output = defaultOutput,
+    saveProjectLink = defaultSaveProjectLink,
+    exit = code => process.exit(code)
+  } = deps;
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  let {
+    organizationSlug,
+    projectSlug
+  } = parseProjectSelector(selector, options);
+  try {
+    let config = await loadConfig(globalOptions.config, globalOptions);
+    let userToken = config.userToken || (await getAccessToken());
+    if (!userToken) {
+      output.error('Login required before linking a project');
+      output.hint('Run "vizzly login" first, then try project link again');
+      output.cleanup();
+      exit(1);
+      return;
+    }
+    output.startSpinner(`Linking ${organizationSlug}/${projectSlug}...`);
+    let apiUrl = config.apiUrl || getApiUrl();
+    let client = createApiClient({
+      baseUrl: apiUrl,
+      token: userToken,
+      command: 'project-link'
+    });
+    let response = await client.request(`/api/cli/${projectSlug}/link-token`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Organization': organizationSlug
+      },
+      body: JSON.stringify({
+        name: options.name,
+        expiresAt: options.expiresAt
+      })
+    });
+    let linkedProject = await saveProjectLink({
+      apiUrl,
+      organizationSlug: response.organization?.slug || organizationSlug,
+      organizationName: response.organization?.name,
+      projectSlug: response.project?.slug || projectSlug,
+      projectName: response.project?.name,
+      token: response.token.token,
+      tokenId: response.token.id,
+      tokenPrefix: response.token.token_prefix,
+      expiresAt: response.token.expires_at,
+      createdAt: response.token.created_at
+    });
+    output.stopSpinner();
+    if (globalOptions.json) {
+      output.data({
+        linked: true,
+        organizationSlug: linkedProject.organizationSlug,
+        projectSlug: linkedProject.projectSlug,
+        tokenPrefix: linkedProject.tokenPrefix,
+        storage: linkedProject.storage
+      });
+      output.cleanup();
+      return;
+    }
+    output.complete(`Linked ${linkedProject.organizationSlug}/${linkedProject.projectSlug}`);
+    output.hint(`Active project: ${linkedProject.organizationSlug}/${linkedProject.projectSlug}`);
+    output.hint(`Cloud uploads and project-scoped context will use ${linkedProject.tokenPrefix}...`);
+    output.hint(`Credential storage: ${linkedProject.storage}`);
+    output.cleanup();
+  } catch (error) {
+    output.stopSpinner();
+    output.error('Failed to link project', error);
+    output.cleanup();
+    exit(1);
+  }
+}

package/dist/commands/projects.js

@@ -106,6 +106,13 @@ export async function projectsCommand(options = {}, globalOptions = {}, deps = {
  * @param {Object} _options - Command options
  * @returns {string[]} Validation errors
  */
-export function validateProjectsOptions(_options = {}) {
-  return [];
+export function validateProjectsOptions(options = {}) {
+  let errors = [];
+  if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 250)) {
+    errors.push('--limit must be an integer between 1 and 250');
+  }
+  if (options.offset !== undefined && (!Number.isInteger(options.offset) || options.offset < 0)) {
+    errors.push('--offset must be a non-negative integer');
+  }
+  return errors;
 }