@wyxos/zephyr 0.3.4 → 0.4.0

package/src/application/release/release-packagist-package.mjs

@@ -8,7 +8,7 @@ import {writeStderr} from '../../utils/output.mjs'
 import {
     ensureCleanWorkingTree,
     ensureReleaseBranchReady,
-    runReleaseCommand as runCommand,
+    runReleaseCommand,
     validateReleaseDependencies
 } from '../../release/shared.mjs'
 
@@ -50,7 +50,13 @@ async function hasArtisan(rootDir = process.cwd()) {
     }
 }
 
-async function runLint(skipLint, rootDir = process.cwd(), {logStep, logSuccess, logWarning} = {}) {
+async function runLint(skipLint, rootDir = process.cwd(), {
+    logStep,
+    logSuccess,
+    logWarning,
+    runCommand = runReleaseCommand,
+    progressWriter = process.stdout
+} = {}) {
     if (skipLint) {
         logWarning?.('Skipping lint because --skip-lint flag was provided.')
         return
@@ -67,9 +73,9 @@ async function runLint(skipLint, rootDir = process.cwd(), {logStep, logSuccess,
 
     let dotInterval = null
     try {
-        process.stdout.write('  ')
+        progressWriter.write('  ')
         dotInterval = setInterval(() => {
-            process.stdout.write('.')
+            progressWriter.write('.')
         }, 200)
 
         await runCommand('php', [pintPath], {capture: true, cwd: rootDir})
@@ -78,14 +84,14 @@ async function runLint(skipLint, rootDir = process.cwd(), {logStep, logSuccess,
             clearInterval(dotInterval)
             dotInterval = null
         }
-        process.stdout.write('\n')
+        progressWriter.write('\n')
         logSuccess?.('Lint passed.')
     } catch (error) {
         if (dotInterval) {
             clearInterval(dotInterval)
             dotInterval = null
         }
-        process.stdout.write('\n')
+        progressWriter.write('\n')
         if (error.stdout) {
             writeStderr(error.stdout)
         }
@@ -96,7 +102,13 @@ async function runLint(skipLint, rootDir = process.cwd(), {logStep, logSuccess,
     }
 }
 
-async function runTests(skipTests, composer, rootDir = process.cwd(), {logStep, logSuccess, logWarning} = {}) {
+async function runTests(skipTests, composer, rootDir = process.cwd(), {
+    logStep,
+    logSuccess,
+    logWarning,
+    runCommand = runReleaseCommand,
+    progressWriter = process.stdout
+} = {}) {
     if (skipTests) {
         logWarning?.('Skipping tests because --skip-tests flag was provided.')
         return
@@ -114,9 +126,9 @@ async function runTests(skipTests, composer, rootDir = process.cwd(), {logStep,
 
     let dotInterval = null
     try {
-        process.stdout.write('  ')
+        progressWriter.write('  ')
         dotInterval = setInterval(() => {
-            process.stdout.write('.')
+            progressWriter.write('.')
         }, 200)
 
         if (hasArtisanFile) {
@@ -129,14 +141,14 @@ async function runTests(skipTests, composer, rootDir = process.cwd(), {logStep,
             clearInterval(dotInterval)
             dotInterval = null
         }
-        process.stdout.write('\n')
+        progressWriter.write('\n')
         logSuccess?.('Tests passed.')
     } catch (error) {
         if (dotInterval) {
             clearInterval(dotInterval)
             dotInterval = null
         }
-        process.stdout.write('\n')
+        progressWriter.write('\n')
         if (error.stdout) {
             writeStderr(error.stdout)
         }
@@ -147,7 +159,11 @@ async function runTests(skipTests, composer, rootDir = process.cwd(), {logStep,
     }
 }
 
-async function bumpVersion(releaseType, rootDir = process.cwd(), {logStep, logSuccess} = {}) {
+async function bumpVersion(releaseType, rootDir = process.cwd(), {
+    logStep,
+    logSuccess,
+    runCommand = runReleaseCommand
+} = {}) {
     logStep?.('Bumping composer version...')
 
     const composer = await readComposer(rootDir)
@@ -179,7 +195,11 @@ async function bumpVersion(releaseType, rootDir = process.cwd(), {logStep, logSu
     return {...composer, version: newVersion}
 }
 
-async function pushChanges(rootDir = process.cwd(), {logStep, logSuccess} = {}) {
+async function pushChanges(rootDir = process.cwd(), {
+    logStep,
+    logSuccess,
+    runCommand = runReleaseCommand
+} = {}) {
     logStep?.('Pushing commits to origin...')
     await runCommand('git', ['push'], {cwd: rootDir})
 
@@ -196,8 +216,19 @@ export async function releasePackagistPackage({
                                                   rootDir = process.cwd(),
                                                   logStep,
                                                   logSuccess,
-                                                  logWarning
+                                                  logWarning,
+                                                  runPrompt,
+                                                  runCommandImpl,
+                                                  runCommandCaptureImpl,
+                                                  interactive = true,
+                                                  progressWriter = process.stdout
                                               } = {}) {
+    const runCommand = (command, args, options = {}) => runReleaseCommand(command, args, {
+        ...options,
+        runCommandImpl,
+        runCommandCaptureImpl
+    })
+
     logStep?.('Reading composer metadata...')
     const composer = await readComposer(rootDir)
 
@@ -206,17 +237,21 @@ export async function releasePackagistPackage({
     }
 
     logStep?.('Validating dependencies...')
-    await validateReleaseDependencies(rootDir, {logSuccess})
+    await validateReleaseDependencies(rootDir, {
+        prompt: runPrompt,
+        logSuccess,
+        interactive
+    })
 
     logStep?.('Checking working tree status...')
     await ensureCleanWorkingTree(rootDir, {runCommand})
     await ensureReleaseBranchReady({rootDir, branchMethod: 'show-current', logStep, logWarning})
 
-    await runLint(skipLint, rootDir, {logStep, logSuccess, logWarning})
-    await runTests(skipTests, composer, rootDir, {logStep, logSuccess, logWarning})
+    await runLint(skipLint, rootDir, {logStep, logSuccess, logWarning, runCommand, progressWriter})
+    await runTests(skipTests, composer, rootDir, {logStep, logSuccess, logWarning, runCommand, progressWriter})
 
-    const updatedComposer = await bumpVersion(releaseType, rootDir, {logStep, logSuccess})
-    await pushChanges(rootDir, {logStep, logSuccess})
+    const updatedComposer = await bumpVersion(releaseType, rootDir, {logStep, logSuccess, runCommand})
+    await pushChanges(rootDir, {logStep, logSuccess, runCommand})
 
     logSuccess?.(`Release workflow completed for ${composer.name}@${updatedComposer.version}.`)
     logStep?.('Note: Packagist will automatically detect the new git tag and update the package.')

package/src/cli/options.mjs

@@ -0,0 +1,122 @@
+import process from 'node:process'
+
+import {Command} from 'commander'
+
+import {InvalidCliOptionsError} from '../runtime/errors.mjs'
+
+const WORKFLOW_TYPES = new Set(['node', 'vue', 'packagist'])
+function normalizeMaintenanceMode(value) {
+    if (value == null) {
+        return null
+    }
+
+    if (value === 'on') {
+        return true
+    }
+
+    if (value === 'off') {
+        return false
+    }
+
+    throw new InvalidCliOptionsError('Invalid value for --maintenance. Use "on" or "off".')
+}
+
+export function parseCliOptions(args = process.argv.slice(2)) {
+    const program = new Command()
+
+    program
+        .allowExcessArguments(false)
+        .allowUnknownOption(false)
+        .exitOverride()
+        .option('--type <type>', 'Workflow type (node|vue|packagist). Omit for normal app deployments.')
+        .option('--non-interactive', 'Fail instead of prompting when Zephyr needs user input.')
+        .option('--json', 'Emit NDJSON events to stdout. Requires --non-interactive.')
+        .option('--preset <name>', 'Preset name to use for non-interactive app deployments.')
+        .option('--resume-pending', 'Resume a saved pending deployment snapshot without prompting.')
+        .option('--discard-pending', 'Discard a saved pending deployment snapshot without prompting.')
+        .option('--maintenance <mode>', 'Laravel maintenance mode policy for non-interactive app deploys (on|off).')
+        .option('--skip-tests', 'Skip test execution in package release workflows.')
+        .option('--skip-lint', 'Skip lint execution in package release workflows.')
+        .option('--skip-build', 'Skip build execution in node/vue release workflows.')
+        .option('--skip-deploy', 'Skip GitHub Pages deployment in node/vue release workflows.')
+        .argument(
+            '[version]',
+            'Version or npm bump type for deployments (e.g. 1.2.3, patch, minor, major).'
+        )
+
+    try {
+        program.parse(args, {from: 'user'})
+    } catch (error) {
+        throw new InvalidCliOptionsError(error.message)
+    }
+
+    const options = program.opts()
+    const workflowType = options.type ?? null
+
+    if (workflowType && !WORKFLOW_TYPES.has(workflowType)) {
+        throw new InvalidCliOptionsError('Invalid value for --type. Use one of: node, vue, packagist.')
+    }
+
+    return {
+        workflowType,
+        versionArg: program.args[0] ?? null,
+        nonInteractive: Boolean(options.nonInteractive),
+        json: Boolean(options.json),
+        presetName: options.preset ?? null,
+        resumePending: Boolean(options.resumePending),
+        discardPending: Boolean(options.discardPending),
+        maintenanceMode: normalizeMaintenanceMode(options.maintenance),
+        skipTests: Boolean(options.skipTests),
+        skipLint: Boolean(options.skipLint),
+        skipBuild: Boolean(options.skipBuild),
+        skipDeploy: Boolean(options.skipDeploy)
+    }
+}
+
+export function validateCliOptions(options = {}) {
+    const {
+        workflowType = null,
+        nonInteractive = false,
+        json = false,
+        presetName = null,
+        resumePending = false,
+        discardPending = false,
+        maintenanceMode = null,
+        skipTests = false,
+        skipLint = false,
+        skipBuild = false,
+        skipDeploy = false
+    } = options
+
+    if (json && !nonInteractive) {
+        throw new InvalidCliOptionsError('--json requires --non-interactive.')
+    }
+
+    if (resumePending && discardPending) {
+        throw new InvalidCliOptionsError('Use either --resume-pending or --discard-pending, not both.')
+    }
+
+    const isPackageRelease = workflowType === 'node' || workflowType === 'vue' || workflowType === 'packagist'
+
+    if (isPackageRelease) {
+        if (presetName) {
+            throw new InvalidCliOptionsError('--preset is only valid for app deployments.')
+        }
+
+        if (resumePending || discardPending) {
+            throw new InvalidCliOptionsError('--resume-pending and --discard-pending are only valid for app deployments.')
+        }
+
+        if (maintenanceMode !== null) {
+            throw new InvalidCliOptionsError('--maintenance is only valid for app deployments.')
+        }
+    } else {
+        if (skipTests || skipLint || skipBuild || skipDeploy) {
+            throw new InvalidCliOptionsError('Release-only skip flags are not valid for app deployments.')
+        }
+
+        if (nonInteractive && !presetName) {
+            throw new InvalidCliOptionsError('--non-interactive app deployments require --preset <name>.')
+        }
+    }
+}

package/src/config/project.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises'
 
+import {ZephyrError} from '../runtime/errors.mjs'
 import { ensureDirectory, getProjectConfigDir, getProjectConfigPath } from '../utils/paths.mjs'
 import { generateId } from '../utils/id.mjs'
 
@@ -69,7 +70,12 @@ export function migratePresets(presets, apps) {
   return { presets: migrated, needsMigration }
 }
 
-export async function loadProjectConfig(rootDir, servers = [], { logSuccess, logWarning } = {}) {
+export async function loadProjectConfig(rootDir, servers = [], {
+  logSuccess,
+  logWarning,
+  strict = false,
+  allowMigration = true
+} = {}) {
   const configPath = getProjectConfigPath(rootDir)
 
   try {
@@ -82,6 +88,13 @@ export async function loadProjectConfig(rootDir, servers = [], { logSuccess, log
     const { presets: migratedPresets, needsMigration: presetsNeedMigration } = migratePresets(presets, migratedApps)
 
     if (appsNeedMigration || presetsNeedMigration) {
+      if (!allowMigration) {
+        throw new ZephyrError(
+          'Zephyr cannot run non-interactively because .zephyr/config.json needs migration. Rerun interactively once to update the config.',
+          {code: 'ZEPHYR_PROJECT_CONFIG_MIGRATION_REQUIRED'}
+        )
+      }
+
       await saveProjectConfig(rootDir, {
         apps: migratedApps,
         presets: migratedPresets
@@ -92,9 +105,27 @@ export async function loadProjectConfig(rootDir, servers = [], { logSuccess, log
     return { apps: migratedApps, presets: migratedPresets }
   } catch (error) {
     if (error.code === 'ENOENT') {
+      if (strict) {
+        throw new ZephyrError(
+          'Zephyr cannot run non-interactively because .zephyr/config.json does not exist. Run an interactive deployment first to create it.',
+          {code: 'ZEPHYR_PROJECT_CONFIG_MISSING'}
+        )
+      }
+
       return { apps: [], presets: [] }
     }
 
+    if (error instanceof ZephyrError) {
+      throw error
+    }
+
+    if (strict) {
+      throw new ZephyrError(
+        'Zephyr cannot run non-interactively because .zephyr/config.json could not be read.',
+        {code: 'ZEPHYR_PROJECT_CONFIG_INVALID', cause: error}
+      )
+    }
+
     logWarning?.('Failed to read .zephyr/config.json, starting with an empty list of apps.')
     return { apps: [], presets: [] }
   }

package/src/config/servers.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 
+import {ZephyrError} from '../runtime/errors.mjs'
 import { ensureDirectory } from '../utils/paths.mjs'
 import { generateId } from '../utils/id.mjs'
 
@@ -25,7 +26,12 @@ export function migrateServers(servers) {
   return { servers: migrated, needsMigration }
 }
 
-export async function loadServers({ logSuccess, logWarning } = {}) {
+export async function loadServers({
+  logSuccess,
+  logWarning,
+  strict = false,
+  allowMigration = true
+} = {}) {
   try {
     const raw = await fs.readFile(SERVERS_FILE, 'utf8')
     const data = JSON.parse(raw)
@@ -34,6 +40,13 @@ export async function loadServers({ logSuccess, logWarning } = {}) {
     const { servers: migrated, needsMigration } = migrateServers(servers)
 
     if (needsMigration) {
+      if (!allowMigration) {
+        throw new ZephyrError(
+          'Zephyr cannot run non-interactively because ~/.config/zephyr/servers.json needs migration. Rerun interactively once to update the config.',
+          {code: 'ZEPHYR_SERVERS_CONFIG_MIGRATION_REQUIRED'}
+        )
+      }
+
       await saveServers(migrated)
       logSuccess?.('Migrated servers configuration to use unique IDs.')
     }
@@ -41,9 +54,27 @@ export async function loadServers({ logSuccess, logWarning } = {}) {
     return migrated
   } catch (error) {
     if (error.code === 'ENOENT') {
+      if (strict) {
+        throw new ZephyrError(
+          'Zephyr cannot run non-interactively because ~/.config/zephyr/servers.json does not exist. Run an interactive deployment first to create it.',
+          {code: 'ZEPHYR_SERVERS_CONFIG_MISSING'}
+        )
+      }
+
       return []
     }
 
+    if (error instanceof ZephyrError) {
+      throw error
+    }
+
+    if (strict) {
+      throw new ZephyrError(
+        'Zephyr cannot run non-interactively because ~/.config/zephyr/servers.json could not be read.',
+        {code: 'ZEPHYR_SERVERS_CONFIG_INVALID', cause: error}
+      )
+    }
+
     logWarning?.('Failed to read servers.json, starting with an empty list.')
     return []
   }
@@ -54,4 +85,3 @@ export async function saveServers(servers) {
   const payload = JSON.stringify(servers, null, 2)
   await fs.writeFile(SERVERS_FILE, `${payload}\n`)
 }
-

package/src/dependency-scanner.mjs

@@ -2,6 +2,7 @@ import { readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import process from 'node:process'
 import chalk from 'chalk'
+import {ZephyrError} from './runtime/errors.mjs'
 import { runCommand as runCommandBase, runCommandCapture as runCommandCaptureBase } from './utils/command.mjs'
 
 function isLocalPathOutsideRepo(depPath, rootDir) {
@@ -262,7 +263,9 @@ async function commitDependencyUpdates(rootDir, updatedFiles, promptFn, logFn) {
   return true
 }
 
-async function validateLocalDependencies(rootDir, promptFn, logFn = null) {
+async function validateLocalDependencies(rootDir, promptFn, logFn = null, {
+  interactive = true
+} = {}) {
   const packageDeps = await scanPackageJsonDependencies(rootDir)
   const composerDeps = await scanComposerJsonDependencies(rootDir)
 
@@ -308,6 +311,13 @@ async function validateLocalDependencies(rootDir, promptFn, logFn = null) {
   const countText = allDeps.length === 1 ? 'dependency' : 'dependencies'
   const promptMessage = `Found ${countColored} local file ${countText} pointing outside the repository:\n\n${messages.join('\n\n')}\n\nUpdate to latest version?`
 
+  if (!interactive) {
+    throw new ZephyrError(
+      'Zephyr cannot run non-interactively because local file dependencies point outside the repository and require confirmation to update.',
+      {code: 'ZEPHYR_DEPENDENCY_UPDATE_REQUIRED'}
+    )
+  }
+
   // Prompt user
   const { shouldUpdate } = await promptFn([
     {

package/src/deploy/locks.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises'
 import os from 'node:os'
 import process from 'node:process'
 
+import {ZephyrError} from '../runtime/errors.mjs'
 import { PROJECT_LOCK_FILE, ensureDirectory, getLockFilePath, getProjectConfigDir } from '../utils/paths.mjs'
 
 function createLockPayload() {
@@ -67,7 +68,26 @@ export async function readRemoteLock(ssh, remoteCwd) {
   return null
 }
 
-export async function compareLocksAndPrompt(rootDir, ssh, remoteCwd, { runPrompt, logWarning } = {}) {
+function parseLockDetails(rawContent = '') {
+  try {
+    return JSON.parse(rawContent.trim())
+  } catch (_error) {
+    return { raw: rawContent.trim() }
+  }
+}
+
+function formatLockHolder(details = {}) {
+  const startedBy = details.user ? `${details.user}@${details.hostname ?? 'unknown'}` : 'unknown user'
+  const startedAt = details.startedAt ? ` at ${details.startedAt}` : ''
+
+  return { startedBy, startedAt }
+}
+
+export async function compareLocksAndPrompt(rootDir, ssh, remoteCwd, {
+  runPrompt,
+  logWarning,
+  interactive = true
+} = {}) {
   const localLock = await readLocalLock(rootDir)
   const remoteLock = await readRemoteLock(ssh, remoteCwd)
 
@@ -79,8 +99,15 @@ export async function compareLocksAndPrompt(rootDir, ssh, remoteCwd, { runPrompt
   const remoteKey = `${remoteLock.user}@${remoteLock.hostname}:${remoteLock.pid}:${remoteLock.startedAt}`
 
   if (localKey === remoteKey) {
-    const startedBy = remoteLock.user ? `${remoteLock.user}@${remoteLock.hostname ?? 'unknown'}` : 'unknown user'
-    const startedAt = remoteLock.startedAt ? ` at ${remoteLock.startedAt}` : ''
+    const { startedBy, startedAt } = formatLockHolder(remoteLock)
+
+    if (!interactive) {
+      throw new ZephyrError(
+        `Stale deployment lock detected on the server (started by ${startedBy}${startedAt}). Remove ${remoteCwd}/.zephyr/${PROJECT_LOCK_FILE} manually before rerunning with --non-interactive.`,
+        {code: 'ZEPHYR_STALE_REMOTE_LOCK'}
+      )
+    }
+
     const { shouldRemove } = await runPrompt([
       {
         type: 'confirm',
@@ -103,7 +130,11 @@ export async function compareLocksAndPrompt(rootDir, ssh, remoteCwd, { runPrompt
   return false
 }
 
-export async function acquireRemoteLock(ssh, remoteCwd, rootDir, { runPrompt, logWarning } = {}) {
+export async function acquireRemoteLock(ssh, remoteCwd, rootDir, {
+  runPrompt,
+  logWarning,
+  interactive = true
+} = {}) {
   const lockPath = `.zephyr/${PROJECT_LOCK_FILE}`
   const escapedLockPath = lockPath.replace(/'/g, "'\\''")
   const checkCommand = `mkdir -p .zephyr && if [ -f '${escapedLockPath}' ]; then cat '${escapedLockPath}'; else echo "LOCK_NOT_FOUND"; fi`
@@ -113,31 +144,17 @@ export async function acquireRemoteLock(ssh, remoteCwd, rootDir, { runPrompt, lo
   if (checkResult.stdout && checkResult.stdout.trim() !== 'LOCK_NOT_FOUND' && checkResult.stdout.trim() !== '') {
     const localLock = await readLocalLock(rootDir)
     if (localLock) {
-      const removed = await compareLocksAndPrompt(rootDir, ssh, remoteCwd, { runPrompt, logWarning })
+      const removed = await compareLocksAndPrompt(rootDir, ssh, remoteCwd, { runPrompt, logWarning, interactive })
       if (!removed) {
-        let details = {}
-        try {
-          details = JSON.parse(checkResult.stdout.trim())
-        } catch (_error) {
-          details = { raw: checkResult.stdout.trim() }
-        }
-
-        const startedBy = details.user ? `${details.user}@${details.hostname ?? 'unknown'}` : 'unknown user'
-        const startedAt = details.startedAt ? ` at ${details.startedAt}` : ''
+        const details = parseLockDetails(checkResult.stdout.trim())
+        const { startedBy, startedAt } = formatLockHolder(details)
         throw new Error(
           `Another deployment is currently in progress on the server (started by ${startedBy}${startedAt}). Remove ${remoteCwd}/${lockPath} if you are sure it is stale.`
         )
       }
     } else {
-      let details = {}
-      try {
-        details = JSON.parse(checkResult.stdout.trim())
-      } catch (_error) {
-        details = { raw: checkResult.stdout.trim() }
-      }
-
-      const startedBy = details.user ? `${details.user}@${details.hostname ?? 'unknown'}` : 'unknown user'
-      const startedAt = details.startedAt ? ` at ${details.startedAt}` : ''
+      const details = parseLockDetails(checkResult.stdout.trim())
+      const { startedBy, startedAt } = formatLockHolder(details)
       throw new Error(
         `Another deployment is currently in progress on the server (started by ${startedBy}${startedAt}). Remove ${remoteCwd}/${lockPath} if you are sure it is stale.`
       )
@@ -168,4 +185,3 @@ export async function releaseRemoteLock(ssh, remoteCwd, { logWarning } = {}) {
     logWarning?.(`Failed to remove lock file: ${result.stderr}`)
   }
 }
-