@wyxos/zephyr 0.5.0 → 0.6.0

package/README.md

@@ -40,9 +40,12 @@ Common workflows:
 # Deploy an app using the saved preset or the interactive prompts
 zephyr
 
-# Deploy an app and bump the local npm package version first
+# Deploy an app with a local npm package version bump
 zephyr minor
 
+# Deploy an app while bypassing Zephyr's built-in local checks
+zephyr minor --skip-checks
+
 # Deploy a configured app non-interactively
 zephyr --non-interactive --preset wyxos-release --maintenance off
 
@@ -155,6 +158,8 @@ 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 fresh Laravel app deploys, Zephyr runs local lint/test checks before creating the version-bump commit so failed checks do not force repeated bump retries.
+- For critical app deploys, `--skip-checks` is shorthand for `--skip-lint --skip-tests`. It skips Zephyr's built-in local checks, but any local `pre-push` hook can still run its own checks during git push unless you also opt into `--skip-git-hooks`.
 - For non-interactive app deploys, use a saved preset name instead of relying on prompt fallback.
 
 ## Features

package/package.json

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

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

@@ -10,6 +10,8 @@ export async function prepareLocalDeployment(config, {
     rootDir = process.cwd(),
     versionArg = null,
     skipGitHooks = false,
+    skipTests = false,
+    skipLint = false,
     runPrompt,
     runCommand,
     runCommandCapture,
@@ -31,10 +33,29 @@ export async function prepareLocalDeployment(config, {
     const checkSupport = await resolveLocalDeploymentCheckSupport({
         rootDir,
         isLaravel: context.isLaravel,
+        skipTests,
+        skipLint,
         runCommandCapture
     })
 
     if (!snapshot && context.isLaravel) {
+        await runLocalDeploymentChecks({
+            rootDir,
+            isLaravel: context.isLaravel,
+            hasHook: context.hasHook,
+            skipGitHooks,
+            skipTests,
+            skipLint,
+            forceRunWhenHookPresent: true,
+            runCommand,
+            runCommandCapture,
+            logProcessing,
+            logSuccess,
+            logWarning,
+            lintCommand: checkSupport.lintCommand,
+            testCommand: checkSupport.testCommand
+        })
+
         await bumpLocalPackageVersion(rootDir, {
             versionArg,
             skipGitHooks,
@@ -52,6 +73,8 @@ export async function prepareLocalDeployment(config, {
             logWarning,
             skipGitHooks
         })
+
+        return context
     }
 
     await runLocalDeploymentChecks({
@@ -59,6 +82,8 @@ export async function prepareLocalDeployment(config, {
         isLaravel: context.isLaravel,
         hasHook: context.hasHook,
         skipGitHooks,
+        skipTests,
+        skipLint,
         runCommand,
         runCommandCapture,
         logProcessing,

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

@@ -366,6 +366,8 @@ export async function runDeployment(config, options = {}) {
             rootDir,
             versionArg,
             skipGitHooks: executionMode?.skipGitHooks === true,
+            skipTests: executionMode?.skipTests === true,
+            skipLint: executionMode?.skipLint === true,
             runPrompt,
             runCommand,
             runCommandCapture: context.runCommandCapture,

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

@@ -50,19 +50,23 @@ async function resolveSupportedLaravelTestCommand(rootDir, {runCommandCapture} =
 export async function resolveLocalDeploymentCheckSupport({
     rootDir,
     isLaravel,
+    skipTests = false,
+    skipLint = false,
     runCommandCapture
 } = {}) {
     let lintCommand = null
 
-    try {
-        lintCommand = await preflight.resolveSupportedLintCommand(rootDir, {commandExists})
-    } catch (error) {
-        if (error?.code !== 'ZEPHYR_LINT_COMMAND_NOT_FOUND') {
-            throw error
+    if (!skipLint) {
+        try {
+            lintCommand = await preflight.resolveSupportedLintCommand(rootDir, {commandExists})
+        } catch (error) {
+            if (error?.code !== 'ZEPHYR_LINT_COMMAND_NOT_FOUND') {
+                throw error
+            }
         }
     }
 
-    const testCommand = isLaravel
+    const testCommand = isLaravel && !skipTests
         ? await resolveSupportedLaravelTestCommand(rootDir, {runCommandCapture})
         : null
 
@@ -95,6 +99,9 @@ export async function runLocalDeploymentChecks({
     isLaravel,
     hasHook,
     skipGitHooks = false,
+    skipTests = false,
+    skipLint = false,
+    forceRunWhenHookPresent = false,
     runCommand,
     runCommandCapture,
     logProcessing,
@@ -108,6 +115,8 @@ export async function runLocalDeploymentChecks({
         : await resolveLocalDeploymentCheckSupport({
             rootDir,
             isLaravel,
+            skipTests,
+            skipLint,
             runCommandCapture
         })
 
@@ -116,6 +125,10 @@ export async function runLocalDeploymentChecks({
             logWarning?.(
                 'Pre-push git hook detected. Zephyr will run its built-in release checks manually because --skip-git-hooks is enabled, and the hook will be bypassed during git push.'
             )
+        } else if (forceRunWhenHookPresent) {
+            logProcessing?.(
+                'Pre-push git hook detected. Zephyr will run its built-in release checks now before bumping the deployment version. The hook will still run again during git push.'
+            )
         } else {
             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.'
@@ -124,11 +137,19 @@ export async function runLocalDeploymentChecks({
         }
     }
 
-    if (support.lintCommand === null) {
+    if (hasHook && !skipGitHooks && (skipLint || skipTests)) {
+        logWarning?.(
+            'Pre-push git hook detected. --skip-lint/--skip-tests only skip Zephyr\'s built-in checks; your hook may still run its own checks during git push.'
+        )
+    }
+
+    if (skipLint) {
+        logWarning?.('Skipping lint because --skip-lint flag was provided.')
+    } else if (support.lintCommand === null) {
         logWarning?.('No supported lint command was found. Skipping linting checks.')
     }
 
-    const lintRan = support.lintCommand === null
+    const lintRan = skipLint || support.lintCommand === null
         ? false
         : await preflight.runLinting(rootDir, {
             runCommand,
@@ -152,7 +173,9 @@ export async function runLocalDeploymentChecks({
         }
     }
 
-    if (isLaravel) {
+    if (isLaravel && skipTests) {
+        logWarning?.('Skipping tests because --skip-tests flag was provided.')
+    } else if (isLaravel) {
         await runLocalLaravelTests(rootDir, {
             runCommand,
             logProcessing,

package/src/cli/options.mjs

@@ -36,8 +36,9 @@ export function parseCliOptions(args = process.argv.slice(2)) {
         .option('--discard-pending', 'Discard a saved pending deployment snapshot without prompting.')
         .option('--maintenance <mode>', 'Laravel maintenance mode policy for app deployments (on|off).')
         .option('--skip-git-hooks', 'Bypass local git hooks for any commits and pushes Zephyr performs.')
-        .option('--skip-tests', 'Skip test execution in package release workflows.')
-        .option('--skip-lint', 'Skip lint execution in package release workflows.')
+        .option('--skip-checks', 'Skip Zephyr local lint and test execution.')
+        .option('--skip-tests', 'Skip Zephyr local test execution in package release and app deployment workflows.')
+        .option('--skip-lint', 'Skip Zephyr local lint execution in package release and app deployment 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(
@@ -68,8 +69,9 @@ export function parseCliOptions(args = process.argv.slice(2)) {
         discardPending: Boolean(options.discardPending),
         maintenanceMode: normalizeMaintenanceMode(options.maintenance),
         skipGitHooks: Boolean(options.skipGitHooks),
-        skipTests: Boolean(options.skipTests),
-        skipLint: Boolean(options.skipLint),
+        skipChecks: Boolean(options.skipChecks),
+        skipTests: Boolean(options.skipTests || options.skipChecks),
+        skipLint: Boolean(options.skipLint || options.skipChecks),
         skipBuild: Boolean(options.skipBuild),
         skipDeploy: Boolean(options.skipDeploy)
     }
@@ -84,8 +86,6 @@ export function validateCliOptions(options = {}) {
         resumePending = false,
         discardPending = false,
         maintenanceMode = null,
-        skipTests = false,
-        skipLint = false,
         skipBuild = false,
         skipDeploy = false
     } = options
@@ -113,8 +113,8 @@ export function validateCliOptions(options = {}) {
             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 (skipBuild || skipDeploy) {
+            throw new InvalidCliOptionsError('--skip-build and --skip-deploy are only valid for node/vue release workflows.')
         }
 
         if (nonInteractive && !presetName) {

package/src/deploy/local-repo.mjs

@@ -2,7 +2,6 @@ import { getCurrentBranch as getCurrentBranchImpl, getUpstreamRef as getUpstream
 import {hasPrePushHook} from './preflight.mjs'
 import {gitCommitArgs, gitPushArgs} from '../utils/git-hooks.mjs'
 import {
-  buildFallbackCommitMessage,
   formatWorkingTreePreview,
   parseWorkingTreeEntries,
   suggestCommitMessage as suggestCommitMessageImpl
@@ -213,35 +212,24 @@ async function commitAndPushPendingChanges(targetBranch, rootDir, {
     logStep: logProcessing,
     logWarning,
     statusEntries
-  }) ?? buildFallbackCommitMessage(statusEntries)
-
-  const changeLabel = statusEntries.length === 1 ? 'change' : 'changes'
-  const {shouldCommitPendingChanges} = await runPrompt([
+  })
+  const { commitMessage } = await runPrompt([
     {
-      type: 'confirm',
-      name: 'shouldCommitPendingChanges',
+      type: 'input',
+      name: 'commitMessage',
       message:
-        `Pending ${changeLabel} detected before deployment:\n\n` +
+        'Pending changes detected before deployment:\n\n' +
         `${formatWorkingTreePreview(statusEntries)}\n\n` +
-        'Stage and commit all current changes before continuing?',
-      default: true
+        'Enter a commit message to stage and commit all current changes before continuing.\n' +
+        'Leave blank to cancel.',
+      default: suggestedCommitMessage ?? ''
     }
   ])
 
-  if (!shouldCommitPendingChanges) {
+  if (!commitMessage || commitMessage.trim().length === 0) {
     throw new Error(DIRTY_DEPLOYMENT_CANCELLED_MESSAGE)
   }
 
-  const { commitMessage } = await runPrompt([
-    {
-      type: 'input',
-      name: 'commitMessage',
-      message: 'Commit message for pending deployment changes',
-      default: suggestedCommitMessage,
-      validate: (value) => (value && value.trim().length > 0 ? true : 'Commit message cannot be empty.')
-    }
-  ])
-
   const message = commitMessage.trim()
 
   logProcessing?.('Staging all pending changes before deployment...')

package/src/main.mjs

@@ -36,8 +36,9 @@ function normalizeMainOptions(firstArg = null, secondArg = null) {
             discardPending: firstArg.discardPending === true,
             maintenanceMode: firstArg.maintenanceMode ?? null,
             skipGitHooks: firstArg.skipGitHooks === true,
-            skipTests: firstArg.skipTests === true,
-            skipLint: firstArg.skipLint === true,
+            skipChecks: firstArg.skipChecks === true,
+            skipTests: firstArg.skipTests === true || firstArg.skipChecks === true,
+            skipLint: firstArg.skipLint === true || firstArg.skipChecks === true,
             skipBuild: firstArg.skipBuild === true,
             skipDeploy: firstArg.skipDeploy === true,
             context: firstArg.context ?? null
@@ -54,6 +55,7 @@ function normalizeMainOptions(firstArg = null, secondArg = null) {
         discardPending: false,
         maintenanceMode: null,
         skipGitHooks: false,
+        skipChecks: false,
         skipTests: false,
         skipLint: false,
         skipBuild: false,
@@ -109,6 +111,9 @@ async function main(optionsOrWorkflowType = null, versionArg = null) {
         presetName: options.presetName,
         maintenanceMode: options.maintenanceMode,
         skipGitHooks: options.skipGitHooks === true,
+        skipChecks: options.skipChecks === true,
+        skipTests: options.skipTests === true,
+        skipLint: options.skipLint === true,
         resumePending: options.resumePending,
         discardPending: options.discardPending
     }
@@ -138,6 +143,9 @@ async function main(optionsOrWorkflowType = null, versionArg = null) {
                     presetName: currentExecutionMode.presetName,
                     maintenanceMode: currentExecutionMode.maintenanceMode,
                     skipGitHooks: currentExecutionMode.skipGitHooks === true,
+                    skipChecks: currentExecutionMode.skipChecks === true,
+                    skipTests: currentExecutionMode.skipTests === true,
+                    skipLint: currentExecutionMode.skipLint === true,
                     resumePending: currentExecutionMode.resumePending,
                     discardPending: currentExecutionMode.discardPending
                 }

package/src/release/commit-message.mjs

@@ -20,9 +20,12 @@ const GENERIC_SUBJECT_PATTERNS = [
   /^update work$/i,
   /^misc(ellaneous)?( updates?)?$/i,
   /^changes$/i,
-  /^updates?$/i
+  /^updates?$/i,
+  /^(improve|update|adjust|refine|align|support|enable)\s+.+\s+(workflow|process|flow)$/i
 ]
 const MAX_WORKING_TREE_PREVIEW = 20
+const MAX_DIFF_EXCERPT_LINES = 60
+const MAX_DIFF_EXCERPT_CHARS = 4000
 const STATUS_LABELS = {
   A: 'added',
   C: 'copied',
@@ -261,10 +264,10 @@ export function buildFallbackCommitMessage(statusEntries = []) {
   }
 
   if (commitType === 'ci') {
-    return `ci: update ${primaryTopic} workflow`
+    return `ci: update ${primaryTopic} pipeline`
   }
 
-  return `chore: improve ${primaryTopic} workflow`
+  return `chore: update ${primaryTopic} handling`
 }
 
 async function collectDiffNumstat(rootDir, {runCommand} = {}) {
@@ -297,12 +300,68 @@ async function collectDiffNumstat(rootDir, {runCommand} = {}) {
   }
 }
 
+function shouldIncludeDiffExcerptLine(line = '') {
+  if (line.startsWith('diff --git ')) {
+    return true
+  }
+
+  if (line.startsWith('@@')) {
+    return true
+  }
+
+  return (line.startsWith('+') || line.startsWith('-')) && !line.startsWith('+++') && !line.startsWith('---')
+}
+
+function trimDiffExcerpt(diffText = '') {
+  const selectedLines = []
+  let totalChars = 0
+
+  for (const rawLine of diffText.split(/\r?\n/)) {
+    const line = rawLine.trimEnd()
+
+    if (!shouldIncludeDiffExcerptLine(line)) {
+      continue
+    }
+
+    const truncatedLine = line.length > 180 ? `${line.slice(0, 177)}...` : line
+    const nextTotal = totalChars + truncatedLine.length + 1
+
+    if (selectedLines.length >= MAX_DIFF_EXCERPT_LINES || nextTotal > MAX_DIFF_EXCERPT_CHARS) {
+      break
+    }
+
+    selectedLines.push(truncatedLine)
+    totalChars = nextTotal
+  }
+
+  return selectedLines.join('\n')
+}
+
+async function collectDiffExcerpt(rootDir, {runCommand} = {}) {
+  try {
+    const {stdout} = await runCommand('git', ['diff', '--unified=0', '--no-color', 'HEAD', '--'], {
+      capture: true,
+      cwd: rootDir
+    })
+
+    return trimDiffExcerpt(stdout)
+  } catch {
+    return ''
+  }
+}
+
 async function buildCommitMessageContext(rootDir, {
   runCommand,
   statusEntries = []
 } = {}) {
   const changeCountsByPath = await collectDiffNumstat(rootDir, {runCommand})
-  return statusEntries.map((entry) => `- ${summarizeWorkingTreeEntry(entry, {changeCountsByPath})}`).join('\n')
+  const summary = statusEntries.map((entry) => `- ${summarizeWorkingTreeEntry(entry, {changeCountsByPath})}`).join('\n')
+  const diffExcerpt = await collectDiffExcerpt(rootDir, {runCommand})
+
+  return {
+    summary,
+    diffExcerpt
+  }
 }
 
 export async function suggestCommitMessage(rootDir = process.cwd(), {
@@ -328,6 +387,21 @@ export async function suggestCommitMessage(rootDir = process.cwd(), {
 
     logStep?.('Generating a suggested commit message with Codex...')
 
+    const promptSections = [
+      'Write exactly one short conventional commit message for these pending changes.',
+      'Use the exact format "<type>: <subject>" with no scope, no exclamation mark, and no extra text.',
+      'Choose the most appropriate type from: fix, feat, chore, docs, refactor, test, style, perf, build, ci, revert.',
+      'Base the subject on the actual behavior, safeguard, bug fix, feature, or API change shown below.',
+      'Avoid generic nouns like "workflow", "process", "flow", "changes", or "updates" unless the diff truly changes CI or docs.',
+      'Do not describe the commit itself, staging, or "pending changes"; describe the underlying code or product change.',
+      'Pending change summary:',
+      commitContext.summary || '- changed files present'
+    ]
+
+    if (commitContext.diffExcerpt) {
+      promptSections.push('Diff excerpt:', commitContext.diffExcerpt)
+    }
+
     await runCommand('codex', [
       'exec',
       '--ephemeral',
@@ -338,15 +412,7 @@ export async function suggestCommitMessage(rootDir = process.cwd(), {
       '--skip-git-repo-check',
       '--output-last-message',
       outputPath,
-      [
-        'Write exactly one short conventional commit message for these pending changes.',
-        'Use the exact format "<type>: <subject>" with no scope, no exclamation mark, and no extra text.',
-        'Choose the most appropriate type from: fix, feat, chore, docs, refactor, test, style, perf, build, ci, revert.',
-        'Make the subject specific enough to describe the actual behavior or workflow change, not just that files changed.',
-        'Do not describe the commit itself, staging, or "pending changes"; describe the underlying behavior or workflow fix.',
-        'Pending change summary:',
-        commitContext || '- changed files present'
-      ].join('\n\n')
+      promptSections.join('\n\n')
     ], {
       capture: true,
       cwd: rootDir

package/src/release/shared.mjs

@@ -10,7 +10,6 @@ import {
   getUpstreamRef
 } from '../utils/git.mjs'
 import {
-  buildFallbackCommitMessage,
   formatWorkingTreePreview,
   parseWorkingTreeEntries,
   parseWorkingTreeStatus,
@@ -117,35 +116,24 @@ export async function ensureCleanWorkingTree(rootDir = process.cwd(), {
     logStep,
     logWarning,
     statusEntries
-  }) ?? buildFallbackCommitMessage(statusEntries)
-
-  const changeLabel = statusEntries.length === 1 ? 'change' : 'changes'
-  const {shouldCommitPendingChanges} = await runPrompt([
+  })
+  const {commitMessage} = await runPrompt([
     {
-      type: 'confirm',
-      name: 'shouldCommitPendingChanges',
+      type: 'input',
+      name: 'commitMessage',
       message:
-        `Pending ${changeLabel} detected before release:\n\n` +
+        'Pending changes detected before release:\n\n' +
         `${formatWorkingTreePreview(statusEntries)}\n\n` +
-        'Stage and commit all current changes before continuing?',
-      default: true
+        'Enter a commit message to stage and commit all current changes before continuing.\n' +
+        'Leave blank to cancel.',
+      default: suggestedCommitMessage ?? ''
     }
   ])
 
-  if (!shouldCommitPendingChanges) {
+  if (!commitMessage || commitMessage.trim().length === 0) {
     throw new Error(DIRTY_WORKING_TREE_CANCELLED_MESSAGE)
   }
 
-  const {commitMessage} = await runPrompt([
-    {
-      type: 'input',
-      name: 'commitMessage',
-      message: 'Commit message for pending release changes',
-      default: suggestedCommitMessage,
-      validate: (value) => (value && value.trim().length > 0 ? true : 'Commit message cannot be empty.')
-    }
-  ])
-
   const message = commitMessage.trim()
 
   logStep?.('Staging all pending changes before release...')

package/src/runtime/app-context.mjs

@@ -25,6 +25,9 @@ export function createAppContext({
         presetName: executionMode.presetName ?? null,
         maintenanceMode: executionMode.maintenanceMode ?? null,
         skipGitHooks: executionMode.skipGitHooks === true,
+        skipChecks: executionMode.skipChecks === true,
+        skipTests: executionMode.skipTests === true || executionMode.skipChecks === true,
+        skipLint: executionMode.skipLint === true || executionMode.skipChecks === true,
         resumePending: executionMode.resumePending === true,
         discardPending: executionMode.discardPending === true
     }