@wyxos/zephyr 0.3.4 → 0.4.1

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.4",
+  "version": "0.4.1",
   "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,4 +1,5 @@
 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'
@@ -241,7 +242,8 @@ function createMaintenanceModePlan({
 async function resolveMaintenanceMode({
                                          snapshot,
                                          remoteIsLaravel,
-                                         runPrompt
+                                         runPrompt,
+                                         executionMode = {}
                                      } = {}) {
     if (!remoteIsLaravel) {
         return false
@@ -251,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
     }
@@ -325,10 +338,43 @@ async function resolveMaintenanceModePlan({
     })
 }
 
+export async function resolveRemoteDeploymentState({
+                                                       snapshot,
+                                                       executionMode = {},
+                                                       ssh,
+                                                       remoteCwd,
+                                                       runPrompt,
+                                                       logSuccess,
+                                                       logWarning
+                                                   } = {}) {
+    const remoteIsLaravel = await detectRemoteLaravelProject(ssh, remoteCwd)
+
+    if (remoteIsLaravel) {
+        logSuccess?.('Laravel project detected.')
+    } else {
+        logWarning?.('Laravel project not detected; skipping Laravel-specific maintenance tasks.')
+    }
+
+    const maintenanceModeEnabled = await resolveMaintenanceMode({
+        snapshot,
+        remoteIsLaravel,
+        runPrompt,
+        executionMode
+    })
+
+    return {
+        remoteIsLaravel,
+        maintenanceModeEnabled
+    }
+}
+
 export async function buildRemoteDeploymentPlan({
                                                     config,
                                                     snapshot = null,
                                                     requiredPhpVersion = null,
+                                                    executionMode = {},
+                                                    remoteIsLaravel = null,
+                                                    maintenanceModeEnabled = null,
                                                     ssh,
                                                     remoteCwd,
                                                     executeRemote,
@@ -337,18 +383,26 @@ export async function buildRemoteDeploymentPlan({
                                                     logWarning,
                                                     runPrompt
                                                 } = {}) {
-    const remoteIsLaravel = await detectRemoteLaravelProject(ssh, remoteCwd)
-
-    if (remoteIsLaravel) {
-        logSuccess?.('Laravel project detected.')
-    } else {
-        logWarning?.('Laravel project not detected; skipping Laravel-specific maintenance tasks.')
-    }
+    const remoteState = typeof remoteIsLaravel === 'boolean' &&
+    (remoteIsLaravel === false || typeof maintenanceModeEnabled === 'boolean')
+        ? {
+            remoteIsLaravel,
+            maintenanceModeEnabled: remoteIsLaravel ? maintenanceModeEnabled : false
+        }
+        : await resolveRemoteDeploymentState({
+            snapshot,
+            executionMode,
+            ssh,
+            remoteCwd,
+            runPrompt,
+            logSuccess,
+            logWarning
+        })
 
     const changedFiles = await collectChangedFiles({
         config,
         snapshot,
-        remoteIsLaravel,
+        remoteIsLaravel: remoteState.remoteIsLaravel,
         executeRemote,
         logProcessing
     })
@@ -356,7 +410,7 @@ export async function buildRemoteDeploymentPlan({
     const horizonConfigured = await detectHorizonConfiguration({
         ssh,
         remoteCwd,
-        remoteIsLaravel,
+        remoteIsLaravel: remoteState.remoteIsLaravel,
         changedFiles
     })
 
@@ -368,17 +422,11 @@ export async function buildRemoteDeploymentPlan({
         logWarning
     })
 
-    const maintenanceModeEnabled = await resolveMaintenanceMode({
-        snapshot,
-        remoteIsLaravel,
-        runPrompt
-    })
-
     const maintenanceModePlan = await resolveMaintenanceModePlan({
         snapshot,
-        remoteIsLaravel,
+        remoteIsLaravel: remoteState.remoteIsLaravel,
         remoteCwd,
-        maintenanceModeEnabled,
+        maintenanceModeEnabled: remoteState.maintenanceModeEnabled,
         phpCommand,
         ssh,
         executeRemote,
@@ -388,7 +436,7 @@ export async function buildRemoteDeploymentPlan({
 
     const steps = planLaravelDeploymentTasks({
         branch: config.branch,
-        isLaravel: remoteIsLaravel,
+        isLaravel: remoteState.remoteIsLaravel,
         changedFiles,
         horizonConfigured,
         phpCommand,
@@ -423,7 +471,7 @@ export async function buildRemoteDeploymentPlan({
     }
 
     return {
-        remoteIsLaravel,
+        remoteIsLaravel: remoteState.remoteIsLaravel,
         changedFiles,
         horizonConfigured,
         phpCommand,

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',