@wyxos/zephyr 0.3.4 → 0.4.0

package/src/main.mjs

@@ -3,10 +3,12 @@ import {createRequire} from 'node:module'
 import path from 'node:path'
 import process from 'node:process'
 
+import {validateCliOptions} from './cli/options.mjs'
 import {releaseNode} from './release-node.mjs'
 import {releasePackagist} from './release-packagist.mjs'
 import {validateLocalDependencies} from './dependency-scanner.mjs'
 import * as bootstrap from './project/bootstrap.mjs'
+import {getErrorCode} from './runtime/errors.mjs'
 import {PROJECT_CONFIG_DIR} from './utils/paths.mjs'
 import {writeStderrLine} from './utils/output.mjs'
 import {createAppContext} from './runtime/app-context.mjs'
@@ -20,97 +22,223 @@ 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 {
-    logProcessing,
-    logSuccess,
-    logWarning,
-    logError,
-    runPrompt,
-    runCommand
-} = appContext
-const configurationService = createConfigurationService(appContext)
+function normalizeMainOptions(firstArg = null, secondArg = null) {
+    if (firstArg && typeof firstArg === 'object' && !Array.isArray(firstArg)) {
+        return {
+            workflowType: firstArg.workflowType ?? firstArg.type ?? null,
+            versionArg: firstArg.versionArg ?? null,
+            nonInteractive: firstArg.nonInteractive === true,
+            json: firstArg.json === true,
+            presetName: firstArg.presetName ?? null,
+            resumePending: firstArg.resumePending === true,
+            discardPending: firstArg.discardPending === true,
+            maintenanceMode: firstArg.maintenanceMode ?? null,
+            skipTests: firstArg.skipTests === true,
+            skipLint: firstArg.skipLint === true,
+            skipBuild: firstArg.skipBuild === true,
+            skipDeploy: firstArg.skipDeploy === true,
+            context: firstArg.context ?? null
+        }
+    }
+
+    return {
+        workflowType: firstArg ?? null,
+        versionArg: secondArg ?? null,
+        nonInteractive: false,
+        json: false,
+        presetName: null,
+        resumePending: false,
+        discardPending: false,
+        maintenanceMode: null,
+        skipTests: false,
+        skipLint: false,
+        skipBuild: false,
+        skipDeploy: false,
+        context: null
+    }
+}
+
+function resolveWorkflowName(workflowType = null) {
+    if (workflowType === 'node' || workflowType === 'vue') {
+        return `release-${workflowType}`
+    }
+
+    if (workflowType === 'packagist') {
+        return 'release-packagist'
+    }
+
+    return 'deploy'
+}
 
 async function runRemoteTasks(config, options = {}) {
     return await runDeployment(config, {
         ...options,
-        context: options.context ?? appContext
+        context: options.context
     })
 }
 
-async function main(releaseType = null, versionArg = null) {
-    logProcessing(`Zephyr v${ZEPHYR_VERSION}`)
+async function main(optionsOrWorkflowType = null, versionArg = null) {
+    const options = normalizeMainOptions(optionsOrWorkflowType, versionArg)
+
+    const executionMode = {
+        interactive: !options.nonInteractive,
+        json: options.json === true && options.nonInteractive === true,
+        workflow: resolveWorkflowName(options.workflowType),
+        presetName: options.presetName,
+        maintenanceMode: options.maintenanceMode,
+        resumePending: options.resumePending,
+        discardPending: options.discardPending
+    }
+    const appContext = options.context ?? createAppContext({executionMode})
+    const {
+        logProcessing,
+        logSuccess,
+        logWarning,
+        logError,
+        runPrompt,
+        runCommand,
+        emitEvent
+    } = appContext
+    const currentExecutionMode = appContext.executionMode ?? executionMode
+    const configurationService = createConfigurationService(appContext)
+
+    try {
+        validateCliOptions(options)
+
+        if (currentExecutionMode.json) {
+            emitEvent?.('run_started', {
+                message: `Zephyr v${ZEPHYR_VERSION} starting`,
+                data: {
+                    version: ZEPHYR_VERSION,
+                    workflow: currentExecutionMode.workflow,
+                    nonInteractive: currentExecutionMode.interactive === false,
+                    presetName: currentExecutionMode.presetName,
+                    maintenanceMode: currentExecutionMode.maintenanceMode,
+                    resumePending: currentExecutionMode.resumePending,
+                    discardPending: currentExecutionMode.discardPending
+                }
+            })
+        } else {
+            logProcessing(`Zephyr v${ZEPHYR_VERSION}`)
+        }
 
-    if (releaseType === 'node' || releaseType === 'vue') {
-        try {
-            await releaseNode()
+        if (options.workflowType === 'node' || options.workflowType === 'vue') {
+            await releaseNode({
+                releaseType: options.versionArg,
+                skipTests: options.skipTests,
+                skipLint: options.skipLint,
+                skipBuild: options.skipBuild,
+                skipDeploy: options.skipDeploy,
+                context: appContext
+            })
+            emitEvent?.('run_completed', {
+                message: 'Zephyr workflow completed successfully.',
+                data: {
+                    version: ZEPHYR_VERSION,
+                    workflow: currentExecutionMode.workflow
+                }
+            })
             return
-        } catch (error) {
-            logError('\nRelease failed:')
-            logError(error.message)
-            if (error.stack) {
-                writeStderrLine(error.stack)
-            }
-            process.exit(1)
         }
-    }
 
-    if (releaseType === 'packagist') {
-        try {
-            await releasePackagist()
+        if (options.workflowType === 'packagist') {
+            await releasePackagist({
+                releaseType: options.versionArg,
+                skipTests: options.skipTests,
+                skipLint: options.skipLint,
+                context: appContext
+            })
+            emitEvent?.('run_completed', {
+                message: 'Zephyr workflow completed successfully.',
+                data: {
+                    version: ZEPHYR_VERSION,
+                    workflow: currentExecutionMode.workflow
+                }
+            })
             return
-        } catch (error) {
-            logError('\nRelease failed:')
-            logError(error.message)
-            if (error.stack) {
-                writeStderrLine(error.stack)
-            }
-            process.exit(1)
         }
-    }
 
-    const rootDir = process.cwd()
+        const rootDir = process.cwd()
 
-    await bootstrap.ensureGitignoreEntry(rootDir, {
-        projectConfigDir: PROJECT_CONFIG_DIR,
-        runCommand,
-        logSuccess,
-        logWarning
-    })
-    await bootstrap.ensureProjectReleaseScript(rootDir, {
-        runPrompt,
-        runCommand,
-        logSuccess,
-        logWarning,
-        releaseScriptName: RELEASE_SCRIPT_NAME,
-        releaseScriptCommand: RELEASE_SCRIPT_COMMAND
-    })
+        await bootstrap.ensureGitignoreEntry(rootDir, {
+            projectConfigDir: PROJECT_CONFIG_DIR,
+            runCommand,
+            logSuccess,
+            logWarning
+        })
+        await bootstrap.ensureProjectReleaseScript(rootDir, {
+            runPrompt,
+            runCommand,
+            logSuccess,
+            logWarning,
+            interactive: currentExecutionMode.interactive,
+            releaseScriptName: RELEASE_SCRIPT_NAME,
+            releaseScriptCommand: RELEASE_SCRIPT_COMMAND
+        })
 
-    const packageJsonPath = path.join(rootDir, 'package.json')
-    const composerJsonPath = path.join(rootDir, 'composer.json')
-    const hasPackageJson = await fs.access(packageJsonPath).then(() => true).catch(() => false)
-    const hasComposerJson = await fs.access(composerJsonPath).then(() => true).catch(() => false)
+        const packageJsonPath = path.join(rootDir, 'package.json')
+        const composerJsonPath = path.join(rootDir, 'composer.json')
+        const hasPackageJson = await fs.access(packageJsonPath).then(() => true).catch(() => false)
+        const hasComposerJson = await fs.access(composerJsonPath).then(() => true).catch(() => false)
 
-    if (hasPackageJson || hasComposerJson) {
-        logProcessing('Validating dependencies...')
-        await validateLocalDependencies(rootDir, runPrompt, logSuccess)
-    }
+        if (hasPackageJson || hasComposerJson) {
+            logProcessing('Validating dependencies...')
+            await validateLocalDependencies(rootDir, runPrompt, logSuccess, {
+                interactive: currentExecutionMode.interactive
+            })
+        }
 
-    const {deploymentConfig} = await selectDeploymentTarget(rootDir, {
-        configurationService,
-        runPrompt,
-        logProcessing,
-        logSuccess,
-        logWarning
-    })
+        const {deploymentConfig} = await selectDeploymentTarget(rootDir, {
+            configurationService,
+            runPrompt,
+            logProcessing,
+            logSuccess,
+            logWarning,
+            emitEvent,
+            executionMode: currentExecutionMode
+        })
 
-    const snapshotToUse = await resolvePendingSnapshot(rootDir, deploymentConfig, {
-        runPrompt,
-        logProcessing,
-        logWarning
-    })
+        const snapshotToUse = await resolvePendingSnapshot(rootDir, deploymentConfig, {
+            runPrompt,
+            logProcessing,
+            logWarning,
+            executionMode: currentExecutionMode
+        })
+
+        await runRemoteTasks(deploymentConfig, {
+            rootDir,
+            snapshot: snapshotToUse,
+            versionArg: options.versionArg,
+            context: appContext
+        })
+
+        emitEvent?.('run_completed', {
+            message: 'Zephyr workflow completed successfully.',
+            data: {
+                version: ZEPHYR_VERSION,
+                workflow: currentExecutionMode.workflow
+            }
+        })
+    } catch (error) {
+        const errorCode = getErrorCode(error)
+        emitEvent?.('run_failed', {
+            message: error.message,
+            code: errorCode,
+            data: {
+                version: ZEPHYR_VERSION,
+                workflow: currentExecutionMode.workflow
+            }
+        })
 
-    await runRemoteTasks(deploymentConfig, {rootDir, snapshot: snapshotToUse, versionArg})
+        if (!currentExecutionMode.json) {
+            logError(error.message)
+            if (errorCode === 'ZEPHYR_FAILURE' && error.stack) {
+                writeStderrLine(error.stack)
+            }
+        }
+
+        throw error
+    }
 }
 
 export {main, runRemoteTasks}

package/src/project/bootstrap.mjs

@@ -1,6 +1,8 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 
+import {ZephyrError} from '../runtime/errors.mjs'
+
 export async function ensureGitignoreEntry(rootDir, {
   projectConfigDir = '.zephyr',
   runCommand,
@@ -66,6 +68,7 @@ export async function ensureProjectReleaseScript(rootDir, {
   runCommand,
   logSuccess,
   logWarning,
+  interactive = true,
   releaseScriptName = 'release',
   releaseScriptCommand = 'npx @wyxos/zephyr@latest'
 } = {}) {
@@ -96,6 +99,13 @@ export async function ensureProjectReleaseScript(rootDir, {
     return false
   }
 
+  if (!interactive) {
+    throw new ZephyrError(
+      'Zephyr cannot run non-interactively because package.json is missing the Zephyr release script. Add `"release": "npx @wyxos/zephyr@latest"` and rerun.',
+      {code: 'ZEPHYR_RELEASE_SCRIPT_REQUIRED'}
+    )
+  }
+
   const { installReleaseScript } = await runPrompt([
     {
       type: 'confirm',
@@ -144,4 +154,3 @@ export async function ensureProjectReleaseScript(rootDir, {
 
   return true
 }
-

package/src/release/shared.mjs

@@ -65,14 +65,23 @@ export function parseReleaseArgs({
 
 export async function runReleaseCommand(command, args, {
   cwd = process.cwd(),
-  capture = false
+  capture = false,
+  runCommandImpl = runCommandBase,
+  runCommandCaptureImpl = runCommandCaptureBase
 } = {}) {
   if (capture) {
-    const { stdout, stderr } = await runCommandCaptureBase(command, args, { cwd })
+    const captured = await runCommandCaptureImpl(command, args, { cwd })
+
+    if (typeof captured === 'string') {
+      return { stdout: captured.trim(), stderr: '' }
+    }
+
+    const stdout = captured?.stdout ?? ''
+    const stderr = captured?.stderr ?? ''
     return { stdout: stdout.trim(), stderr: stderr.trim() }
   }
 
-  await runCommandBase(command, args, { cwd })
+  await runCommandImpl(command, args, { cwd })
   return undefined
 }
 
@@ -91,9 +100,10 @@ export async function ensureCleanWorkingTree(rootDir = process.cwd(), {
 
 export async function validateReleaseDependencies(rootDir = process.cwd(), {
   prompt = (questions) => inquirer.prompt(questions),
-  logSuccess
+  logSuccess,
+  interactive = true
 } = {}) {
-  await validateLocalDependencies(rootDir, prompt, logSuccess)
+  await validateLocalDependencies(rootDir, prompt, logSuccess, { interactive })
 }
 
 export async function ensureReleaseBranchReady({

package/src/release-node.mjs

@@ -1,27 +1,37 @@
 import process from 'node:process'
-import chalk from 'chalk'
-import {createChalkLogger} from './utils/output.mjs'
-import {
-    parseReleaseArgs,
-} from './release/shared.mjs'
+import {createAppContext} from './runtime/app-context.mjs'
+import {parseReleaseArgs} from './release/shared.mjs'
 import {releaseNodePackage} from './application/release/release-node-package.mjs'
 
-const {logProcessing: logStep, logSuccess, logWarning} = createChalkLogger(chalk)
-
-export async function releaseNode() {
-    const {releaseType, skipTests, skipLint, skipBuild, skipDeploy} = parseReleaseArgs({
-        booleanFlags: ['--skip-tests', '--skip-lint', '--skip-build', '--skip-deploy']
+export async function releaseNode(options = {}) {
+    const parsed = options.releaseType
+        ? options
+        : parseReleaseArgs({
+            booleanFlags: ['--skip-tests', '--skip-lint', '--skip-build', '--skip-deploy']
+        })
+    const rootDir = options.rootDir ?? process.cwd()
+    const context = options.context ?? createAppContext({
+        executionMode: {
+            interactive: true,
+            json: false,
+            workflow: 'release-node'
+        }
     })
-    const rootDir = process.cwd()
+    const {logProcessing: logStep, logSuccess, logWarning, runPrompt, runCommand, runCommandCapture, executionMode} = context
+
     await releaseNodePackage({
-        releaseType,
-        skipTests,
-        skipLint,
-        skipBuild,
-        skipDeploy,
+        releaseType: parsed.releaseType,
+        skipTests: parsed.skipTests === true,
+        skipLint: parsed.skipLint === true,
+        skipBuild: parsed.skipBuild === true,
+        skipDeploy: parsed.skipDeploy === true,
         rootDir,
         logStep,
         logSuccess,
-        logWarning
+        logWarning,
+        runPrompt,
+        runCommandImpl: runCommand,
+        runCommandCaptureImpl: runCommandCapture,
+        interactive: executionMode?.interactive !== false
     })
 }

package/src/release-packagist.mjs

@@ -1,25 +1,36 @@
 import process from 'node:process'
-import chalk from 'chalk'
-import {createChalkLogger} from './utils/output.mjs'
-import {
-    parseReleaseArgs,
-} from './release/shared.mjs'
+import {createAppContext} from './runtime/app-context.mjs'
+import {parseReleaseArgs} from './release/shared.mjs'
 import {releasePackagistPackage} from './application/release/release-packagist-package.mjs'
 
-const {logProcessing: logStep, logSuccess, logWarning} = createChalkLogger(chalk)
-
-export async function releasePackagist() {
-    const {releaseType, skipTests, skipLint} = parseReleaseArgs({
-        booleanFlags: ['--skip-tests', '--skip-lint']
+export async function releasePackagist(options = {}) {
+    const parsed = options.releaseType
+        ? options
+        : parseReleaseArgs({
+            booleanFlags: ['--skip-tests', '--skip-lint']
+        })
+    const rootDir = options.rootDir ?? process.cwd()
+    const context = options.context ?? createAppContext({
+        executionMode: {
+            interactive: true,
+            json: false,
+            workflow: 'release-packagist'
+        }
     })
-    const rootDir = process.cwd()
+    const {logProcessing: logStep, logSuccess, logWarning, runPrompt, runCommand, runCommandCapture, executionMode} = context
+
     await releasePackagistPackage({
-        releaseType,
-        skipTests,
-        skipLint,
+        releaseType: parsed.releaseType,
+        skipTests: parsed.skipTests === true,
+        skipLint: parsed.skipLint === true,
         rootDir,
         logStep,
         logSuccess,
-        logWarning
+        logWarning,
+        runPrompt,
+        runCommandImpl: runCommand,
+        runCommandCaptureImpl: runCommandCapture,
+        interactive: executionMode?.interactive !== false,
+        progressWriter: executionMode?.json ? process.stderr : process.stdout
     })
 }

package/src/runtime/app-context.mjs

@@ -2,7 +2,7 @@ import chalk from 'chalk'
 import inquirer from 'inquirer'
 import {NodeSSH} from 'node-ssh'
 
-import {createChalkLogger} from '../utils/output.mjs'
+import {createChalkLogger, createJsonEventEmitter, createJsonLogger} from '../utils/output.mjs'
 import {runCommand as runCommandBase, runCommandCapture as runCommandCaptureBase} from '../utils/command.mjs'
 import {createLocalCommandRunners} from './local-command.mjs'
 import {createRunPrompt} from './prompt.mjs'
@@ -13,16 +13,41 @@ export function createAppContext({
                                      inquirerInstance = inquirer,
                                      NodeSSHClass = NodeSSH,
                                      runCommandImpl = runCommandBase,
-                                     runCommandCaptureImpl = runCommandCaptureBase
+                                     runCommandCaptureImpl = runCommandCaptureBase,
+                                     executionMode = {}
                                  } = {}) {
-    const {logProcessing, logSuccess, logWarning, logError} = createChalkLogger(chalkInstance)
-    const runPrompt = createRunPrompt({inquirer: inquirerInstance})
+    const normalizedExecutionMode = {
+        interactive: executionMode.interactive !== false,
+        json: executionMode.json === true,
+        workflow: executionMode.workflow ?? 'deploy',
+        presetName: executionMode.presetName ?? null,
+        maintenanceMode: executionMode.maintenanceMode ?? null,
+        resumePending: executionMode.resumePending === true,
+        discardPending: executionMode.discardPending === true
+    }
+    const emitEvent = normalizedExecutionMode.json
+        ? createJsonEventEmitter({workflow: normalizedExecutionMode.workflow})
+        : null
+    const {logProcessing, logSuccess, logWarning, logError} = normalizedExecutionMode.json
+        ? createJsonLogger({emitEvent})
+        : createChalkLogger(chalkInstance)
+    const runPrompt = createRunPrompt({
+        inquirer: inquirerInstance,
+        interactive: normalizedExecutionMode.interactive,
+        emitEvent,
+        workflow: normalizedExecutionMode.workflow
+    })
     const createSshClient = createSshClientFactory({NodeSSH: NodeSSHClass})
     const {runCommand, runCommandCapture} = createLocalCommandRunners({
         runCommandBase: runCommandImpl,
         runCommandCaptureBase: runCommandCaptureImpl
     })
 
+    const runCommandWithMode = (command, args, options = {}) => runCommand(command, args, {
+        ...options,
+        forwardStdoutToStderr: normalizedExecutionMode.json
+    })
+
     return {
         logProcessing,
         logSuccess,
@@ -30,7 +55,9 @@ export function createAppContext({
         logError,
         runPrompt,
         createSshClient,
-        runCommand,
-        runCommandCapture
+        runCommand: runCommandWithMode,
+        runCommandCapture,
+        emitEvent,
+        executionMode: normalizedExecutionMode
     }
 }

package/src/runtime/errors.mjs

@@ -0,0 +1,46 @@
+export class ZephyrError extends Error {
+    constructor(message, {
+        code = 'ZEPHYR_FAILURE',
+        data = {},
+        cause
+    } = {}) {
+        super(message, cause ? {cause} : undefined)
+        this.name = this.constructor.name
+        this.code = code
+        this.data = data
+    }
+}
+
+export class PromptRequiredError extends ZephyrError {
+    constructor(message, {
+        data = {},
+        cause
+    } = {}) {
+        super(message, {
+            code: 'ZEPHYR_PROMPT_REQUIRED',
+            data,
+            cause
+        })
+    }
+}
+
+export class InvalidCliOptionsError extends ZephyrError {
+    constructor(message, {
+        data = {},
+        cause
+    } = {}) {
+        super(message, {
+            code: 'ZEPHYR_INVALID_OPTIONS',
+            data,
+            cause
+        })
+    }
+}
+
+export function getErrorCode(error) {
+    if (error && typeof error === 'object' && typeof error.code === 'string' && error.code.length > 0) {
+        return error.code
+    }
+
+    return 'ZEPHYR_FAILURE'
+}

package/src/runtime/local-command.mjs

@@ -1,10 +1,20 @@
+import process from 'node:process'
+
 export function createLocalCommandRunners({ runCommandBase, runCommandCaptureBase }) {
   if (!runCommandBase || !runCommandCaptureBase) {
     throw new Error('createLocalCommandRunners requires runCommandBase and runCommandCaptureBase')
   }
 
-  const runCommand = async (command, args, { silent = false, cwd } = {}) => {
-    const stdio = silent ? 'ignore' : 'inherit'
+  const runCommand = async (command, args, {
+    silent = false,
+    cwd,
+    forwardStdoutToStderr = false
+  } = {}) => {
+    const stdio = silent
+      ? 'ignore'
+      : forwardStdoutToStderr
+        ? ['ignore', process.stderr, process.stderr]
+        : 'inherit'
     return runCommandBase(command, args, { cwd, stdio })
   }
 
@@ -15,4 +25,3 @@ export function createLocalCommandRunners({ runCommandBase, runCommandCaptureBas
 
   return { runCommand, runCommandCapture }
 }
-