@wyxos/zephyr 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyxos/zephyr",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "A streamlined deployment tool for web applications with intelligent Laravel project detection",
   "type": "module",
   "main": "./src/index.mjs",

package/src/application/deploy/build-remote-deployment-plan.mjs

@@ -1,6 +1,116 @@
 import {findPhpBinary} from '../../infrastructure/php/version.mjs'
 import {planLaravelDeploymentTasks} from './plan-laravel-deployment-tasks.mjs'
 
+const PRERENDERED_MAINTENANCE_VIEW = 'errors::503'
+const PRERENDERED_MAINTENANCE_FILE = 'resources/views/errors/503.blade.php'
+const LARAVEL_WRITABLE_PATHS = [
+    'bootstrap/cache',
+    'storage/framework/cache',
+    'storage/framework/views',
+    'storage/framework/sessions'
+]
+
+function escapeForSingleQuotes(value) {
+    return value.replace(/'/g, "'\\''")
+}
+
+function isGroupWritable(mode) {
+    if (typeof mode !== 'string' || mode.length < 2) {
+        return false
+    }
+
+    const groupDigit = mode.at(-2)
+    const parsed = Number.parseInt(groupDigit, 8)
+    return Number.isInteger(parsed) && (parsed & 2) === 2
+}
+
+function shouldInspectLaravelWritablePaths(steps = []) {
+    return steps.some((step) => step.label === 'Clear Laravel caches')
+}
+
+async function inspectLaravelWritablePath(ssh, remoteCwd, relativePath) {
+    const escapedPath = escapeForSingleQuotes(relativePath)
+    const command = [
+        `if [ ! -e '${escapedPath}' ]; then`,
+        '  printf "__MISSING__";',
+        'else',
+        `  WRITABLE="no"; [ -w '${escapedPath}' ] && WRITABLE="yes";`,
+        `  OWNER=$(stat -c '%U' '${escapedPath}' 2>/dev/null || printf '?');`,
+        `  GROUP=$(stat -c '%G' '${escapedPath}' 2>/dev/null || printf '?');`,
+        `  MODE=$(stat -c '%a' '${escapedPath}' 2>/dev/null || printf '?');`,
+        '  printf "%s|%s|%s|%s" "$WRITABLE" "$OWNER" "$GROUP" "$MODE";',
+        'fi'
+    ].join(' ')
+
+    const result = await ssh.execCommand(command, {cwd: remoteCwd})
+    const output = result.stdout.trim()
+
+    if (output === '__MISSING__') {
+        return {
+            path: relativePath,
+            exists: false,
+            writable: false,
+            owner: null,
+            group: null,
+            mode: null
+        }
+    }
+
+    const [writableFlag, owner = '?', group = '?', mode = '?'] = output.split('|')
+
+    return {
+        path: relativePath,
+        exists: true,
+        writable: writableFlag === 'yes',
+        owner,
+        group,
+        mode
+    }
+}
+
+async function validateLaravelWritablePaths({
+                                               ssh,
+                                               remoteCwd,
+                                               sshUser,
+                                               steps,
+                                               logProcessing,
+                                               logWarning
+                                           } = {}) {
+    if (!shouldInspectLaravelWritablePaths(steps)) {
+        return
+    }
+
+    logProcessing?.(`Checking Laravel writable directories for deploy user ${sshUser || 'current SSH user'}...`)
+
+    const inspections = []
+    for (const relativePath of LARAVEL_WRITABLE_PATHS) {
+        inspections.push(await inspectLaravelWritablePath(ssh, remoteCwd, relativePath))
+    }
+
+    const blockedPaths = inspections.filter((inspection) => inspection.exists && !inspection.writable)
+    if (blockedPaths.length > 0) {
+        const details = blockedPaths
+            .map((inspection) => ` - ${inspection.path} (owner ${inspection.owner}:${inspection.group}, mode ${inspection.mode})`)
+            .join('\n')
+
+        throw new Error(
+            'Laravel cache-related deployment tasks cannot run because the SSH deploy user cannot write to required directories:\n' +
+            `${details}\n` +
+            'Fix permissions before releasing. Typical fix:\n' +
+            'sudo chown -R $USER:www-data bootstrap/cache storage/framework/cache storage/framework/views storage/framework/sessions\n' +
+            'sudo chmod -R ug+rwX bootstrap/cache storage/framework/cache storage/framework/views storage/framework/sessions'
+        )
+    }
+
+    const riskyPaths = inspections.filter((inspection) => inspection.exists && inspection.writable && !isGroupWritable(inspection.mode))
+    for (const inspection of riskyPaths) {
+        logWarning?.(
+            `${inspection.path} is writable by the deploy user (${inspection.owner}:${inspection.group}, mode ${inspection.mode}), ` +
+            'but it is not group-writable. Web-created cache files may cause later permission drift.'
+        )
+    }
+}
+
 async function detectRemoteLaravelProject(ssh, remoteCwd) {
     const laravelCheck = await ssh.execCommand(
         'if [ -f artisan ] && [ -f composer.json ] && grep -q "laravel/framework" composer.json; then echo "yes"; else echo "no"; fi',
@@ -99,6 +209,122 @@ async function resolvePhpCommand({
     }
 }
 
+function createMaintenanceModePlan({
+                                       enabled,
+                                       phpCommand,
+                                       usesPrerender = false,
+                                       renderView = null
+                                   } = {}) {
+    const maintenanceUpCommand = `${phpCommand} artisan up`
+
+    if (!enabled) {
+        return {
+            enabled: false,
+            usesPrerender: false,
+            renderView: null,
+            downCommand: null,
+            upCommand: maintenanceUpCommand
+        }
+    }
+
+    return {
+        enabled: true,
+        usesPrerender,
+        renderView: usesPrerender ? renderView : null,
+        downCommand: usesPrerender && renderView
+            ? `${phpCommand} artisan down --render="${renderView}"`
+            : `${phpCommand} artisan down`,
+        upCommand: maintenanceUpCommand
+    }
+}
+
+async function resolveMaintenanceMode({
+                                         snapshot,
+                                         remoteIsLaravel,
+                                         runPrompt
+                                     } = {}) {
+    if (!remoteIsLaravel) {
+        return false
+    }
+
+    if (typeof snapshot?.maintenanceModeEnabled === 'boolean') {
+        return snapshot.maintenanceModeEnabled
+    }
+
+    if (typeof runPrompt !== 'function') {
+        return false
+    }
+
+    const answers = await runPrompt([
+        {
+            type: 'confirm',
+            name: 'enableMaintenanceMode',
+            message: 'Enable Laravel maintenance mode for this deployment? (`artisan down` before deploy, `artisan up` after)',
+            default: false
+        }
+    ])
+
+    return Boolean(answers?.enableMaintenanceMode)
+}
+
+async function resolveMaintenanceModePlan({
+                                             snapshot,
+                                             remoteIsLaravel,
+                                             remoteCwd,
+                                             maintenanceModeEnabled,
+                                             phpCommand,
+                                             ssh,
+                                             executeRemote,
+                                             logProcessing,
+                                             logWarning
+                                         } = {}) {
+    if (!remoteIsLaravel || !maintenanceModeEnabled) {
+        return createMaintenanceModePlan({enabled: false, phpCommand})
+    }
+
+    if (typeof snapshot?.maintenanceModeUsesPrerender === 'boolean') {
+        return createMaintenanceModePlan({
+            enabled: true,
+            phpCommand,
+            usesPrerender: snapshot.maintenanceModeUsesPrerender,
+            renderView: snapshot.maintenanceModeRenderView ?? PRERENDERED_MAINTENANCE_VIEW
+        })
+    }
+
+    const capabilityResult = await executeRemote(
+        'Inspect Laravel maintenance mode capabilities',
+        `${phpCommand} artisan down --help`,
+        {printStdout: false, allowFailure: true}
+    )
+    const helpOutput = `${capabilityResult.stdout ?? ''}\n${capabilityResult.stderr ?? ''}`
+    const supportsPrerender = capabilityResult.code === 0 && /(^|\s)--render(?:\[|[=\s]|$)/m.test(helpOutput)
+
+    if (!supportsPrerender) {
+        logProcessing?.('Prerendered Laravel maintenance mode is unavailable on the remote app; using standard maintenance mode.')
+        return createMaintenanceModePlan({enabled: true, phpCommand})
+    }
+
+    const maintenanceViewCheck = await ssh.execCommand(
+        `if [ -f ${PRERENDERED_MAINTENANCE_FILE} ]; then echo "yes"; else echo "no"; fi`,
+        {cwd: remoteCwd}
+    )
+
+    if (maintenanceViewCheck.stdout.trim() !== 'yes') {
+        logWarning?.(
+            `Laravel supports prerendered maintenance mode, but ${PRERENDERED_MAINTENANCE_FILE} is missing; using standard maintenance mode.`
+        )
+        return createMaintenanceModePlan({enabled: true, phpCommand})
+    }
+
+    logProcessing?.(`Using prerendered Laravel maintenance response (${PRERENDERED_MAINTENANCE_VIEW}).`)
+    return createMaintenanceModePlan({
+        enabled: true,
+        phpCommand,
+        usesPrerender: true,
+        renderView: PRERENDERED_MAINTENANCE_VIEW
+    })
+}
+
 export async function buildRemoteDeploymentPlan({
                                                     config,
                                                     snapshot = null,
@@ -108,7 +334,8 @@ export async function buildRemoteDeploymentPlan({
                                                     executeRemote,
                                                     logProcessing,
                                                     logSuccess,
-                                                    logWarning
+                                                    logWarning,
+                                                    runPrompt
                                                 } = {}) {
     const remoteIsLaravel = await detectRemoteLaravelProject(ssh, remoteCwd)
 
@@ -141,12 +368,42 @@ export async function buildRemoteDeploymentPlan({
         logWarning
     })
 
+    const maintenanceModeEnabled = await resolveMaintenanceMode({
+        snapshot,
+        remoteIsLaravel,
+        runPrompt
+    })
+
+    const maintenanceModePlan = await resolveMaintenanceModePlan({
+        snapshot,
+        remoteIsLaravel,
+        remoteCwd,
+        maintenanceModeEnabled,
+        phpCommand,
+        ssh,
+        executeRemote,
+        logProcessing,
+        logWarning
+    })
+
     const steps = planLaravelDeploymentTasks({
         branch: config.branch,
         isLaravel: remoteIsLaravel,
         changedFiles,
         horizonConfigured,
-        phpCommand
+        phpCommand,
+        maintenanceMode: maintenanceModePlan.enabled,
+        maintenanceDownCommand: maintenanceModePlan.downCommand,
+        maintenanceUpCommand: maintenanceModePlan.upCommand
+    })
+
+    await validateLaravelWritablePaths({
+        ssh,
+        remoteCwd,
+        sshUser: config.sshUser,
+        steps,
+        logProcessing,
+        logWarning
     })
 
     const usefulSteps = steps.length > 1
@@ -158,6 +415,9 @@ export async function buildRemoteDeploymentPlan({
         projectPath: config.projectPath,
         sshUser: config.sshUser,
         createdAt: new Date().toISOString(),
+        maintenanceModeEnabled: maintenanceModePlan.enabled,
+        maintenanceModeUsesPrerender: maintenanceModePlan.usesPrerender,
+        maintenanceModeRenderView: maintenanceModePlan.renderView,
         changedFiles,
         taskLabels: steps.map((step) => step.label)
     }
@@ -167,6 +427,11 @@ export async function buildRemoteDeploymentPlan({
         changedFiles,
         horizonConfigured,
         phpCommand,
+        maintenanceModeEnabled: maintenanceModePlan.enabled,
+        maintenanceModeUsesPrerender: maintenanceModePlan.usesPrerender,
+        maintenanceModeRenderView: maintenanceModePlan.renderView,
+        maintenanceDownCommand: maintenanceModePlan.downCommand,
+        maintenanceUpCommand: maintenanceModePlan.upCommand,
         steps,
         usefulSteps,
         pendingSnapshot

package/src/application/deploy/execute-remote-deployment-plan.mjs

@@ -13,17 +13,30 @@ async function persistPendingSnapshot(rootDir, pendingSnapshot, executeRemote) {
 }
 
 function logScheduledTasks(steps, {logProcessing} = {}) {
-    if (steps.length === 1) {
+    const extraTasks = steps
+        .filter((step) => !step.command.startsWith('git pull '))
+        .map((step) => ` - ${step.label}`)
+
+    if (extraTasks.length === 0) {
         logProcessing?.('No additional maintenance tasks scheduled beyond git pull.')
         return
     }
 
-    const extraTasks = steps
-        .slice(1)
-        .map((step) => ` - ${step.label}`)
-        .join('\n')
+    logProcessing?.(`Additional tasks scheduled:\n${extraTasks.join('\n')}`)
+}
 
-    logProcessing?.(`Additional tasks scheduled:\n${extraTasks}`)
+function trackExecutionState(step, executionState) {
+    if (!executionState || !step?.kind) {
+        return
+    }
+
+    if (step.kind === 'maintenance-down') {
+        executionState.enteredMaintenanceMode = true
+    }
+
+    if (step.kind === 'maintenance-up') {
+        executionState.exitedMaintenanceMode = true
+    }
 }
 
 export async function executeRemoteDeploymentPlan({
@@ -32,7 +45,8 @@ export async function executeRemoteDeploymentPlan({
                                                       steps,
                                                       usefulSteps,
                                                       pendingSnapshot = null,
-                                                      logProcessing
+                                                      logProcessing,
+                                                      executionState = null
                                                   } = {}) {
     if (usefulSteps && pendingSnapshot) {
         await persistPendingSnapshot(rootDir, pendingSnapshot, executeRemote)
@@ -45,6 +59,7 @@ export async function executeRemoteDeploymentPlan({
     try {
         for (const step of steps) {
             await executeRemote(step.label, step.command)
+            trackExecutionState(step, executionState)
         }
 
         completed = true
@@ -58,4 +73,4 @@ export async function executeRemoteDeploymentPlan({
             await clearPendingTasksSnapshot(rootDir)
         }
     }
-}
+}

package/src/application/deploy/plan-laravel-deployment-tasks.mjs

@@ -3,7 +3,10 @@ export function planLaravelDeploymentTasks({
   isLaravel,
   changedFiles,
   horizonConfigured = false,
-  phpCommand = 'php'
+  phpCommand = 'php',
+  maintenanceMode = false,
+  maintenanceDownCommand = null,
+  maintenanceUpCommand = null
 }) {
   const safeChangedFiles = Array.isArray(changedFiles) ? changedFiles : []
 
@@ -43,12 +46,20 @@ export function planLaravelDeploymentTasks({
   const shouldClearCaches = hasPhpChanges
   const shouldRestartQueues = hasPhpChanges
 
-  const steps = [
-    {
-      label: `Pull latest changes for ${branch}`,
-      command: `git pull origin ${branch}`
-    }
-  ]
+  const steps = []
+
+  if (maintenanceMode && isLaravel) {
+    steps.push({
+      label: 'Enable Laravel maintenance mode',
+      command: maintenanceDownCommand ?? `${phpCommand} artisan down`,
+      kind: 'maintenance-down'
+    })
+  }
+
+  steps.push({
+    label: `Pull latest changes for ${branch}`,
+    command: `git pull origin ${branch}`
+  })
 
   if (shouldRunComposer) {
     // Composer is a PHP script, so we need to run it with the correct PHP version
@@ -96,5 +107,13 @@ export function planLaravelDeploymentTasks({
     })
   }
 
+  if (maintenanceMode && isLaravel) {
+    steps.push({
+      label: 'Disable Laravel maintenance mode',
+      command: maintenanceUpCommand ?? `${phpCommand} artisan up`,
+      kind: 'maintenance-up'
+    })
+  }
+
   return steps
-}
+}

package/src/application/deploy/prepare-local-deployment.mjs

@@ -3,7 +3,7 @@ import process from 'node:process'
 import {ensureLocalRepositoryState} from '../../deploy/local-repo.mjs'
 import {bumpLocalPackageVersion} from './bump-local-package-version.mjs'
 import {resolveLocalDeploymentContext} from './resolve-local-deployment-context.mjs'
-import {runLocalDeploymentChecks} from './run-local-deployment-checks.mjs'
+import {resolveLocalDeploymentCheckSupport, runLocalDeploymentChecks} from './run-local-deployment-checks.mjs'
 
 export async function prepareLocalDeployment(config, {
     snapshot = null,
@@ -17,6 +17,11 @@ export async function prepareLocalDeployment(config, {
     logWarning
 } = {}) {
     const context = await resolveLocalDeploymentContext(rootDir)
+    const checkSupport = await resolveLocalDeploymentCheckSupport({
+        rootDir,
+        isLaravel: context.isLaravel,
+        runCommandCapture
+    })
 
     if (!snapshot && context.isLaravel) {
         await bumpLocalPackageVersion(rootDir, {
@@ -45,7 +50,9 @@ export async function prepareLocalDeployment(config, {
         runCommandCapture,
         logProcessing,
         logSuccess,
-        logWarning
+        logWarning,
+        lintCommand: checkSupport.lintCommand,
+        testCommand: checkSupport.testCommand
     })
 
     return context

package/src/application/deploy/run-deployment.mjs

@@ -21,6 +21,52 @@ async function resolveRemoteHome(ssh, sshUser) {
     return remoteHomeResult.stdout.trim() || `/home/${sshUser}`
 }
 
+async function maybeRecoverLaravelMaintenanceMode({
+    remotePlan,
+    executionState,
+    executeRemote,
+    runPrompt,
+    logWarning
+} = {}) {
+    if (!remotePlan?.remoteIsLaravel || !remotePlan?.maintenanceModeEnabled) {
+        return
+    }
+
+    if (!executionState?.enteredMaintenanceMode || executionState.exitedMaintenanceMode) {
+        return
+    }
+
+    if (typeof runPrompt !== 'function' || typeof executeRemote !== 'function') {
+        logWarning?.('Deployment failed while Laravel maintenance mode may still be enabled.')
+        return
+    }
+
+    try {
+        const answers = await runPrompt([
+            {
+                type: 'confirm',
+                name: 'disableMaintenanceMode',
+                message: 'Deployment failed after Laravel maintenance mode was enabled. Run `artisan up` now?',
+                default: true
+            }
+        ])
+        const disableMaintenanceMode = answers?.disableMaintenanceMode === true
+
+        if (!disableMaintenanceMode) {
+            logWarning?.('Laravel maintenance mode remains enabled because recovery was not confirmed.')
+            return
+        }
+
+        await executeRemote(
+            'Disable Laravel maintenance mode',
+            remotePlan.maintenanceUpCommand ?? `${remotePlan.phpCommand} artisan up`
+        )
+        executionState.exitedMaintenanceMode = true
+    } catch (error) {
+        logWarning?.(`Failed to disable Laravel maintenance mode after deployment error: ${error.message}`)
+    }
+}
+
 export async function runDeployment(config, options = {}) {
     const {
         snapshot = null,
@@ -58,6 +104,12 @@ export async function runDeployment(config, options = {}) {
     const privateKeyPath = await resolveSshKeyPath(config.sshKey)
     const privateKey = await fs.readFile(privateKeyPath, 'utf8')
     let remoteCwd = null
+    let executeRemote = null
+    let remotePlan = null
+    const executionState = {
+        enteredMaintenanceMode: false,
+        exitedMaintenanceMode: false
+    }
 
     logProcessing(`\nConnecting to ${config.serverIp} as ${sshUser}...`)
 
@@ -78,7 +130,7 @@ export async function runDeployment(config, options = {}) {
         lockAcquired = true
         logProcessing(`Lock acquired. Running deployment commands in ${remoteCwd}...`)
 
-        const executeRemote = createRemoteExecutor({
+        executeRemote = createRemoteExecutor({
             ssh,
             rootDir,
             remoteCwd,
@@ -88,7 +140,7 @@ export async function runDeployment(config, options = {}) {
             logError
         })
 
-        const remotePlan = await buildRemoteDeploymentPlan({
+        remotePlan = await buildRemoteDeploymentPlan({
             config,
             snapshot,
             rootDir,
@@ -96,6 +148,7 @@ export async function runDeployment(config, options = {}) {
             ssh,
             remoteCwd,
             executeRemote,
+            runPrompt,
             logProcessing,
             logSuccess,
             logWarning
@@ -107,7 +160,8 @@ export async function runDeployment(config, options = {}) {
             steps: remotePlan.steps,
             usefulSteps: remotePlan.usefulSteps,
             pendingSnapshot: remotePlan.pendingSnapshot,
-            logProcessing
+            logProcessing,
+            executionState
         })
 
         logSuccess('\nDeployment commands completed successfully.')
@@ -120,6 +174,14 @@ export async function runDeployment(config, options = {}) {
             logError(`\nTask output has been logged to: ${logPath}`)
         }
 
+        await maybeRecoverLaravelMaintenanceMode({
+            remotePlan,
+            executionState,
+            executeRemote,
+            runPrompt,
+            logWarning
+        })
+
         if (lockAcquired && ssh && remoteCwd) {
             try {
                 await compareLocksAndPrompt(rootDir, ssh, remoteCwd, {runPrompt, logWarning})
@@ -144,4 +206,4 @@ export async function runDeployment(config, options = {}) {
             ssh.dispose()
         }
     }
-}
+}

package/src/application/deploy/run-local-deployment-checks.mjs

@@ -12,20 +12,62 @@ async function hasUncommittedChanges(rootDir, {runCommandCapture} = {}) {
     })
 }
 
-async function runLocalLaravelTests(rootDir, {runCommand, logProcessing, logSuccess, logWarning} = {}) {
+function supportsArtisanTestCommand(listOutput = '') {
+    return /(?:^|\n)\s*test(?:\s|$)/m.test(listOutput)
+}
+
+async function resolveSupportedLaravelTestCommand(rootDir, {runCommandCapture} = {}) {
     if (!commandExists('php')) {
-        logWarning?.(
-            'PHP is not available in PATH. Skipping local Laravel tests.\n' +
-            '  To run tests locally, ensure PHP is installed and added to your PATH.\n' +
-            '  On Windows with Laravel Herd, you may need to add Herd\'s PHP to your system PATH.'
+        throw new Error(
+            'Release cannot run because PHP is not available in PATH.\n' +
+            'Zephyr requires `php artisan test --compact` for Laravel projects before deployment.'
+        )
+    }
+
+    let artisanCommands
+    try {
+        artisanCommands = await runCommandCapture('php', ['artisan', 'list'], {cwd: rootDir})
+    } catch (error) {
+        throw new Error(
+            'Release cannot run because Zephyr could not verify support for `php artisan test`.\n' +
+            `Ensure the project can run \`php artisan list\` locally before deployment.\n${error.message}`
+        )
+    }
+
+    if (!supportsArtisanTestCommand(artisanCommands)) {
+        throw new Error(
+            'Release cannot run because this Laravel project does not support `php artisan test`.\n' +
+            'Zephyr requires Laravel\'s built-in test command before deployment. PHPUnit-only test setups are not supported.'
         )
-        return
     }
 
+    return {
+        command: 'php',
+        args: ['artisan', 'test', '--compact']
+    }
+}
+
+export async function resolveLocalDeploymentCheckSupport({
+    rootDir,
+    isLaravel,
+    runCommandCapture
+} = {}) {
+    const lintCommand = await preflight.resolveSupportedLintCommand(rootDir, {commandExists})
+    const testCommand = isLaravel
+        ? await resolveSupportedLaravelTestCommand(rootDir, {runCommandCapture})
+        : null
+
+    return {
+        lintCommand,
+        testCommand
+    }
+}
+
+async function runLocalLaravelTests(rootDir, {runCommand, logProcessing, logSuccess, testCommand} = {}) {
     logProcessing?.('Running Laravel tests locally...')
 
     try {
-        await runCommand('php', ['artisan', 'test', '--compact'], {cwd: rootDir})
+        await runCommand(testCommand.command, testCommand.args, {cwd: rootDir})
         logSuccess?.('Local tests passed.')
     } catch (error) {
         if (error.code === 'ENOENT') {
@@ -47,10 +89,22 @@ export async function runLocalDeploymentChecks({
     runCommandCapture,
     logProcessing,
     logSuccess,
-    logWarning
+    logWarning,
+    lintCommand = undefined,
+    testCommand = undefined
 } = {}) {
+    const support = lintCommand !== undefined || testCommand !== undefined
+        ? {lintCommand, testCommand}
+        : await resolveLocalDeploymentCheckSupport({
+            rootDir,
+            isLaravel,
+            runCommandCapture
+        })
+
     if (hasHook) {
-        logProcessing?.('Pre-push git hook detected. Skipping local linting and test execution.')
+        logProcessing?.(
+            'Pre-push git hook detected. Built-in release checks are supported, but Zephyr will skip executing them here. If Zephyr pushes local commits during this release, the hook will run during git push.'
+        )
         return
     }
 
@@ -59,7 +113,8 @@ export async function runLocalDeploymentChecks({
         logProcessing,
         logSuccess,
         logWarning,
-        commandExists
+        commandExists,
+        lintCommand: support.lintCommand
     })
 
     if (lintRan) {
@@ -75,6 +130,11 @@ export async function runLocalDeploymentChecks({
     }
 
     if (isLaravel) {
-        await runLocalLaravelTests(rootDir, {runCommand, logProcessing, logSuccess, logWarning})
+        await runLocalLaravelTests(rootDir, {
+            runCommand,
+            logProcessing,
+            logSuccess,
+            testCommand: support.testCommand
+        })
     }
 }

package/src/deploy/local-repo.mjs

@@ -1,4 +1,5 @@
 import { getCurrentBranch as getCurrentBranchImpl, getUpstreamRef as getUpstreamRefImpl } from '../utils/git.mjs'
+import {hasPrePushHook} from './preflight.mjs'
 
 export async function getCurrentBranch(rootDir) {
   const branch = await getCurrentBranchImpl(rootDir)
@@ -179,7 +180,22 @@ async function commitAndPushStagedChanges(targetBranch, rootDir, {
 
   logProcessing?.('Committing staged changes before deployment...')
   await runCommand('git', ['commit', '-m', message], { cwd: rootDir })
-  await runCommand('git', ['push', 'origin', targetBranch], { cwd: rootDir })
+
+  const prePushHookPresent = await hasPrePushHook(rootDir)
+  if (prePushHookPresent) {
+    logProcessing?.('Pre-push git hook detected. Running hook during git push...')
+  }
+
+  try {
+    await runCommand('git', ['push', 'origin', targetBranch], { cwd: rootDir })
+  } catch (error) {
+    if (prePushHookPresent) {
+      throw new Error(`Git push failed while the pre-push hook was running. See hook output above.\n${error.message}`)
+    }
+
+    throw error
+  }
+
   logSuccess?.(`Committed and pushed changes to origin/${targetBranch}.`)
 
   const finalStatus = await getGitStatus(rootDir)
@@ -195,14 +211,17 @@ export async function ensureCommittedChangesPushed(targetBranch, rootDir, {
   logProcessing,
   logSuccess,
   logWarning,
-  getUpstreamRef: getUpstreamRefFn = getUpstreamRef
+  getUpstreamRef: getUpstreamRefFn = getUpstreamRef,
+  readUpstreamSyncState: readUpstreamSyncStateFn = (branch, dir) =>
+    readUpstreamSyncState(branch, dir, {
+      runCommand,
+      runCommandCapture,
+      logWarning,
+      getUpstreamRef: getUpstreamRefFn
+    }),
+  hasPrePushHook: hasPrePushHookFn = hasPrePushHook
 } = {}) {
-  const syncState = await readUpstreamSyncState(targetBranch, rootDir, {
-    runCommand,
-    runCommandCapture,
-    logWarning,
-    getUpstreamRef: getUpstreamRefFn
-  })
+  const syncState = await readUpstreamSyncStateFn(targetBranch, rootDir)
 
   const {
     upstreamRef,
@@ -234,8 +253,31 @@ export async function ensureCommittedChangesPushed(targetBranch, rootDir, {
 
   const commitLabel = aheadCount === 1 ? 'commit' : 'commits'
   logProcessing?.(`Found ${aheadCount} ${commitLabel} not yet pushed to ${upstreamRef}. Pushing before deployment...`)
+  const prePushHookPresent = await hasPrePushHookFn(rootDir)
+
+  if (prePushHookPresent) {
+    logProcessing?.('Pre-push git hook detected. Running hook during git push...')
+  }
+
+  try {
+    await runCommandCapture('git', ['push', remoteName, `${targetBranch}:${upstreamBranch}`], { cwd: rootDir })
+  } catch (error) {
+    if (prePushHookPresent) {
+      const hookOutput = [error.stdout, error.stderr]
+        .map((value) => (typeof value === 'string' ? value.trim() : ''))
+        .filter(Boolean)
+        .join('\n')
+
+      throw new Error(
+        hookOutput
+          ? `Git push failed while the pre-push hook was running.\n${hookOutput}`
+          : `Git push failed while the pre-push hook was running.\n${error.message}`
+      )
+    }
+
+    throw error
+  }
 
-  await runCommandCapture('git', ['push', remoteName, `${targetBranch}:${upstreamBranch}`], { cwd: rootDir })
   logSuccess?.(`Pushed committed changes to ${upstreamRef}.`)
 
   return { pushed: true, upstreamRef }

package/src/deploy/preflight.mjs

@@ -45,29 +45,67 @@ export async function hasLaravelPint(rootDir) {
   }
 }
 
-export async function runLinting(rootDir, { runCommand, logProcessing, logSuccess, logWarning, commandExists } = {}) {
+export async function resolveSupportedLintCommand(rootDir, {commandExists} = {}) {
   const hasNpmLint = await hasLintScript(rootDir)
   const hasPint = await hasLaravelPint(rootDir)
 
   if (hasNpmLint) {
-    logProcessing?.('Running npm lint...')
-    await runCommand('npm', ['run', 'lint'], { cwd: rootDir })
-    logSuccess?.('Linting completed.')
-    return true
+    if (commandExists && !commandExists('npm')) {
+      throw new Error(
+        'Release cannot run because `npm run lint` is configured but npm is not available in PATH.\n' +
+        'Install npm or fix your PATH before releasing.'
+      )
+    }
+
+    return {
+      type: 'npm',
+      command: 'npm',
+      args: ['run', 'lint'],
+      label: 'npm lint'
+    }
   }
 
   if (hasPint) {
-    // Check if PHP is available before trying to run Pint
     if (commandExists && !commandExists('php')) {
-      logWarning?.(
-        'PHP is not available in PATH. Skipping Laravel Pint.\n' +
-        '  To run Pint locally, ensure PHP is installed and added to your PATH.'
+      throw new Error(
+        'Release cannot run because Laravel Pint is present but PHP is not available in PATH.\n' +
+        'Zephyr requires `php vendor/bin/pint` to run successfully before deployment.'
       )
-      return false
     }
 
+    return {
+      type: 'pint',
+      command: 'php',
+      args: ['vendor/bin/pint'],
+      label: 'Laravel Pint'
+    }
+  }
+
+  throw new Error(
+    'Release cannot run because no supported lint command was found.\n' +
+    'Zephyr requires either `npm run lint` or Laravel Pint (`vendor/bin/pint`) before deployment.'
+  )
+}
+
+export async function runLinting(rootDir, {
+  runCommand,
+  logProcessing,
+  logSuccess,
+  commandExists,
+  lintCommand = null
+} = {}) {
+  const selectedLintCommand = lintCommand ?? await resolveSupportedLintCommand(rootDir, {commandExists})
+
+  if (selectedLintCommand.type === 'npm') {
+    logProcessing?.('Running npm lint...')
+    await runCommand(selectedLintCommand.command, selectedLintCommand.args, { cwd: rootDir })
+    logSuccess?.('Linting completed.')
+    return true
+  }
+
+  if (selectedLintCommand.type === 'pint') {
     logProcessing?.('Running Laravel Pint...')
-    await runCommand('php', ['vendor/bin/pint'], { cwd: rootDir })
+    await runCommand(selectedLintCommand.command, selectedLintCommand.args, { cwd: rootDir })
     logSuccess?.('Linting completed.')
     return true
   }
@@ -123,4 +161,3 @@ export async function isLocalLaravelProject(rootDir) {
     return false
   }
 }
-

package/src/main.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises'
+import {createRequire} from 'node:module'
 import path from 'node:path'
 import process from 'node:process'
 
@@ -16,6 +17,8 @@ import {runDeployment} from './application/deploy/run-deployment.mjs'
 
 const RELEASE_SCRIPT_NAME = 'release'
 const RELEASE_SCRIPT_COMMAND = 'npx @wyxos/zephyr@latest'
+const require = createRequire(import.meta.url)
+const {version: ZEPHYR_VERSION} = require('../package.json')
 
 const appContext = createAppContext()
 const {
@@ -36,6 +39,8 @@ async function runRemoteTasks(config, options = {}) {
 }
 
 async function main(releaseType = null, versionArg = null) {
+    logProcessing(`Zephyr v${ZEPHYR_VERSION}`)
+
     if (releaseType === 'node' || releaseType === 'vue') {
         try {
             await releaseNode()