launchpd 1.0.3 → 1.0.6

package/src/commands/deploy.js

@@ -1,426 +1,785 @@
-import { existsSync, statSync } from 'node:fs';
-import { exec } from 'node:child_process';
-import chalk from 'chalk';
-import { readdir } from 'node:fs/promises';
-import { resolve, basename, join, relative, sep } from 'node:path';
-import { generateSubdomain } from '../utils/id.js';
-import { uploadFolder, finalizeUpload } from '../utils/upload.js';
-import { getNextVersion } from '../utils/metadata.js';
-import { saveLocalDeployment } from '../utils/localConfig.js';
-import { getNextVersionFromAPI, checkSubdomainAvailable, listSubdomains, MaintenanceError, NetworkError, AuthError } from '../utils/api.js';
-import { getProjectConfig, findProjectRoot, updateProjectConfig, initProjectConfig } from '../utils/projectConfig.js';
-import { success, errorWithSuggestions, info, warning, spinner, formatSize, log, raw } from '../utils/logger.js';
-import { calculateExpiresAt, formatTimeRemaining } from '../utils/expiration.js';
-import { checkQuota, displayQuotaWarnings } from '../utils/quota.js';
-import { getCredentials } from '../utils/credentials.js';
-import { validateStaticOnly } from '../utils/validator.js';
-import { isIgnored } from '../utils/ignore.js';
-import { prompt } from '../utils/prompt.js';
-import { handleCommonError } from '../utils/errors.js';
-import QRCode from 'qrcode';
+import { existsSync, statSync } from 'node:fs'
+import { execFile } from 'node:child_process'
+import chalk from 'chalk'
+import { readdir } from 'node:fs/promises'
+import { resolve, basename, join, relative, sep } from 'node:path'
+import { generateSubdomain } from '../utils/id.js'
+import { uploadFolder, finalizeUpload } from '../utils/upload.js'
+import { getNextVersion } from '../utils/metadata.js'
+import { saveLocalDeployment } from '../utils/localConfig.js'
+import {
+  getNextVersionFromAPI,
+  checkSubdomainAvailable,
+  listSubdomains,
+  MaintenanceError,
+  NetworkError,
+  AuthError
+} from '../utils/api.js'
+import {
+  getProjectConfig,
+  findProjectRoot,
+  updateProjectConfig,
+  initProjectConfig
+} from '../utils/projectConfig.js'
+import {
+  success,
+  errorWithSuggestions,
+  info,
+  warning,
+  spinner,
+  log,
+  raw
+} from '../utils/logger.js'
+import {
+  calculateExpiresAt,
+  formatTimeRemaining
+} from '../utils/expiration.js'
+import {
+  checkQuota,
+  displayQuotaWarnings,
+  formatBytes
+} from '../utils/quota.js'
+import { getCredentials } from '../utils/credentials.js'
+import { validateStaticOnly } from '../utils/validator.js'
+import { isIgnored } from '../utils/ignore.js'
+import { prompt } from '../utils/prompt.js'
+import { handleCommonError } from '../utils/errors.js'
+import {
+  isRemoteUrl,
+  parseRemoteUrl,
+  fetchRemoteSource,
+  cleanupTempDir
+} from '../utils/remoteSource.js'
+import QRCode from 'qrcode'
+
+// ============================================================================
+// Helper Functions (extracted to reduce cyclomatic complexity)
+// ============================================================================
 
 /**
- * Calculate total size of a folder
+ * Validate subdomain contains only safe DNS characters
+ * @param {string} subdomain - The subdomain to validate
+ * @returns {string} The validated subdomain
+ * @throws {Error} If subdomain contains invalid characters
  */
-async function calculateFolderSize(folderPath) {
-    const files = await readdir(folderPath, { recursive: true, withFileTypes: true });
-    let totalSize = 0;
-
-    for (const file of files) {
-        const parentDir = file.parentPath || file.path;
-        const relativePath = relative(folderPath, join(parentDir, file.name));
-        const pathParts = relativePath.split(sep);
-
-        // Skip ignored directories/files in the path
-        if (pathParts.some(part => isIgnored(part, file.isDirectory()))) {
-            continue;
-        }
-
-        if (file.isFile()) {
-            const fullPath = join(parentDir, file.name);
-            try {
-                const stats = statSync(fullPath);
-                totalSize += stats.size;
-            } catch {
-                // File may have been deleted
-            }
-        }
+function validateSubdomain (subdomain) {
+  const safePattern = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/
+  if (!safePattern.test(subdomain)) {
+    throw new Error(
+      `Invalid subdomain "${subdomain}": must contain only lowercase letters, numbers, and hyphens`
+    )
+  }
+  return subdomain
+}
+
+/**
+ * Calculate total size of a folder (excluding ignored files)
+ */
+async function calculateFolderSize (folderPath) {
+  const files = await readdir(folderPath, {
+    recursive: true,
+    withFileTypes: true
+  })
+  let totalSize = 0
+
+  for (const file of files) {
+    const parentDir = file.parentPath || file.path
+    const relativePath = relative(folderPath, join(parentDir, file.name))
+    const pathParts = relativePath.split(sep)
+
+    if (pathParts.some((part) => isIgnored(part, file.isDirectory()))) {
+      continue
+    }
+
+    if (file.isFile()) {
+      const fullPath = join(parentDir, file.name)
+      try {
+        const stats = statSync(fullPath)
+        totalSize += stats.size
+      } catch {
+        // File may have been deleted
+      }
     }
+  }
 
-    return totalSize;
+  return totalSize
 }
 
 /**
- * Deploy a local folder to StaticLaunch
- * @param {string} folder - Path to folder to deploy
- * @param {object} options - Command options
- * @param {string} options.name - Custom subdomain
- * @param {string} options.expires - Expiration time (e.g., "30m", "2h", "1d")
- * @param {boolean} options.verbose - Show verbose error details
+ * Parse and validate expiration option
+ */
+function parseExpiration (expiresOption, verbose) {
+  if (!expiresOption) return null
+
+  try {
+    return calculateExpiresAt(expiresOption)
+  } catch (err) {
+    errorWithSuggestions(
+      err.message,
+      [
+        'Use format like: 30m, 2h, 1d, 7d',
+        'Minimum expiration is 30 minutes',
+        'Examples: --expires 1h, --expires 2d'
+      ],
+      { verbose, cause: err }
+    )
+    process.exit(1)
+    return null // Unreachable, but satisfies static analysis
+  }
+}
+
+/**
+ * Validate required options
+ */
+function validateOptions (options, folderPath, verbose) {
+  if (!options.message) {
+    errorWithSuggestions(
+      'Deployment message is required.',
+      [
+        'Use -m or --message to provide a description',
+        'Example: launchpd deploy . -m "Fix layout"',
+        'Example: launchpd deploy . -m "Initial deployment"'
+      ],
+      { verbose }
+    )
+    process.exit(1)
+  }
+
+  if (!existsSync(folderPath)) {
+    errorWithSuggestions(
+      `Folder not found: ${folderPath}`,
+      [
+        'Check the path is correct',
+        'Use an absolute path or path relative to current directory',
+        `Current directory: ${process.cwd()}`
+      ],
+      { verbose }
+    )
+    process.exit(1)
+  }
+}
+
+/**
+ * Scan folder and return active file count
+ */
+async function scanFolder (folderPath, verbose) {
+  const scanSpinner = spinner('Scanning folder...')
+  const files = await readdir(folderPath, {
+    recursive: true,
+    withFileTypes: true
+  })
+
+  const activeFiles = files.filter((file) => {
+    if (!file.isFile()) return false
+    const parentDir = file.parentPath || file.path
+    const relativePath = relative(folderPath, join(parentDir, file.name))
+    const pathParts = relativePath.split(sep)
+    return !pathParts.some((part) => isIgnored(part, file.isDirectory()))
+  })
+
+  const fileCount = activeFiles.length
+
+  if (fileCount === 0) {
+    scanSpinner.fail('Folder is empty or only contains ignored files')
+    errorWithSuggestions(
+      'Nothing to deploy.',
+      [
+        'Add some files to your folder',
+        'Make sure your files are not in ignored directories (like node_modules)',
+        'Make sure index.html exists for static sites'
+      ],
+      { verbose }
+    )
+    process.exit(1)
+  }
+
+  scanSpinner.succeed(
+    `Found ${fileCount} file(s) (ignored system files skipped)`
+  )
+  return fileCount
+}
+
+/**
+ * Validate static-only files
  */
-export async function deploy(folder, options) {
-    const folderPath = resolve(folder);
-    const verbose = options.verbose || false;
-
-    // Parse expiration if provided
-    let expiresAt = null;
-    if (options.expires) {
-        try {
-            expiresAt = calculateExpiresAt(options.expires);
-        } catch (err) {
-            errorWithSuggestions(err.message, [
-                'Use format like: 30m, 2h, 1d, 7d',
-                'Minimum expiration is 30 minutes',
-                'Examples: --expires 1h, --expires 2d',
-            ], { verbose, cause: err });
-            process.exit(1);
-        }
+async function validateStaticFiles (folderPath, options, verbose) {
+  const validationSpinner = spinner('Validating files...')
+  const validation = await validateStaticOnly(folderPath)
+
+  if (!validation.success) {
+    if (options.force) {
+      validationSpinner.warn(
+        'Static-only validation failed, but proceeding due to --force'
+      )
+      warning('Non-static files detected.')
+      warning(chalk.bold.red('IMPORTANT: Launchpd only hosts STATIC files.'))
+      warning(
+        'Backend code (Node.js, PHP, etc.) will NOT be executed on the server.'
+      )
+    } else {
+      validationSpinner.fail('Deployment blocked: Non-static files detected')
+      const violationList = validation.violations
+        .map((v) => `   - ${v}`)
+        .slice(0, 10)
+      const moreCount =
+        validation.violations.length > 10
+          ? `   - ...and ${validation.violations.length - 10} more`
+          : ''
+      errorWithSuggestions(
+        'Your project contains files that are not allowed.',
+        [
+          'Launchpd only supports static files (HTML, CSS, JS, images, etc.)',
+          'Remove framework files, backend code, and build metadata:',
+          ...violationList,
+          moreCount,
+          'If you use a framework (React, Vue, etc.), deploy the "dist" or "build" folder instead.'
+        ],
+        { verbose }
+      )
+      process.exit(1)
     }
+  } else {
+    validationSpinner.succeed('Project validated (Static files only)')
+  }
+}
 
-    // Validate deployment message is provided
-    if (!options.message) {
-        errorWithSuggestions('Deployment message is required.', [
-            'Use -m or --message to provide a description',
-            'Example: launchpd deploy . -m "Fix layout"',
-            'Example: launchpd deploy . -m "Initial deployment"'
-        ], { verbose });
-        process.exit(1);
+/**
+ * Resolve subdomain from options/config
+ */
+async function resolveSubdomain (options, folderPath, creds, verbose) {
+  if (options.name && !creds?.email) {
+    warning('Custom subdomains require registration!')
+    info('Anonymous deployments use random subdomains.')
+    info('Run "launchpd register" to use --name option.')
+    log('')
+  }
+
+  let subdomain =
+    options.name && creds?.email ? options.name.toLowerCase() : null
+  const projectRoot = findProjectRoot(folderPath)
+  const config = await getProjectConfig(projectRoot)
+  const configSubdomain = config?.subdomain || null
+
+  if (!subdomain) {
+    if (configSubdomain) {
+      subdomain = configSubdomain
+      info(`Using project subdomain: ${chalk.bold(subdomain)}`)
+    } else {
+      subdomain = generateSubdomain()
     }
+  } else if (configSubdomain && subdomain !== configSubdomain) {
+    await handleSubdomainMismatch(
+      subdomain,
+      configSubdomain,
+      options,
+      projectRoot
+    )
+  }
+
+  // Validate subdomain
+  try {
+    subdomain = validateSubdomain(subdomain)
+  } catch (err) {
+    errorWithSuggestions(
+      err.message,
+      [
+        'Subdomain must start and end with alphanumeric characters',
+        'Only lowercase letters, numbers, and hyphens are allowed',
+        'Example: my-site-123'
+      ],
+      { verbose }
+    )
+    process.exit(1)
+  }
+
+  return { subdomain, configSubdomain, projectRoot }
+}
 
-    // Validate folder exists
-    if (!existsSync(folderPath)) {
-        errorWithSuggestions(`Folder not found: ${folderPath}`, [
-            'Check the path is correct',
-            'Use an absolute path or path relative to current directory',
-            `Current directory: ${process.cwd()}`,
-        ], { verbose });
-        process.exit(1);
+/**
+ * Handle subdomain mismatch between CLI arg and config
+ */
+async function handleSubdomainMismatch (
+  subdomain,
+  configSubdomain,
+  options,
+  projectRoot
+) {
+  warning(
+    `Mismatch: This project is linked to ${chalk.bold(configSubdomain)} but you are deploying to ${chalk.bold(subdomain)}`
+  )
+
+  let shouldUpdate = options.yes
+  if (!shouldUpdate) {
+    const confirm = await prompt(
+      `Would you like to update this project's default subdomain to "${subdomain}"? (Y/N): `
+    )
+    shouldUpdate =
+      confirm.toLowerCase() === 'y' || confirm.toLowerCase() === 'yes'
+  }
+
+  if (shouldUpdate) {
+    await updateProjectConfig({ subdomain }, projectRoot)
+    success(`Project configuration updated to: ${subdomain}`)
+  }
+}
+
+/**
+ * Check subdomain availability
+ */
+async function checkSubdomainOwnership (subdomain) {
+  const checkSpinner = spinner('Checking subdomain availability...')
+  try {
+    const isAvailable = await checkSubdomainAvailable(subdomain)
+
+    if (!isAvailable) {
+      const result = await listSubdomains()
+      const owned = result?.subdomains?.some((s) => s.subdomain === subdomain)
+
+      if (owned) {
+        checkSpinner.succeed(
+          `Deploying new version to your subdomain: "${subdomain}"`
+        )
+      } else {
+        checkSpinner.fail(
+          `Subdomain "${subdomain}" is already taken by another user`
+        )
+        warning(
+          'You do not own this subdomain. Please choose a different name.'
+        )
+        process.exit(1)
+      }
+    } else {
+      checkSpinner.succeed(`Subdomain "${subdomain}" is available`)
     }
+  } catch {
+    checkSpinner.warn(
+      'Could not verify subdomain availability (skipping check)'
+    )
+  }
+}
 
-    // Check folder is not empty
-    const scanSpinner = spinner('Scanning folder...');
-    const files = await readdir(folderPath, { recursive: true, withFileTypes: true });
-
-    // Filter out ignored files for the count
-    const activeFiles = files.filter(file => {
-        if (!file.isFile()) return false;
-        const parentDir = file.parentPath || file.path;
-        const relativePath = relative(folderPath, join(parentDir, file.name));
-        const pathParts = relativePath.split(sep);
-        return !pathParts.some(part => isIgnored(part, file.isDirectory()));
-    });
-
-    const fileCount = activeFiles.length;
-
-    if (fileCount === 0) {
-        scanSpinner.fail('Folder is empty or only contains ignored files');
-        errorWithSuggestions('Nothing to deploy.', [
-            'Add some files to your folder',
-            'Make sure your files are not in ignored directories (like node_modules)',
-            'Make sure index.html exists for static sites',
-        ], { verbose });
-        process.exit(1);
+/**
+ * Prompt for auto-init if needed
+ */
+async function promptAutoInit (options, configSubdomain, subdomain, folderPath) {
+  if (options.name && !configSubdomain) {
+    const confirm = await prompt(
+      `\nRun "launchpd init" to link '${folderPath}' to '${subdomain}'? (Y/N): `
+    )
+    if (
+      confirm.toLowerCase() === 'y' ||
+      confirm.toLowerCase() === 'yes' ||
+      confirm === ''
+    ) {
+      await initProjectConfig(subdomain, folderPath)
+      success('Project initialized! Future deploys here can skip --name.')
     }
-    scanSpinner.succeed(`Found ${fileCount} file(s) (ignored system files skipped)`);
-
-    // Static-Only Validation
-    const validationSpinner = spinner('Validating files...');
-    const validation = await validateStaticOnly(folderPath);
-    if (!validation.success) {
-        if (options.force) {
-            validationSpinner.warn('Static-only validation failed, but proceeding due to --force');
-            warning('Non-static files detected.');
-            warning(chalk.bold.red('IMPORTANT: Launchpd only hosts STATIC files.'));
-            warning('Backend code (Node.js, PHP, etc.) will NOT be executed on the server.');
-        } else {
-            validationSpinner.fail('Deployment blocked: Non-static files detected');
-            errorWithSuggestions('Your project contains files that are not allowed.', [
-                'Launchpd only supports static files (HTML, CSS, JS, images, etc.)',
-                'Remove framework files, backend code, and build metadata:',
-                ...validation.violations.map(v => `   - ${v}`).slice(0, 10),
-                validation.violations.length > 10 ? `   - ...and ${validation.violations.length - 10} more` : '',
-                'If you use a framework (React, Vue, etc.), deploy the "dist" or "build" folder instead.',
-            ], { verbose });
-            process.exit(1);
-        }
+  }
+}
+
+/**
+ * Check quota and return result
+ */
+async function checkDeploymentQuota (
+  subdomain,
+  estimatedBytes,
+  configSubdomain,
+  options
+) {
+  const quotaSpinner = spinner('Checking quota...')
+  const isUpdate = configSubdomain && subdomain === configSubdomain
+  const quotaCheck = await checkQuota(subdomain, estimatedBytes, { isUpdate })
+
+  if (!quotaCheck.allowed) {
+    if (options.force) {
+      quotaSpinner.warn(
+        'Deployment blocked due to quota limits, but proceeding due to --force'
+      )
+      warning(
+        'Uploading anyway... (server might still reject if physical limit is hit)'
+      )
     } else {
-        validationSpinner.succeed('Project validated (Static files only)');
+      quotaSpinner.fail('Deployment blocked due to quota limits')
+      info('Try running "launchpd quota" to check your storage.')
+      info('Use --force to try anyway (if you think this is a mistake)')
+      process.exit(1)
     }
+  } else {
+    quotaSpinner.succeed('Quota check passed')
+  }
+
+  displayQuotaWarnings(quotaCheck.warnings)
+}
 
-    // Generate or use provided subdomain
-    // Anonymous users cannot use custom subdomains
-    const creds = await getCredentials();
-    if (options.name && !creds?.email) {
-        warning('Custom subdomains require registration!');
-        info('Anonymous deployments use random subdomains.');
-        info('Run "launchpd register" to use --name option.');
-        log('');
+/**
+ * Perform the actual upload
+ */
+async function performUpload (
+  folderPath,
+  subdomain,
+  fileCount,
+  expiresAt,
+  options
+) {
+  const versionSpinner = spinner('Fetching version info...')
+  let version = await getNextVersionFromAPI(subdomain)
+  if (version === null) {
+    version = await getNextVersion(subdomain)
+  }
+  versionSpinner.succeed(`Deploying as version ${version}`)
+
+  const folderName = basename(folderPath)
+  const uploadSpinner = spinner(`Uploading files... 0/${fileCount}`)
+
+  const { totalBytes } = await uploadFolder(
+    folderPath,
+    subdomain,
+    version,
+    (uploaded, total, fileName) => {
+      uploadSpinner.update(
+        `Uploading files... ${uploaded}/${total} (${fileName})`
+      )
     }
+  )
+
+  uploadSpinner.succeed(
+    `Uploaded ${fileCount} files (${formatBytes(totalBytes)})`
+  )
+
+  const finalizeSpinner = spinner('Finalizing deployment...')
+  await finalizeUpload(
+    subdomain,
+    version,
+    fileCount,
+    totalBytes,
+    folderName,
+    expiresAt?.toISOString() || null,
+    options.message
+  )
+  finalizeSpinner.succeed('Deployment finalized')
+
+  await saveLocalDeployment({
+    subdomain,
+    folderName,
+    fileCount,
+    totalBytes,
+    version,
+    timestamp: new Date().toISOString(),
+    expiresAt: expiresAt?.toISOString() || null
+  })
+
+  return { version, totalBytes }
+}
 
-    // Detect project config if no name provided
-    let subdomain = (options.name && creds?.email) ? options.name.toLowerCase() : null;
-    let configSubdomain = null;
+/**
+ * Show post-deployment info
+ */
+async function showPostDeploymentInfo (url, options, expiresAt, creds, verbose) {
+  if (options.open) {
+    openUrlInBrowser(url)
+  }
 
-    const projectRoot = findProjectRoot(folderPath);
-    const config = await getProjectConfig(projectRoot);
-    if (config?.subdomain) {
-        configSubdomain = config.subdomain;
-    }
+  if (expiresAt) {
+    warning(`Expires: ${formatTimeRemaining(expiresAt)}`)
+  }
+
+  if (!creds?.email) {
+    showAnonymousWarnings()
+  }
+
+  log('')
+
+  if (options.qr) {
+    await showQRCode(url, verbose)
+  }
+}
 
-    if (!subdomain) {
-        if (configSubdomain) {
-            subdomain = configSubdomain;
-            info(`Using project subdomain: ${chalk.bold(subdomain)}`);
-        } else {
-            subdomain = generateSubdomain();
-        }
-    } else if (configSubdomain && subdomain !== configSubdomain) {
-        warning(`Mismatch: This project is linked to ${chalk.bold(configSubdomain)} but you are deploying to ${chalk.bold(subdomain)}`);
-
-        let shouldUpdate = options.yes;
-        if (!shouldUpdate) {
-            const confirm = await prompt(`Would you like to update this project's default subdomain to "${subdomain}"? (Y/N): `);
-            shouldUpdate = (confirm.toLowerCase() === 'y' || confirm.toLowerCase() === 'yes');
-        }
-
-        if (shouldUpdate) {
-            await updateProjectConfig({ subdomain }, projectRoot);
-            success(`Project configuration updated to: ${subdomain}`);
-        }
+/**
+ * Open URL in system browser
+ */
+function openUrlInBrowser (url) {
+  const platform = process.platform
+  let command = 'xdg-open'
+  let args = [url]
+
+  if (platform === 'darwin') {
+    command = 'open'
+  } else if (platform === 'win32') {
+    // Use rundll32 to open the URL with the default browser without invoking a shell
+    command = 'rundll32'
+    args = ['url.dll,FileProtocolHandler', url]
+  }
+
+  execFile(command, args)
+}
+
+/**
+ * Show warnings for anonymous deployments
+ */
+function showAnonymousWarnings () {
+  log('')
+  warning('Anonymous deployment limits:')
+  log('   • 3 active sites per IP')
+  log('   • 50MB total storage')
+  log('   • 7-day site expiration')
+  log('')
+  info(
+    'Run "launchpd register" to unlock unlimited sites and permanent storage!'
+  )
+}
+
+/**
+ * Generate and display QR code
+ */
+async function showQRCode (url, verbose) {
+  try {
+    const terminalWidth = process.stdout.columns || 80
+    const qr = await QRCode.toString(url, {
+      type: 'terminal',
+      small: true,
+      margin: 2,
+      errorCorrectionLevel: 'L'
+    })
+
+    const firstLine = qr.split('\n')[0]
+    if (firstLine.length > terminalWidth) {
+      warning('\nTerminal is too narrow to display the QR code correctly.')
+      info(
+        `Please expand your terminal to at least ${firstLine.length} columns.`
+      )
+      info(`URL: ${url}`)
+    } else {
+      log(`\nScan this QR code to view your site on mobile:\n${qr}`)
     }
+  } catch (err) {
+    warning('Could not generate QR code.')
+    if (verbose) raw(err, 'error')
+  }
+}
 
-    const url = `https://${subdomain}.launchpd.cloud`;
+/**
+ * Handle upload errors with appropriate messages
+ */
+function handleUploadError (err, verbose) {
+  if (
+    handleCommonError(err, {
+      error: (msg) => errorWithSuggestions(msg, [], { verbose }),
+      info,
+      warning
+    })
+  ) {
+    process.exit(1)
+  }
+
+  if (err instanceof MaintenanceError || err.isMaintenanceError) {
+    errorWithSuggestions(
+      '⚠️ LaunchPd is under maintenance',
+      [
+        'Please try again in a few minutes',
+        'Check https://status.launchpd.cloud for updates'
+      ],
+      { verbose }
+    )
+    process.exit(1)
+  }
+
+  if (err instanceof NetworkError || err.isNetworkError) {
+    errorWithSuggestions(
+      'Unable to connect to LaunchPd',
+      [
+        'Check your internet connection',
+        'The API server may be temporarily unavailable',
+        'Check https://status.launchpd.cloud for service status'
+      ],
+      { verbose, cause: err }
+    )
+    process.exit(1)
+  }
+
+  if (err instanceof AuthError || err.isAuthError) {
+    errorWithSuggestions(
+      'Authentication failed',
+      [
+        'Run "launchpd login" to authenticate',
+        'Your API key may have expired or been revoked'
+      ],
+      { verbose, cause: err }
+    )
+    process.exit(1)
+  }
+
+  const suggestions = getErrorSuggestions(err)
+  errorWithSuggestions(`Upload failed: ${err.message}`, suggestions, {
+    verbose,
+    cause: err
+  })
+  process.exit(1)
+}
 
-    // Check subdomain availability and ownership (ALWAYS run this)
-    const checkSpinner = spinner('Checking subdomain availability...');
+/**
+ * Get context-specific suggestions for errors
+ */
+function getErrorSuggestions (err) {
+  const message = err.message || ''
+
+  if (message.includes('fetch failed') || message.includes('ENOTFOUND')) {
+    return [
+      'Check your internet connection',
+      'The API server may be temporarily unavailable'
+    ]
+  }
+
+  if (message.includes('401') || message.includes('Unauthorized')) {
+    return [
+      'Run "launchpd login" to authenticate',
+      'Your API key may have expired'
+    ]
+  }
+
+  if (message.includes('413') || message.includes('too large')) {
+    return [
+      'Try deploying fewer or smaller files',
+      'Check your storage quota with "launchpd quota"'
+    ]
+  }
+
+  if (message.includes('429') || message.includes('rate limit')) {
+    return [
+      'Wait a few minutes and try again',
+      'You may be deploying too frequently'
+    ]
+  }
+
+  return [
+    'Try running with --verbose for more details',
+    'Check https://status.launchpd.cloud for service status'
+  ]
+}
+
+// ============================================================================
+// Main Deploy Function
+// ============================================================================
+
+/**
+ * Deploy a local folder or remote URL to StaticLaunch
+ * @param {string} source - Path to folder, GitHub repo URL, or Gist URL
+ * @param {object} options - Command options
+ * @param {string} options.name - Custom subdomain
+ * @param {string} options.expires - Expiration time (e.g., "30m", "2h", "1d")
+ * @param {boolean} options.verbose - Show verbose error details
+ * @param {string} options.branch - Git branch (for repo URLs)
+ * @param {string} options.dir - Subdirectory within repo to deploy
+ */
+export async function deploy (source, options) {
+  const verbose = options.verbose || false
+  let folderPath = null
+  let tempDir = null
+
+  // Detect remote URL vs local folder
+  if (isRemoteUrl(source)) {
+    const fetchSpinner = spinner('Fetching remote source...')
     try {
-        const isAvailable = await checkSubdomainAvailable(subdomain);
-
-        if (!isAvailable) {
-            // Check if the current user owns it
-            const result = await listSubdomains();
-            const owned = result?.subdomains?.some(s => s.subdomain === subdomain);
-
-            if (owned) {
-                checkSpinner.succeed(`Deploying new version to your subdomain: "${subdomain}"`);
-            } else {
-                checkSpinner.fail(`Subdomain "${subdomain}" is already taken by another user`);
-                warning('You do not own this subdomain. Please choose a different name.');
-                process.exit(1);
-            }
-        } else {
-            // If strictly new, it's available
-            checkSpinner.succeed(`Subdomain "${subdomain}" is available`);
-        }
-    } catch {
-        checkSpinner.warn('Could not verify subdomain availability (skipping check)');
+      const parsed = parseRemoteUrl(source)
+      const sourceLabel =
+        parsed.type === 'gist'
+          ? `Gist (${parsed.gistId})`
+          : `${parsed.owner}/${parsed.repo}`
+      fetchSpinner.update(`Downloading from ${sourceLabel}...`)
+
+      const result = await fetchRemoteSource(parsed, {
+        branch: options.branch,
+        dir: options.dir
+      })
+      tempDir = result.tempDir
+      folderPath = result.folderPath
+      fetchSpinner.succeed(`Downloaded from ${parsed.type}: ${sourceLabel}`)
+    } catch (err) {
+      fetchSpinner.fail('Failed to fetch remote source')
+      errorWithSuggestions(
+        `Remote fetch failed: ${err.message}`,
+        [
+          'Check that the URL is correct and the resource is public',
+          'For repos, verify the branch exists with --branch',
+          'For gists, make sure the gist ID is correct',
+          'Check your internet connection'
+        ],
+        { verbose, cause: err }
+      )
+      process.exit(1)
+      return // Unreachable in production, satisfies test mocks
     }
-
-    // Auto-init: If using --name and no config exists, prompt to save it
-    if (options.name && !configSubdomain) {
-        const confirm = await prompt(`\nRun "launchpd init" to link '${folderPath}' to '${subdomain}'? (Y/N): `);
-        if (confirm.toLowerCase() === 'y' || confirm.toLowerCase() === 'yes' || confirm === '') {
-            await initProjectConfig(subdomain, folderPath);
-            success(`Project initialized! Future deploys here can skip --name.`);
-        }
+  } else {
+    folderPath = resolve(source)
+  }
+
+  try {
+    // Parse and validate
+    const expiresAt = parseExpiration(options.expires, verbose)
+    validateOptions(options, folderPath, verbose)
+
+    // Scan and validate folder
+    const fileCount = await scanFolder(folderPath, verbose)
+    await validateStaticFiles(folderPath, options, verbose)
+
+    // Resolve subdomain
+    const creds = await getCredentials()
+    const { subdomain, configSubdomain } = await resolveSubdomain(
+      options,
+      folderPath,
+      creds,
+      verbose
+    )
+    const url = `https://${subdomain}.launchpd.cloud`
+
+    // Check subdomain availability
+    await checkSubdomainOwnership(subdomain)
+
+    // Auto-init prompt (skip for remote URLs — no local project to init)
+    if (!tempDir) {
+      await promptAutoInit(options, configSubdomain, subdomain, folderPath)
     }
 
-    // Calculate estimated upload size
-    const sizeSpinner = spinner('Calculating folder size...');
-    const estimatedBytes = await calculateFolderSize(folderPath);
-    sizeSpinner.succeed(`Size: ${formatSize(estimatedBytes)}`);
-
-    // Check quota before deploying
-    const quotaSpinner = spinner('Checking quota...');
-    const isUpdate = (configSubdomain && subdomain === configSubdomain);
-
-    const quotaCheck = await checkQuota(subdomain, estimatedBytes, { isUpdate });
-
-    if (!quotaCheck.allowed) {
-        if (options.force) {
-            quotaSpinner.warn('Deployment blocked due to quota limits, but proceeding due to --force');
-            warning('Uploading anyway... (server might still reject if physical limit is hit)');
-        } else {
-            quotaSpinner.fail('Deployment blocked due to quota limits');
-            info('Try running "launchpd quota" to check your storage.');
-            info('Use --force to try anyway (if you think this is a mistake)');
-            process.exit(1);
-        }
-    } else {
-        quotaSpinner.succeed('Quota check passed');
-    }
+    // Calculate size and check quota
+    const sizeSpinner = spinner('Calculating folder size...')
+    const estimatedBytes = await calculateFolderSize(folderPath)
+    sizeSpinner.succeed(`Size: ${formatBytes(estimatedBytes)}`)
 
-    // Display any warnings
-    displayQuotaWarnings(quotaCheck.warnings);
+    await checkDeploymentQuota(
+      subdomain,
+      estimatedBytes,
+      configSubdomain,
+      options
+    )
 
-    // Show current user status (creds already fetched above)
+    // Show deployment info
     if (creds?.email) {
-        info(`Deploying as: ${creds.email}`);
+      info(`Deploying as: ${creds.email}`)
     } else {
-        info('Deploying as: anonymous (run "launchpd login" for more quota)');
+      info('Deploying as: anonymous (run "launchpd login" for more quota)')
     }
+    const sourceLabel = tempDir ? source : folderPath
+    info(`Deploying ${fileCount} file(s) from ${sourceLabel}`)
+    info(`Target: ${url}`)
 
-    info(`Deploying ${fileCount} file(s) from ${folderPath}`);
-    info(`Target: ${url}`);
-
-    // Perform actual upload
+    // Perform upload
     try {
-        // Get next version number for this subdomain (try API first, fallback to local)
-        const versionSpinner = spinner('Fetching version info...');
-        let version = await getNextVersionFromAPI(subdomain);
-        if (version === null) {
-            version = await getNextVersion(subdomain);
-        }
-        versionSpinner.succeed(`Deploying as version ${version}`);
-
-        // Upload all files via API proxy
-        const folderName = basename(folderPath);
-        const uploadSpinner = spinner(`Uploading files... 0/${fileCount}`);
-
-        const { totalBytes } = await uploadFolder(folderPath, subdomain, version, (uploaded, total, fileName) => {
-            uploadSpinner.update(`Uploading files... ${uploaded}/${total} (${fileName})`);
-        });
-
-        uploadSpinner.succeed(`Uploaded ${fileCount} files (${formatSize(totalBytes)})`);
-
-        // Finalize upload: set active version and record metadata
-        const finalizeSpinner = spinner('Finalizing deployment...');
-        await finalizeUpload(
-            subdomain,
-            version,
-            fileCount,
-            totalBytes,
-            folderName,
-            expiresAt?.toISOString() || null,
-            options.message
-        );
-        finalizeSpinner.succeed('Deployment finalized');
-
-        // Save locally for quick access
-        await saveLocalDeployment({
-            subdomain,
-            folderName,
-            fileCount,
-            totalBytes,
-            version,
-            timestamp: new Date().toISOString(),
-            expiresAt: expiresAt?.toISOString() || null,
-        });
-
-        success(`Deployed successfully! (v${version})`);
-        log(`\n${url}`);
-
-        if (options.open) {
-            const platform = process.platform;
-            let cmd;
-            if (platform === 'darwin') cmd = `open "${url}"`;
-            else if (platform === 'win32') cmd = `start "" "${url}"`;
-            else cmd = `xdg-open "${url}"`;
-
-            exec(cmd);
-        }
-
-
-
-        if (expiresAt) {
-            warning(`Expires: ${formatTimeRemaining(expiresAt)}`);
-        }
-
-        // Show anonymous limit warnings
-        if (!creds?.email) {
-            log('');
-            warning('Anonymous deployment limits:');
-            log('   • 3 active sites per IP');
-            log('   • 50MB total storage');
-            log('   • 7-day site expiration');
-            log('');
-            info('Run "launchpd register" to unlock unlimited sites and permanent storage!');
-        }
-        log('');
-
-        if (options.qr) {
-            try {
-                // Determine terminal width to avoid wrapping
-                const terminalWidth = process.stdout.columns || 80;
-
-                // version: 2-3 is typical for these URLs. L level is smallest.
-                // margin: 2 is safe but compact.
-                const qr = await QRCode.toString(url, {
-                    type: 'terminal',
-                    small: true,
-                    margin: 2,
-                    errorCorrectionLevel: 'L'
-                });
-
-                // Check if QR might wrap
-                const firstLine = qr.split('\n')[0];
-                if (firstLine.length > terminalWidth) {
-                    warning('\nTerminal is too narrow to display the QR code correctly.');
-                    info(`Please expand your terminal to at least ${firstLine.length} columns.`);
-                    info(`URL: ${url}`);
-                } else {
-                    log(`\nScan this QR code to view your site on mobile:\n${qr}`);
-                }
-            } catch (err) {
-                warning('Could not generate QR code.');
-                if (verbose) raw(err, 'error');
-            }
-        }
+      const { version } = await performUpload(
+        folderPath,
+        subdomain,
+        fileCount,
+        expiresAt,
+        options
+      )
+      success(`Deployed successfully! (v${version})`)
+      log(`\n${url}`)
+      await showPostDeploymentInfo(url, options, expiresAt, creds, verbose)
     } catch (err) {
-        // Handle common errors with standardized messages
-        if (handleCommonError(err, { error: (msg) => errorWithSuggestions(msg, [], { verbose }), info, warning })) {
-            process.exit(1);
-        }
-
-        // Handle maintenance mode specifically
-        if (err instanceof MaintenanceError || err.isMaintenanceError) {
-            errorWithSuggestions('⚠️ LaunchPd is under maintenance', [
-                'Please try again in a few minutes',
-                'Check https://status.launchpd.cloud for updates',
-            ], { verbose });
-            process.exit(1);
-        }
-
-        // Handle network errors
-        if (err instanceof NetworkError || err.isNetworkError) {
-            errorWithSuggestions('Unable to connect to LaunchPd', [
-                'Check your internet connection',
-                'The API server may be temporarily unavailable',
-                'Check https://status.launchpd.cloud for service status',
-            ], { verbose, cause: err });
-            process.exit(1);
-        }
-
-        // Handle auth errors
-        if (err instanceof AuthError || err.isAuthError) {
-            errorWithSuggestions('Authentication failed', [
-                'Run "launchpd login" to authenticate',
-                'Your API key may have expired or been revoked',
-            ], { verbose, cause: err });
-            process.exit(1);
-        }
-
-        const suggestions = [];
-
-        // Provide context-specific suggestions for other errors
-        if (err.message.includes('fetch failed') || err.message.includes('ENOTFOUND')) {
-            suggestions.push('Check your internet connection');
-            suggestions.push('The API server may be temporarily unavailable');
-        } else if (err.message.includes('401') || err.message.includes('Unauthorized')) {
-            suggestions.push('Run "launchpd login" to authenticate');
-            suggestions.push('Your API key may have expired');
-        } else if (err.message.includes('413') || err.message.includes('too large')) {
-            suggestions.push('Try deploying fewer or smaller files');
-            suggestions.push('Check your storage quota with "launchpd quota"');
-        } else if (err.message.includes('429') || err.message.includes('rate limit')) {
-            suggestions.push('Wait a few minutes and try again');
-            suggestions.push('You may be deploying too frequently');
-        } else {
-            suggestions.push('Try running with --verbose for more details');
-            suggestions.push('Check https://status.launchpd.cloud for service status');
-        }
-
-        errorWithSuggestions(`Upload failed: ${err.message}`, suggestions, { verbose, cause: err });
-        process.exit(1);
+      handleUploadError(err, verbose)
+    }
+  } finally {
+    // Clean up temp directory if we fetched from a remote source
+    if (tempDir) {
+      await cleanupTempDir(tempDir)
     }
+  }
 }