@wyxos/zephyr 0.3.3 → 0.4.0

package/README.md

@@ -43,6 +43,15 @@ zephyr
 # Deploy an app and bump the local npm package version first
 zephyr minor
 
+# Deploy a configured app non-interactively
+zephyr --non-interactive --preset wyxos-release --maintenance off
+
+# Resume a pending non-interactive deployment
+zephyr --non-interactive --preset wyxos-release --resume-pending --maintenance off
+
+# Emit NDJSON events for automation or agent tooling
+zephyr --non-interactive --json --preset wyxos-release --maintenance on
+
 # Release a Node/Vue package (defaults to a patch bump)
 zephyr --type node
 
@@ -55,6 +64,67 @@ zephyr --type packagist patch
 
 When `--type node` or `--type vue` is used without a bump argument, Zephyr defaults to `patch`.
 
+## Interactive and Non-Interactive Modes
+
+Interactive mode remains the default and is the best fit for first-time setup, config repair, and one-off deployments.
+
+Non-interactive mode is strict and is intended for already-configured projects:
+
+- `--non-interactive` fails instead of prompting
+- app deployments require `--preset <name>`
+- Laravel app deployments require `--maintenance on|off` unless resuming a saved snapshot that already contains the choice
+- pending deployment snapshots require either `--resume-pending` or `--discard-pending`
+- stale remote locks are never auto-removed in non-interactive mode
+- `--json` is only supported together with `--non-interactive`
+
+If Zephyr would normally prompt to:
+
+- create or repair config
+- save a preset
+- install the `release` script
+- confirm local path dependency updates
+- resolve a stale remote lock
+
+then non-interactive mode stops immediately with a clear error instead.
+
+## AI Agents and Automation
+
+Zephyr can be used safely by Codex, CI jobs, or other automation once configuration is already in place.
+
+Recommended pattern for app deployments:
+
+```bash
+zephyr --non-interactive --json --preset wyxos-release --maintenance off
+```
+
+Recommended pattern for package releases:
+
+```bash
+zephyr --type node --non-interactive --json minor
+zephyr --type packagist --non-interactive --json patch
+```
+
+In `--json` mode Zephyr emits NDJSON events on `stdout` with a stable shape:
+
+- `run_started`
+- `log`
+- `prompt_required`
+- `run_completed`
+- `run_failed`
+
+Each event includes:
+
+- `event`
+- `timestamp`
+- `workflow`
+- `message`
+- `level` where relevant
+- `data`
+
+`run_failed` also includes a stable `code` field for automation checks.
+
+In `--json` mode, Zephyr reserves `stdout` for NDJSON events and routes inherited local command output to `stderr` so agent parsers do not get corrupted.
+
 On a first run inside a project with `package.json`, Zephyr can:
 - add `.zephyr/` to `.gitignore`
 - add a `release` script that runs `npx @wyxos/zephyr@latest`
@@ -79,6 +149,7 @@ npm run release
 - `npm run release` is the recommended app/package entrypoint once the release script has been installed.
 - For `--type node` workflows, Zephyr runs your project's `lint` script when present.
 - For `--type node` workflows, Zephyr runs `test:run` or `test` when present.
+- For non-interactive app deploys, use a saved preset name instead of relying on prompt fallback.
 
 ## Features
 

package/bin/zephyr.mjs

@@ -1,30 +1,22 @@
 #!/usr/bin/env node
 import process from 'node:process'
-import { Command } from 'commander'
-import chalk from 'chalk'
-import { main } from '../src/main.mjs'
-import { createChalkLogger } from '../src/utils/output.mjs'
 
-const { logError } = createChalkLogger(chalk)
-
-const program = new Command()
-
-program
-  .name('zephyr')
-  .description('A streamlined deployment tool for web applications with intelligent Laravel project detection')
-  .option('--type <type>', 'Workflow type (node|vue|packagist). Omit for normal app deployments.')
-  .argument(
-    '[version]',
-    'Version or npm bump type for deployments (e.g. 1.2.3, patch, minor, major). --type node/vue/packagist workflows accept bump types only and default to patch.'
-  )
-
-program.parse(process.argv)
-const options = program.opts()
-const versionArg = program.args[0] ?? null
+import {parseCliOptions} from '../src/cli/options.mjs'
+import {main} from '../src/main.mjs'
+import {writeStderrLine} from '../src/utils/output.mjs'
 
+let options
 try {
-  await main(options.type ?? null, versionArg)
+    options = parseCliOptions()
 } catch (error) {
-  logError(error?.message || String(error))
-  process.exitCode = 1
+    writeStderrLine(error.message)
+    process.exitCode = 1
+}
+
+if (options) {
+    try {
+        await main(options)
+    } catch {
+        process.exitCode = 1
+    }
 }

package/package.json

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

package/src/application/configuration/select-deployment-target.mjs

@@ -1,22 +1,82 @@
 import {writeStdoutLine} from '../../utils/output.mjs'
 import {loadServers} from '../../config/servers.mjs'
 import {loadProjectConfig, removePreset, saveProjectConfig} from '../../config/project.mjs'
+import {ZephyrError} from '../../runtime/errors.mjs'
+
+function findPresetByName(projectConfig, presetName) {
+    const presets = projectConfig?.presets ?? []
+    return presets.find((entry) => entry?.name === presetName) ?? null
+}
+
+function resolvePresetNonInteractive(projectConfig, servers, preset, presetName) {
+    if (!preset) {
+        throw new ZephyrError(
+            `Zephyr cannot run non-interactively because preset "${presetName}" was not found in .zephyr/config.json.`,
+            {code: 'ZEPHYR_PRESET_NOT_FOUND'}
+        )
+    }
+
+    if (!preset.appId) {
+        throw new ZephyrError(
+            `Zephyr cannot run non-interactively because preset "${preset.name || presetName}" uses a legacy or invalid format. Rerun interactively once to repair .zephyr/config.json.`,
+            {code: 'ZEPHYR_PRESET_REPAIR_REQUIRED'}
+        )
+    }
+
+    const apps = projectConfig?.apps ?? []
+    const appConfig = apps.find((app) => app.id === preset.appId)
+    if (!appConfig) {
+        throw new ZephyrError(
+            `Zephyr cannot run non-interactively because preset "${preset.name || presetName}" references an application that no longer exists.`,
+            {code: 'ZEPHYR_PRESET_INVALID'}
+        )
+    }
+
+    const server = servers.find((entry) => entry.id === appConfig.serverId || entry.serverName === appConfig.serverName)
+    if (!server) {
+        throw new ZephyrError(
+            `Zephyr cannot run non-interactively because preset "${preset.name || presetName}" references a server that no longer exists.`,
+            {code: 'ZEPHYR_PRESET_INVALID'}
+        )
+    }
+
+    return {
+        server,
+        appConfig,
+        branch: preset.branch || appConfig.branch
+    }
+}
 
 export async function selectDeploymentTarget(rootDir, {
     configurationService,
     runPrompt,
     logProcessing,
     logSuccess,
-    logWarning
+    logWarning,
+    emitEvent,
+    executionMode = {}
 } = {}) {
-    const servers = await loadServers({logSuccess, logWarning})
-    const projectConfig = await loadProjectConfig(rootDir, servers, {logSuccess, logWarning})
+    const nonInteractive = executionMode?.interactive === false
+    const servers = await loadServers({
+        logSuccess,
+        logWarning,
+        strict: nonInteractive,
+        allowMigration: !nonInteractive
+    })
+    const projectConfig = await loadProjectConfig(rootDir, servers, {
+        logSuccess,
+        logWarning,
+        strict: nonInteractive,
+        allowMigration: !nonInteractive
+    })
 
     let server = null
     let appConfig = null
     let isCreatingNewPreset = false
 
-    const preset = await configurationService.selectPreset(projectConfig, servers)
+    const preset = nonInteractive
+        ? findPresetByName(projectConfig, executionMode.presetName)
+        : await configurationService.selectPreset(projectConfig, servers)
 
     const removeInvalidPreset = async () => {
         if (!preset || preset === 'create') {
@@ -34,7 +94,15 @@ export async function selectDeploymentTarget(rootDir, {
         isCreatingNewPreset = true
     }
 
-    if (preset === 'create') {
+    if (nonInteractive) {
+        const resolved = resolvePresetNonInteractive(projectConfig, servers, preset, executionMode.presetName)
+        server = resolved.server
+        appConfig = resolved.appConfig
+        appConfig = {
+            ...appConfig,
+            branch: resolved.branch
+        }
+    } else if (preset === 'create') {
         isCreatingNewPreset = true
         server = await configurationService.selectServer(servers)
         appConfig = await configurationService.selectApp(projectConfig, server, rootDir)
@@ -103,7 +171,16 @@ export async function selectDeploymentTarget(rootDir, {
         appConfig = await configurationService.selectApp(projectConfig, server, rootDir)
     }
 
-    const updated = await configurationService.ensureSshDetails(appConfig, rootDir)
+    if (nonInteractive && (!appConfig?.sshUser || !appConfig?.sshKey)) {
+        throw new ZephyrError(
+            `Zephyr cannot run non-interactively because preset "${preset?.name || executionMode.presetName}" is missing SSH details.`,
+            {code: 'ZEPHYR_SSH_DETAILS_REQUIRED'}
+        )
+    }
+
+    const updated = nonInteractive
+        ? false
+        : await configurationService.ensureSshDetails(appConfig, rootDir)
 
     if (updated) {
         await saveProjectConfig(rootDir, projectConfig)
@@ -119,10 +196,18 @@ export async function selectDeploymentTarget(rootDir, {
         sshKey: appConfig.sshKey
     }
 
-    logProcessing?.('\nSelected deployment target:')
-    writeStdoutLine(JSON.stringify(deploymentConfig, null, 2))
+    if (typeof emitEvent === 'function' && executionMode?.json) {
+        emitEvent('log', {
+            level: 'processing',
+            message: 'Selected deployment target.',
+            data: {deploymentConfig}
+        })
+    } else {
+        logProcessing?.('\nSelected deployment target:')
+        writeStdoutLine(JSON.stringify(deploymentConfig, null, 2))
+    }
 
-    if (isCreatingNewPreset || !preset) {
+    if (!nonInteractive && (isCreatingNewPreset || !preset)) {
         const {presetName} = await runPrompt([
             {
                 type: 'input',

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

@@ -1,8 +1,116 @@
 import {findPhpBinary} from '../../infrastructure/php/version.mjs'
+import {ZephyrError} from '../../runtime/errors.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(
@@ -134,7 +242,8 @@ function createMaintenanceModePlan({
 async function resolveMaintenanceMode({
                                          snapshot,
                                          remoteIsLaravel,
-                                         runPrompt
+                                         runPrompt,
+                                         executionMode = {}
                                      } = {}) {
     if (!remoteIsLaravel) {
         return false
@@ -144,6 +253,17 @@ async function resolveMaintenanceMode({
         return snapshot.maintenanceModeEnabled
     }
 
+    if (executionMode?.interactive === false) {
+        if (typeof executionMode.maintenanceMode !== 'boolean') {
+            throw new ZephyrError(
+                'Zephyr cannot run this Laravel deployment non-interactively without an explicit maintenance-mode decision. Pass --maintenance on or --maintenance off.',
+                {code: 'ZEPHYR_MAINTENANCE_FLAG_REQUIRED'}
+            )
+        }
+
+        return executionMode.maintenanceMode
+    }
+
     if (typeof runPrompt !== 'function') {
         return false
     }
@@ -222,6 +342,7 @@ export async function buildRemoteDeploymentPlan({
                                                     config,
                                                     snapshot = null,
                                                     requiredPhpVersion = null,
+                                                    executionMode = {},
                                                     ssh,
                                                     remoteCwd,
                                                     executeRemote,
@@ -264,7 +385,8 @@ export async function buildRemoteDeploymentPlan({
     const maintenanceModeEnabled = await resolveMaintenanceMode({
         snapshot,
         remoteIsLaravel,
-        runPrompt
+        runPrompt,
+        executionMode
     })
 
     const maintenanceModePlan = await resolveMaintenanceModePlan({
@@ -290,6 +412,15 @@ export async function buildRemoteDeploymentPlan({
         maintenanceUpCommand: maintenanceModePlan.upCommand
     })
 
+    await validateLaravelWritablePaths({
+        ssh,
+        remoteCwd,
+        sshUser: config.sshUser,
+        steps,
+        logProcessing,
+        logWarning
+    })
+
     const usefulSteps = steps.length > 1
     const pendingSnapshot = !usefulSteps
         ? null
@@ -320,4 +451,4 @@ export async function buildRemoteDeploymentPlan({
         usefulSteps,
         pendingSnapshot
     }
-}
+}

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

@@ -46,7 +46,7 @@ export async function executeRemoteDeploymentPlan({
                                                       usefulSteps,
                                                       pendingSnapshot = null,
                                                       logProcessing,
-                                                      executionState = null
+                                                      executionState = undefined
                                                   } = {}) {
     if (usefulSteps && pendingSnapshot) {
         await persistPendingSnapshot(rootDir, pendingSnapshot, executeRemote)
@@ -73,4 +73,4 @@ export async function executeRemoteDeploymentPlan({
             await clearPendingTasksSnapshot(rootDir)
         }
     }
-}
+}

package/src/application/deploy/resolve-pending-snapshot.mjs

@@ -1,9 +1,11 @@
 import {clearPendingTasksSnapshot, loadPendingTasksSnapshot} from '../../deploy/snapshots.mjs'
+import {ZephyrError} from '../../runtime/errors.mjs'
 
 export async function resolvePendingSnapshot(rootDir, deploymentConfig, {
     runPrompt,
     logProcessing,
-    logWarning
+    logWarning,
+    executionMode = {}
 } = {}) {
     const existingSnapshot = await loadPendingTasksSnapshot(rootDir)
 
@@ -25,6 +27,24 @@ export async function resolvePendingSnapshot(rootDir, deploymentConfig, {
         messageLines.push(`Tasks: ${existingSnapshot.taskLabels.join(', ')}`)
     }
 
+    if (executionMode?.interactive === false) {
+        if (!executionMode.resumePending && !executionMode.discardPending) {
+            throw new ZephyrError(
+                'Zephyr found a pending deployment snapshot, but non-interactive mode requires either --resume-pending or --discard-pending.',
+                {code: 'ZEPHYR_PENDING_SNAPSHOT_ACTION_REQUIRED'}
+            )
+        }
+
+        if (executionMode.resumePending) {
+            logProcessing?.('Resuming deployment using saved task snapshot...')
+            return existingSnapshot
+        }
+
+        await clearPendingTasksSnapshot(rootDir)
+        logWarning?.('Discarded pending deployment snapshot.')
+        return null
+    }
+
     const {resumePendingTasks} = await runPrompt([
         {
             type: 'confirm',

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

@@ -26,7 +26,9 @@ async function maybeRecoverLaravelMaintenanceMode({
     executionState,
     executeRemote,
     runPrompt,
-    logWarning
+    logProcessing,
+    logWarning,
+    executionMode = {}
 } = {}) {
     if (!remotePlan?.remoteIsLaravel || !remotePlan?.maintenanceModeEnabled) {
         return
@@ -36,12 +38,27 @@ async function maybeRecoverLaravelMaintenanceMode({
         return
     }
 
-    if (typeof runPrompt !== 'function' || typeof executeRemote !== 'function') {
+    if (typeof executeRemote !== 'function') {
         logWarning?.('Deployment failed while Laravel maintenance mode may still be enabled.')
         return
     }
 
     try {
+        if (executionMode?.interactive === false) {
+            logProcessing?.('Deployment failed after Laravel maintenance mode was enabled. Running `artisan up` automatically...')
+            await executeRemote(
+                'Disable Laravel maintenance mode',
+                remotePlan.maintenanceUpCommand ?? `${remotePlan.phpCommand} artisan up`
+            )
+            executionState.exitedMaintenanceMode = true
+            return
+        }
+
+        if (typeof runPrompt !== 'function') {
+            logWarning?.('Deployment failed while Laravel maintenance mode may still be enabled.')
+            return
+        }
+
         const answers = await runPrompt([
             {
                 type: 'confirm',
@@ -82,7 +99,8 @@ export async function runDeployment(config, options = {}) {
         logError,
         runPrompt,
         createSshClient,
-        runCommand
+        runCommand,
+        executionMode
     } = context
 
     await cleanupOldLogs(rootDir)
@@ -126,7 +144,11 @@ export async function runDeployment(config, options = {}) {
         remoteCwd = resolveRemotePath(config.projectPath, remoteHome)
 
         logProcessing('Connection established. Acquiring deployment lock on server...')
-        await acquireRemoteLock(ssh, remoteCwd, rootDir, {runPrompt, logWarning})
+        await acquireRemoteLock(ssh, remoteCwd, rootDir, {
+            runPrompt,
+            logWarning,
+            interactive: executionMode?.interactive !== false
+        })
         lockAcquired = true
         logProcessing(`Lock acquired. Running deployment commands in ${remoteCwd}...`)
 
@@ -145,6 +167,7 @@ export async function runDeployment(config, options = {}) {
             snapshot,
             rootDir,
             requiredPhpVersion,
+            executionMode,
             ssh,
             remoteCwd,
             executeRemote,
@@ -179,12 +202,18 @@ export async function runDeployment(config, options = {}) {
             executionState,
             executeRemote,
             runPrompt,
-            logWarning
+            logProcessing,
+            logWarning,
+            executionMode
         })
 
         if (lockAcquired && ssh && remoteCwd) {
             try {
-                await compareLocksAndPrompt(rootDir, ssh, remoteCwd, {runPrompt, logWarning})
+                await compareLocksAndPrompt(rootDir, ssh, remoteCwd, {
+                    runPrompt,
+                    logWarning,
+                    interactive: executionMode?.interactive !== false
+                })
             } catch {
                 // Ignore lock comparison errors during error handling
             }
@@ -206,4 +235,4 @@ export async function runDeployment(config, options = {}) {
             ssh.dispose()
         }
     }
-}
+}