@wyxos/zephyr 0.4.5 → 0.4.7

package/README.md

@@ -68,6 +68,8 @@ When `--type node` or `--type vue` is used without a bump argument, Zephyr defau
 
 Interactive mode remains the default and is the best fit for first-time setup, config repair, and one-off deployments.
 
+For app deployments, interactive mode now requires a real interactive terminal. If stdin/stdout are not attached to a TTY, Zephyr refuses to continue in interactive mode and tells you to rerun with --non-interactive --preset <name> --maintenance on|off.
+
 Non-interactive mode is strict and is intended for already-configured projects:
 
 - `--non-interactive` fails instead of prompting
@@ -77,6 +79,8 @@ Non-interactive mode is strict and is intended for already-configured projects:
 - stale remote locks are never auto-removed in non-interactive mode
 - `--json` is only supported together with `--non-interactive`
 
+If Laravel maintenance mode has already been enabled and Zephyr then exits abnormally because of a signal such as `SIGINT`, `SIGTERM`, or `SIGHUP`, it now makes a best-effort attempt to run `artisan up` automatically before exiting.
+
 If Zephyr would normally prompt to:
 
 - create or repair config

package/package.json

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

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

@@ -190,24 +190,16 @@ async function resolvePhpCommand({
                                      requiredPhpVersion,
                                      ssh,
                                      remoteCwd,
-                                     logProcessing,
-                                     logWarning
+                                     logProcessing
                                  } = {}) {
     if (!requiredPhpVersion) {
         return 'php'
     }
 
-    try {
-        const phpCommand = await findPhpBinary(ssh, remoteCwd, requiredPhpVersion)
-        if (phpCommand !== 'php') {
-            logProcessing?.(`Detected PHP requirement: ${requiredPhpVersion}, using ${phpCommand}`)
-        }
+    const phpCommand = await findPhpBinary(ssh, remoteCwd, requiredPhpVersion)
+    logProcessing?.(`Detected PHP requirement: ${requiredPhpVersion}, using ${phpCommand}`)
 
-        return phpCommand
-    } catch (error) {
-        logWarning?.(`Could not find PHP binary for version ${requiredPhpVersion}: ${error.message}`)
-        return 'php'
-    }
+    return phpCommand
 }
 
 function createMaintenanceModePlan({

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

@@ -59,7 +59,9 @@ async function maybeRecoverLaravelMaintenanceMode({
     runPrompt,
     logProcessing,
     logWarning,
-    executionMode = {}
+    executionMode = {},
+    forceAutoRecovery = false,
+    reason = null
 } = {}) {
     if (!remotePlan?.remoteIsLaravel || !remotePlan?.maintenanceModeEnabled) {
         return
@@ -75,8 +77,11 @@ async function maybeRecoverLaravelMaintenanceMode({
     }
 
     try {
-        if (executionMode?.interactive === false) {
-            logProcessing?.('Deployment failed after Laravel maintenance mode was enabled. Running `artisan up` automatically...')
+        if (forceAutoRecovery || executionMode?.interactive === false) {
+            const reasonSuffix = typeof reason === 'string' && reason.length > 0
+                ? ` because of ${reason}`
+                : ''
+            logProcessing?.(`Deployment interrupted${reasonSuffix} after Laravel maintenance mode was enabled. Running \`artisan up\` automatically...`)
             await executeRemote(
                 'Disable Laravel maintenance mode',
                 remotePlan.maintenanceUpCommand ?? `${remotePlan.phpCommand} artisan up`
@@ -115,6 +120,129 @@ async function maybeRecoverLaravelMaintenanceMode({
     }
 }
 
+function signalToExitCode(signal) {
+    const signalNumbers = {
+        SIGHUP: 1,
+        SIGINT: 2,
+        SIGTERM: 15
+    }
+
+    if (!signalNumbers[signal]) {
+        return null
+    }
+
+    return 128 + signalNumbers[signal]
+}
+
+export function createAbnormalExitGuard({
+    processRef = process,
+    cleanup = async () => {},
+    terminate = null,
+    logWarning
+} = {}) {
+    const listeners = new Map()
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP']
+    let active = true
+    let cleanupPromise = null
+
+    const terminateProcess = typeof terminate === 'function'
+        ? terminate
+        : async (signal) => {
+            const exitCode = signalToExitCode(signal)
+
+            if (typeof exitCode === 'number') {
+                processRef.exitCode = exitCode
+            }
+
+            if (typeof processRef.kill === 'function' && typeof processRef.pid === 'number') {
+                processRef.kill(processRef.pid, signal)
+            }
+        }
+
+    const unregister = () => {
+        if (!active) {
+            return
+        }
+
+        active = false
+
+        for (const [signal, handler] of listeners.entries()) {
+            if (typeof processRef.off === 'function') {
+                processRef.off(signal, handler)
+                continue
+            }
+
+            if (typeof processRef.removeListener === 'function') {
+                processRef.removeListener(signal, handler)
+            }
+        }
+
+        listeners.clear()
+    }
+
+    const run = async (signal) => {
+        if (!active) {
+            return cleanupPromise
+        }
+
+        if (cleanupPromise) {
+            return cleanupPromise
+        }
+
+        unregister()
+        cleanupPromise = (async () => {
+            try {
+                await cleanup(signal)
+            } catch (error) {
+                logWarning?.(`Best-effort deploy recovery after ${signal} failed: ${error.message}`)
+            } finally {
+                await terminateProcess(signal)
+            }
+        })()
+
+        return cleanupPromise
+    }
+
+    for (const signal of signals) {
+        const handler = () => {
+            void run(signal)
+        }
+
+        listeners.set(signal, handler)
+        processRef.once(signal, handler)
+    }
+
+    return {
+        unregister,
+        run
+    }
+}
+
+async function cleanupDeploymentResources({
+    rootDir,
+    ssh,
+    remoteCwd,
+    lockAcquired,
+    logWarning
+} = {}) {
+    if (lockAcquired && ssh && remoteCwd) {
+        try {
+            await releaseRemoteLock(ssh, remoteCwd, {logWarning})
+            await releaseLocalLock(rootDir, {logWarning})
+        } catch (error) {
+            logWarning?.(`Failed to release lock: ${error.message}`)
+        }
+    }
+
+    await closeLogFile()
+
+    if (ssh) {
+        ssh.dispose()
+    }
+}
+
+export {maybeRecoverLaravelMaintenanceMode}
+
 export async function runDeployment(config, options = {}) {
     const {
         snapshot = null,
@@ -150,6 +278,64 @@ export async function runDeployment(config, options = {}) {
     }
 
     let lockAcquired = false
+    const abnormalExitGuard = createAbnormalExitGuard({
+        logWarning,
+        cleanup: async (signal) => {
+            let recoverySsh = null
+            let recoveryExecutor = executeRemote
+
+            try {
+                if (remoteCwd) {
+                    ({ssh: recoverySsh} = await connectToRemoteDeploymentTarget({
+                        config,
+                        createSshClient,
+                        sshUser,
+                        privateKey,
+                        remoteCwd,
+                        logProcessing,
+                        message: `Reconnecting to ${config.serverIp} as ${sshUser} for abnormal-exit recovery...`
+                    }))
+
+                    recoveryExecutor = createRemoteExecutor({
+                        ssh: recoverySsh,
+                        rootDir,
+                        remoteCwd,
+                        writeToLogFile,
+                        logProcessing,
+                        logSuccess,
+                        logError
+                    })
+                }
+
+                await maybeRecoverLaravelMaintenanceMode({
+                    remotePlan,
+                    executionState,
+                    executeRemote: recoveryExecutor,
+                    runPrompt,
+                    logProcessing,
+                    logWarning,
+                    executionMode,
+                    forceAutoRecovery: true,
+                    reason: signal
+                })
+            } finally {
+                await cleanupDeploymentResources({
+                    rootDir,
+                    ssh: recoverySsh ?? ssh,
+                    remoteCwd,
+                    lockAcquired,
+                    logWarning
+                })
+                lockAcquired = false
+
+                if (recoverySsh && ssh && recoverySsh !== ssh) {
+                    ssh.dispose()
+                }
+
+                ssh = null
+            }
+        }
+    })
 
     try {
         ({ssh, remoteCwd} = await connectToRemoteDeploymentTarget({
@@ -280,18 +466,13 @@ export async function runDeployment(config, options = {}) {
 
         throw new Error(`Deployment failed: ${error.message}`)
     } finally {
-        if (lockAcquired && ssh && remoteCwd) {
-            try {
-                await releaseRemoteLock(ssh, remoteCwd, {logWarning})
-                await releaseLocalLock(rootDir, {logWarning})
-            } catch (error) {
-                logWarning(`Failed to release lock: ${error.message}`)
-            }
-        }
-
-        await closeLogFile()
-        if (ssh) {
-            ssh.dispose()
-        }
+        abnormalExitGuard.unregister()
+        await cleanupDeploymentResources({
+            rootDir,
+            ssh,
+            remoteCwd,
+            lockAcquired,
+            logWarning
+        })
     }
 }

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

@@ -382,7 +382,15 @@ export async function releaseNodePackage({
     })
 
     logStep?.('Checking working tree status...')
-    await ensureCleanWorkingTree(rootDir, {runCommand})
+    await ensureCleanWorkingTree(rootDir, {
+        runCommand,
+        runPrompt,
+        logStep,
+        logSuccess,
+        logWarning,
+        interactive,
+        skipGitHooks
+    })
     await ensureReleaseBranchReady({rootDir, branchMethod: 'show-current', logStep, logWarning})
 
     await runLint(skipLint, pkg, rootDir, {logStep, logSuccess, logWarning, runCommand})

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

@@ -249,7 +249,15 @@ export async function releasePackagistPackage({
     })
 
     logStep?.('Checking working tree status...')
-    await ensureCleanWorkingTree(rootDir, {runCommand})
+    await ensureCleanWorkingTree(rootDir, {
+        runCommand,
+        runPrompt,
+        logStep,
+        logSuccess,
+        logWarning,
+        interactive,
+        skipGitHooks
+    })
     await ensureReleaseBranchReady({rootDir, branchMethod: 'show-current', logStep, logWarning})
 
     await runLint(skipLint, rootDir, {logStep, logSuccess, logWarning, runCommand, progressWriter})

package/src/infrastructure/php/version.mjs

@@ -2,6 +2,25 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 import semver from 'semver'
 
+function normalizeComposerConstraint(constraint) {
+  if (typeof constraint !== 'string') {
+    return null
+  }
+
+  return constraint
+    .replace(/\s*\|{1,2}\s*/g, ' || ')
+    .replace(/,/g, ' ')
+    .replace(/\s+@[\w.-]+/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function getHighestVersion(versions = []) {
+  return versions
+    .filter((version) => semver.valid(version))
+    .reduce((highest, version) => (!highest || semver.gt(version, highest) ? version : highest), null)
+}
+
 /**
  * Extracts the minimum PHP version requirement from a composer.json object
  * @param {object} composer - Parsed composer.json object
@@ -13,47 +32,78 @@ export function parsePhpVersionRequirement(composer) {
     return null
   }
 
-  // Parse version constraint (e.g., "^8.4", ">=8.4.0", "8.4.*", "~8.4.0")
-  // Extract the minimum version needed
-  const versionMatch = phpRequirement.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
-  if (!versionMatch) {
+  const normalizedConstraint = normalizeComposerConstraint(phpRequirement)
+  if (normalizedConstraint) {
+    const minimumVersion = semver.minVersion(normalizedConstraint)
+    if (minimumVersion) {
+      return minimumVersion.version
+    }
+  }
+
+  const versionMatches = [...phpRequirement.matchAll(/(\d+)\.(\d+)(?:\.(\d+))?/g)]
+  if (versionMatches.length === 0) {
     return null
   }
 
-  const major = versionMatch[1]
-  const minor = versionMatch[2]
-  const patch = versionMatch[3] || '0'
-  
-  const versionStr = `${major}.${minor}.${patch}`
-  
-  // Normalize to semver format
-  if (semver.valid(versionStr)) {
-    return versionStr
+  const versions = versionMatches
+    .map(([, major, minor, patch = '0']) => semver.coerce(`${major}.${minor}.${patch}`)?.version ?? null)
+    .filter(Boolean)
+
+  return versions.length > 0 ? versions.sort(semver.compare)[0] : null
+}
+
+export function parseComposerLockPhpVersionRequirement(lock) {
+  const versions = []
+  const platformPhpVersion = parsePhpVersionRequirement({require: {php: lock?.platform?.php}})
+  if (platformPhpVersion) {
+    versions.push(platformPhpVersion)
   }
-  
-  // Try to coerce to valid semver
-  const coerced = semver.coerce(versionStr)
-  if (coerced) {
-    return coerced.version
+
+  const packages = Array.isArray(lock?.packages) ? lock.packages : []
+  for (const pkg of packages) {
+    const packagePhpVersion = parsePhpVersionRequirement({require: {php: pkg?.require?.php}})
+    if (packagePhpVersion) {
+      versions.push(packagePhpVersion)
+    }
   }
 
-  return null
+  return getHighestVersion(versions)
 }
 
 /**
- * Extracts the minimum PHP version requirement from composer.json file
+ * Extracts the effective minimum PHP version requirement from composer.json and composer.lock.
+ * The lock file wins when runtime dependencies need a higher version than the root package declares.
  * @param {string} rootDir - Project root directory
  * @returns {Promise<string|null>} - PHP version requirement (e.g., "8.4.0") or null
  */
 export async function getPhpVersionRequirement(rootDir) {
+  const versions = []
+
   try {
     const composerPath = path.join(rootDir, 'composer.json')
     const raw = await fs.readFile(composerPath, 'utf8')
     const composer = JSON.parse(raw)
-    return parsePhpVersionRequirement(composer)
+    const composerPhpVersion = parsePhpVersionRequirement(composer)
+    if (composerPhpVersion) {
+      versions.push(composerPhpVersion)
+    }
   } catch {
-    return null
+    // Ignore and continue to composer.lock if present.
   }
+
+  try {
+    const lockPath = path.join(rootDir, 'composer.lock')
+    const raw = await fs.readFile(lockPath, 'utf8')
+    const lock = JSON.parse(raw)
+    const lockPhpVersion = parseComposerLockPhpVersionRequirement(lock)
+    if (lockPhpVersion) {
+      versions.push(lockPhpVersion)
+    }
+  } catch {
+    // Ignore when composer.lock is absent or unreadable.
+  }
+
+  return getHighestVersion(versions)
 }
 
 const RUNCLOUD_PACKAGES = '/RunCloud/Packages'
@@ -126,6 +176,8 @@ export async function findPhpBinary(ssh, remoteCwd, requiredVersion) {
     return 'php'
   }
 
+  let defaultPhpVersion = null
+
   const majorMinor = semver.major(requiredVersion) + '.' + semver.minor(requiredVersion)
   const versionedPhp = `php${majorMinor.replace('.', '')}` // e.g., "php84"
 
@@ -175,11 +227,16 @@ export async function findPhpBinary(ssh, remoteCwd, requiredVersion) {
     if (actualVersion && satisfiesVersion(actualVersion, requiredVersion)) {
       return 'php'
     }
+    defaultPhpVersion = actualVersion
   } catch {
     // Ignore
   }
 
-  return 'php'
+  const defaultVersionHint = defaultPhpVersion
+    ? ` The default php command reports ${defaultPhpVersion}.`
+    : ''
+
+  throw new Error(`No PHP binary satisfying ${requiredVersion} was found on the remote server.${defaultVersionHint}`)
 }
 
 /**

package/src/main.mjs

@@ -8,7 +8,7 @@ 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 {getErrorCode, ZephyrError} 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'
@@ -73,6 +73,23 @@ function resolveWorkflowName(workflowType = null) {
     return 'deploy'
 }
 
+function assertInteractiveAppDeploySession({workflowType = null, executionMode = {}, appContext = {}} = {}) {
+    const isAppDeploy = workflowType !== 'node' && workflowType !== 'vue' && workflowType !== 'packagist'
+
+    if (!isAppDeploy || executionMode?.interactive === false) {
+        return
+    }
+
+    if (appContext?.hasInteractiveTerminal !== false) {
+        return
+    }
+
+    throw new ZephyrError(
+        'Zephyr refuses interactive app deployments without a real interactive terminal. Rerun in a TTY, or use --non-interactive --preset <name> --maintenance on|off.',
+        {code: 'ZEPHYR_INTERACTIVE_SESSION_REQUIRED'}
+    )
+}
+
 async function runRemoteTasks(config, options = {}) {
     return await runDeployment(config, {
         ...options,
@@ -131,6 +148,12 @@ async function main(optionsOrWorkflowType = null, versionArg = null) {
             logWarning(SKIP_GIT_HOOKS_WARNING)
         }
 
+        assertInteractiveAppDeploySession({
+            workflowType: options.workflowType,
+            executionMode: currentExecutionMode,
+            appContext
+        })
+
         if (options.workflowType === 'node' || options.workflowType === 'vue') {
             await releaseNode({
                 releaseType: options.versionArg,

package/src/release/commit-message.mjs

@@ -0,0 +1,331 @@
+import {mkdtemp, readFile, rm} from 'node:fs/promises'
+import {tmpdir} from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+
+import {commandExists} from '../utils/command.mjs'
+
+const CONVENTIONAL_COMMIT_PATTERN = /^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test): .+/i
+const GENERIC_SUBJECT_PATTERNS = [
+  /^commit pending (release )?changes$/i,
+  /^pending (release )?changes$/i,
+  /^commit changes$/i,
+  /^update changes$/i,
+  /^update files$/i,
+  /^update work$/i,
+  /^misc(ellaneous)?( updates?)?$/i,
+  /^changes$/i,
+  /^updates?$/i
+]
+const MAX_WORKING_TREE_PREVIEW = 20
+const STATUS_LABELS = {
+  A: 'added',
+  C: 'copied',
+  D: 'deleted',
+  M: 'modified',
+  R: 'renamed',
+  T: 'type-changed',
+  U: 'conflicted'
+}
+const TOPIC_STOP_WORDS = new Set([
+  'src',
+  'test',
+  'tests',
+  '__tests__',
+  'spec',
+  'specs',
+  'app',
+  'lib',
+  'dist',
+  'packages',
+  'package',
+  'application',
+  'shared',
+  'index',
+  'main',
+  'js',
+  'jsx',
+  'ts',
+  'tsx',
+  'mjs',
+  'cjs',
+  'php',
+  'json',
+  'yaml',
+  'yml',
+  'md',
+  'toml',
+  'lock'
+])
+
+function resolveWorkingTreeEntryLabel(entry) {
+  if (entry.indexStatus === '?' && entry.worktreeStatus === '?') {
+    return 'untracked'
+  }
+
+  if (entry.indexStatus === '!' && entry.worktreeStatus === '!') {
+    return 'ignored'
+  }
+
+  const relevantStatuses = [entry.indexStatus, entry.worktreeStatus].filter((status) => status && status !== ' ')
+  for (const status of relevantStatuses) {
+    if (STATUS_LABELS[status]) {
+      return STATUS_LABELS[status]
+    }
+  }
+
+  return 'changed'
+}
+
+function tokenizePath(pathValue = '') {
+  return pathValue
+    .split(/[\\/]/)
+    .flatMap((segment) => segment.split(/[^a-zA-Z0-9]+/))
+    .map((token) => token.toLowerCase())
+    .filter((token) => token.length >= 3 && !TOPIC_STOP_WORDS.has(token))
+}
+
+function inferCommitTypeFromEntries(statusEntries = []) {
+  const paths = statusEntries.map((entry) => entry.path.toLowerCase())
+
+  if (paths.every((pathValue) => pathValue.endsWith('.md') || pathValue.includes('/docs/') || pathValue.startsWith('docs/'))) {
+    return 'docs'
+  }
+
+  if (paths.every((pathValue) => /\.test\.[^.]+$/.test(pathValue) || pathValue.includes('/tests/'))) {
+    return 'test'
+  }
+
+  if (paths.some((pathValue) => pathValue.includes('.github/workflows/') || pathValue.includes('/ci/'))) {
+    return 'ci'
+  }
+
+  return 'chore'
+}
+
+export function parseWorkingTreeStatus(stdout = '') {
+  return stdout
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+}
+
+export function parseWorkingTreeEntries(stdout = '') {
+  return parseWorkingTreeStatus(stdout).map((line) => {
+    const indexStatus = line.slice(0, 1)
+    const worktreeStatus = line.slice(1, 2)
+    const rawPath = line.slice(3).trim()
+    const isRename = [indexStatus, worktreeStatus].some((status) => status === 'R' || status === 'C')
+    const [fromPath, toPath] = isRename && rawPath.includes(' -> ')
+      ? rawPath.split(' -> ')
+      : [null, null]
+
+    return {
+      raw: line,
+      indexStatus,
+      worktreeStatus,
+      path: toPath ?? rawPath,
+      previousPath: fromPath
+    }
+  })
+}
+
+export function summarizeWorkingTreeEntry(entry, {
+  changeCountsByPath = new Map()
+} = {}) {
+  const label = resolveWorkingTreeEntryLabel(entry)
+  const displayPath = entry.previousPath ? `${entry.previousPath} -> ${entry.path}` : entry.path
+  const counts = changeCountsByPath.get(entry.path) ?? null
+
+  if (!counts) {
+    return `${label}: ${displayPath}`
+  }
+
+  return `${label}: ${displayPath} (+${counts.added} -${counts.deleted})`
+}
+
+export function formatWorkingTreePreview(statusEntries = []) {
+  const preview = statusEntries
+    .slice(0, MAX_WORKING_TREE_PREVIEW)
+    .map((entry) => `  ${summarizeWorkingTreeEntry(entry)}`)
+    .join('\n')
+
+  if (statusEntries.length <= MAX_WORKING_TREE_PREVIEW) {
+    return preview
+  }
+
+  const remaining = statusEntries.length - MAX_WORKING_TREE_PREVIEW
+  return `${preview}\n  ...and ${remaining} more file${remaining === 1 ? '' : 's'}`
+}
+
+export function sanitizeSuggestedCommitMessage(message) {
+  if (typeof message !== 'string') {
+    return null
+  }
+
+  const firstLine = message
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean)
+
+  if (!firstLine) {
+    return null
+  }
+
+  const normalized = firstLine
+    .replace(/^commit message:\s*/i, '')
+    .replace(/^(\w+)\([^)]+\)(!?):/i, '$1:')
+    .replace(/^(\w+)!:/i, '$1:')
+    .replace(/^["'`]+|["'`]+$/g, '')
+    .trim()
+
+  if (!CONVENTIONAL_COMMIT_PATTERN.test(normalized)) {
+    return null
+  }
+
+  const [, subject = ''] = normalized.split(/:\s+/, 2)
+  const normalizedSubject = subject.trim()
+
+  if (
+    normalizedSubject.length < 18 ||
+    normalizedSubject.split(/\s+/).length < 3 ||
+    GENERIC_SUBJECT_PATTERNS.some((pattern) => pattern.test(normalizedSubject))
+  ) {
+    return null
+  }
+
+  return normalized
+}
+
+export function buildFallbackCommitMessage(statusEntries = []) {
+  const tokenCounts = new Map()
+
+  for (const entry of statusEntries) {
+    for (const token of tokenizePath(entry.path)) {
+      tokenCounts.set(token, (tokenCounts.get(token) ?? 0) + 1)
+    }
+  }
+
+  const orderedTokens = Array.from(tokenCounts.entries())
+    .sort((left, right) => {
+      if (right[1] !== left[1]) {
+        return right[1] - left[1]
+      }
+
+      return left[0].localeCompare(right[0])
+    })
+    .map(([token]) => token)
+
+  const primaryTopic = orderedTokens[0] ?? 'release'
+  const commitType = inferCommitTypeFromEntries(statusEntries)
+
+  if (commitType === 'docs') {
+    return `docs: update ${primaryTopic} documentation`
+  }
+
+  if (commitType === 'test') {
+    return `test: expand ${primaryTopic} coverage`
+  }
+
+  if (commitType === 'ci') {
+    return `ci: update ${primaryTopic} workflow`
+  }
+
+  return `chore: improve ${primaryTopic} workflow`
+}
+
+async function collectDiffNumstat(rootDir, {runCommand} = {}) {
+  try {
+    const {stdout} = await runCommand('git', ['diff', '--numstat', 'HEAD', '--'], {
+      capture: true,
+      cwd: rootDir
+    })
+
+    return stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .reduce((map, line) => {
+        const [addedRaw, deletedRaw, filePath] = line.split('\t')
+        if (!filePath) {
+          return map
+        }
+
+        const added = Number.parseInt(addedRaw, 10)
+        const deleted = Number.parseInt(deletedRaw, 10)
+        map.set(filePath, {
+          added: Number.isFinite(added) ? added : 0,
+          deleted: Number.isFinite(deleted) ? deleted : 0
+        })
+        return map
+      }, new Map())
+  } catch {
+    return new Map()
+  }
+}
+
+async function buildCommitMessageContext(rootDir, {
+  runCommand,
+  statusEntries = []
+} = {}) {
+  const changeCountsByPath = await collectDiffNumstat(rootDir, {runCommand})
+  return statusEntries.map((entry) => `- ${summarizeWorkingTreeEntry(entry, {changeCountsByPath})}`).join('\n')
+}
+
+export async function suggestReleaseCommitMessage(rootDir = process.cwd(), {
+  runCommand,
+  commandExistsImpl = commandExists,
+  logStep,
+  logWarning,
+  statusEntries = []
+} = {}) {
+  if (!commandExistsImpl('codex')) {
+    return null
+  }
+
+  let tempDir = null
+
+  try {
+    tempDir = await mkdtemp(path.join(tmpdir(), 'zephyr-release-commit-'))
+    const outputPath = path.join(tempDir, 'codex-last-message.txt')
+    const commitContext = await buildCommitMessageContext(rootDir, {
+      runCommand,
+      statusEntries
+    })
+
+    logStep?.('Generating a suggested commit message with Codex...')
+
+    await runCommand('codex', [
+      'exec',
+      '--ephemeral',
+      '--model',
+      'gpt-5.4-mini',
+      '--sandbox',
+      'read-only',
+      '--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.',
+        'Pending change summary:',
+        commitContext || '- changed files present'
+      ].join('\n\n')
+    ], {
+      capture: true,
+      cwd: rootDir
+    })
+
+    const rawMessage = await readFile(outputPath, 'utf8')
+    return sanitizeSuggestedCommitMessage(rawMessage)
+  } catch (error) {
+    logWarning?.(`Codex could not suggest a commit message: ${error.message}`)
+    return null
+  } finally {
+    if (tempDir) {
+      await rm(tempDir, {recursive: true, force: true}).catch(() => {})
+    }
+  }
+}

package/src/release/shared.mjs

@@ -1,13 +1,21 @@
 import inquirer from 'inquirer'
 import process from 'node:process'
 
-import { validateLocalDependencies } from '../dependency-scanner.mjs'
-import { runCommand as runCommandBase, runCommandCapture as runCommandCaptureBase } from '../utils/command.mjs'
+import {validateLocalDependencies} from '../dependency-scanner.mjs'
+import {runCommand as runCommandBase, runCommandCapture as runCommandCaptureBase} from '../utils/command.mjs'
+import {gitCommitArgs} from '../utils/git-hooks.mjs'
 import {
   ensureUpToDateWithUpstream,
   getCurrentBranch,
   getUpstreamRef
 } from '../utils/git.mjs'
+import {
+  buildFallbackCommitMessage,
+  formatWorkingTreePreview,
+  parseWorkingTreeEntries,
+  parseWorkingTreeStatus,
+  suggestReleaseCommitMessage
+} from './commit-message.mjs'
 
 const RELEASE_TYPES = new Set([
   'major',
@@ -18,6 +26,8 @@ const RELEASE_TYPES = new Set([
   'prepatch',
   'prerelease'
 ])
+const DIRTY_WORKING_TREE_MESSAGE = 'Working tree has uncommitted changes. Commit or stash them before releasing.'
+const DIRTY_WORKING_TREE_CANCELLED_MESSAGE = 'Release cancelled: pending changes were not committed.'
 
 function flagToKey(flag) {
   return flag
@@ -60,7 +70,7 @@ export function parseReleaseArgs({
     booleanFlags.map((flag) => [flagToKey(flag), presentFlags.has(flag)])
   )
 
-  return { releaseType, ...parsedFlags }
+  return {releaseType, ...parsedFlags}
 }
 
 export async function runReleaseCommand(command, args, {
@@ -70,32 +80,103 @@ export async function runReleaseCommand(command, args, {
   runCommandCaptureImpl = runCommandCaptureBase
 } = {}) {
   if (capture) {
-    const captured = await runCommandCaptureImpl(command, args, { cwd })
+    const captured = await runCommandCaptureImpl(command, args, {cwd})
 
     if (typeof captured === 'string') {
-      return { stdout: captured.trim(), stderr: '' }
+      return {stdout: captured.trim(), stderr: ''}
     }
 
     const stdout = captured?.stdout ?? ''
     const stderr = captured?.stderr ?? ''
-    return { stdout: stdout.trim(), stderr: stderr.trim() }
+    return {stdout: stdout.trim(), stderr: stderr.trim()}
   }
 
-  await runCommandImpl(command, args, { cwd })
+  await runCommandImpl(command, args, {cwd})
   return undefined
 }
 
 export async function ensureCleanWorkingTree(rootDir = process.cwd(), {
-  runCommand = runReleaseCommand
+  runCommand = runReleaseCommand,
+  runPrompt,
+  logStep,
+  logSuccess,
+  logWarning,
+  interactive = true,
+  skipGitHooks = false,
+  suggestCommitMessage = suggestReleaseCommitMessage
 } = {}) {
-  const { stdout } = await runCommand('git', ['status', '--porcelain'], {
+  const {stdout} = await runCommand('git', ['status', '--porcelain'], {
     capture: true,
     cwd: rootDir
   })
+  const statusEntries = parseWorkingTreeEntries(stdout)
 
-  if (stdout.length > 0) {
-    throw new Error('Working tree has uncommitted changes. Commit or stash them before releasing.')
+  if (statusEntries.length === 0) {
+    return
   }
+
+  if (!interactive || typeof runPrompt !== 'function') {
+    throw new Error(DIRTY_WORKING_TREE_MESSAGE)
+  }
+
+  const suggestedCommitMessage = await suggestCommitMessage(rootDir, {
+    runCommand,
+    logStep,
+    logWarning,
+    statusEntries
+  }) ?? buildFallbackCommitMessage(statusEntries)
+
+  const changeLabel = statusEntries.length === 1 ? 'change' : 'changes'
+  const {shouldCommitPendingChanges} = await runPrompt([
+    {
+      type: 'confirm',
+      name: 'shouldCommitPendingChanges',
+      message:
+        `Pending ${changeLabel} detected before release:\n\n` +
+        `${formatWorkingTreePreview(statusEntries)}\n\n` +
+        'Stage and commit all current changes before continuing?',
+      default: true
+    }
+  ])
+
+  if (!shouldCommitPendingChanges) {
+    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...')
+  await runCommand('git', ['add', '-A'], {
+    capture: true,
+    cwd: rootDir
+  })
+
+  logStep?.('Committing pending changes before release...')
+  await runCommand('git', gitCommitArgs(['-m', message], {skipGitHooks}), {
+    capture: true,
+    cwd: rootDir
+  })
+
+  const {stdout: finalStatus} = await runCommand('git', ['status', '--porcelain'], {
+    capture: true,
+    cwd: rootDir
+  })
+
+  if (parseWorkingTreeStatus(finalStatus).length > 0) {
+    throw new Error('Working tree still has uncommitted changes after the release commit. Commit or stash them before releasing.')
+  }
+
+  logSuccess?.(`Committed pending changes with "${message}".`)
 }
 
 export async function validateReleaseDependencies(rootDir = process.cwd(), {
@@ -119,7 +200,7 @@ export async function ensureReleaseBranchReady({
   logStep,
   logWarning
 } = {}) {
-  const branch = await getCurrentBranchImpl(rootDir, { method: branchMethod })
+  const branch = await getCurrentBranchImpl(rootDir, {method: branchMethod})
 
   if (!branch) {
     throw new Error('Unable to determine current branch.')
@@ -128,7 +209,9 @@ export async function ensureReleaseBranchReady({
   logStep?.(`Current branch: ${branch}`)
 
   const upstreamRef = await getUpstreamRefImpl(rootDir)
-  await ensureUpToDateWithUpstreamImpl({ branch, upstreamRef, rootDir, logStep, logWarning })
+  await ensureUpToDateWithUpstreamImpl({branch, upstreamRef, rootDir, logStep, logWarning})
 
-  return { branch, upstreamRef }
+  return {branch, upstreamRef}
 }
+
+export {suggestReleaseCommitMessage}

package/src/runtime/app-context.mjs

@@ -1,3 +1,4 @@
+import process from 'node:process'
 import chalk from 'chalk'
 import inquirer from 'inquirer'
 import {NodeSSH} from 'node-ssh'
@@ -12,6 +13,7 @@ export function createAppContext({
                                      chalkInstance = chalk,
                                      inquirerInstance = inquirer,
                                      NodeSSHClass = NodeSSH,
+                                     processInstance = process,
                                      runCommandImpl = runCommandBase,
                                      runCommandCaptureImpl = runCommandCaptureBase,
                                      executionMode = {}
@@ -38,6 +40,7 @@ export function createAppContext({
         emitEvent,
         workflow: normalizedExecutionMode.workflow
     })
+    const hasInteractiveTerminal = Boolean(processInstance?.stdin?.isTTY && processInstance?.stdout?.isTTY)
     const createSshClient = createSshClientFactory({NodeSSH: NodeSSHClass})
     const {runCommand, runCommandCapture} = createLocalCommandRunners({
         runCommandBase: runCommandImpl,
@@ -59,6 +62,7 @@ export function createAppContext({
         runCommand: runCommandWithMode,
         runCommandCapture,
         emitEvent,
+        hasInteractiveTerminal,
         executionMode: normalizedExecutionMode
     }
 }