@wyxos/zephyr 0.4.6 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyxos/zephyr",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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/prepare-local-deployment.mjs

@@ -1,6 +1,6 @@
 import process from 'node:process'
 
-import {ensureLocalRepositoryState} from '../../deploy/local-repo.mjs'
+import {ensureCommittedChangesPushed, ensureLocalRepositoryState} from '../../deploy/local-repo.mjs'
 import {bumpLocalPackageVersion} from './bump-local-package-version.mjs'
 import {resolveLocalDeploymentContext} from './resolve-local-deployment-context.mjs'
 import {resolveLocalDeploymentCheckSupport, runLocalDeploymentChecks} from './run-local-deployment-checks.mjs'
@@ -17,6 +17,16 @@ export async function prepareLocalDeployment(config, {
     logSuccess,
     logWarning
 } = {}) {
+    await ensureLocalRepositoryState(config.branch, rootDir, {
+        runPrompt,
+        runCommand,
+        runCommandCapture,
+        logProcessing,
+        logSuccess,
+        logWarning,
+        skipGitHooks
+    })
+
     const context = await resolveLocalDeploymentContext(rootDir)
     const checkSupport = await resolveLocalDeploymentCheckSupport({
         rootDir,
@@ -33,17 +43,16 @@ export async function prepareLocalDeployment(config, {
             logSuccess,
             logWarning
         })
-    }
 
-    await ensureLocalRepositoryState(config.branch, rootDir, {
-        runPrompt,
-        runCommand,
-        runCommandCapture,
-        logProcessing,
-        logSuccess,
-        logWarning,
-        skipGitHooks
-    })
+        await ensureCommittedChangesPushed(config.branch, rootDir, {
+            runCommand,
+            runCommandCapture,
+            logProcessing,
+            logSuccess,
+            logWarning,
+            skipGitHooks
+        })
+    }
 
     await runLocalDeploymentChecks({
         rootDir,

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/deploy/local-repo.mjs

@@ -1,6 +1,15 @@
 import { getCurrentBranch as getCurrentBranchImpl, getUpstreamRef as getUpstreamRefImpl } from '../utils/git.mjs'
 import {hasPrePushHook} from './preflight.mjs'
 import {gitCommitArgs, gitPushArgs} from '../utils/git-hooks.mjs'
+import {
+  buildFallbackCommitMessage,
+  formatWorkingTreePreview,
+  parseWorkingTreeEntries,
+  suggestCommitMessage as suggestCommitMessageImpl
+} from '../release/commit-message.mjs'
+
+const DIRTY_DEPLOYMENT_MESSAGE = 'Local repository has uncommitted changes. Commit or stash them before deployment.'
+const DIRTY_DEPLOYMENT_CANCELLED_MESSAGE = 'Deployment cancelled: pending changes were not committed.'
 
 export async function getCurrentBranch(rootDir) {
   const branch = await getCurrentBranchImpl(rootDir)
@@ -161,27 +170,84 @@ async function checkoutTargetBranch(targetBranch, currentBranch, rootDir, {
   logSuccess?.(`Checked out ${targetBranch} locally.`)
 }
 
-async function commitAndPushStagedChanges(targetBranch, rootDir, {
+async function commitAndPushPendingChanges(targetBranch, rootDir, {
   runPrompt,
   runCommand,
+  runCommandCapture,
   getGitStatus,
   logProcessing,
   logSuccess,
   logWarning,
-  skipGitHooks = false
+  skipGitHooks = false,
+  suggestCommitMessage = suggestCommitMessageImpl
 } = {}) {
+  const statusEntries = parseWorkingTreeEntries(await getGitStatus(rootDir))
+
+  if (statusEntries.length === 0) {
+    return
+  }
+
+  if (typeof runPrompt !== 'function') {
+    throw new Error(DIRTY_DEPLOYMENT_MESSAGE)
+  }
+
+  const captureAwareRunCommand = async (command, args, { capture = false, cwd } = {}) => {
+    if (capture) {
+      const captured = await runCommandCapture(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 runCommand(command, args, { cwd })
+    return undefined
+  }
+
+  const suggestedCommitMessage = await suggestCommitMessage(rootDir, {
+    runCommand: captureAwareRunCommand,
+    logStep: logProcessing,
+    logWarning,
+    statusEntries
+  }) ?? buildFallbackCommitMessage(statusEntries)
+
+  const changeLabel = statusEntries.length === 1 ? 'change' : 'changes'
+  const {shouldCommitPendingChanges} = await runPrompt([
+    {
+      type: 'confirm',
+      name: 'shouldCommitPendingChanges',
+      message:
+        `Pending ${changeLabel} detected before deployment:\n\n` +
+        `${formatWorkingTreePreview(statusEntries)}\n\n` +
+        'Stage and commit all current changes before continuing?',
+      default: true
+    }
+  ])
+
+  if (!shouldCommitPendingChanges) {
+    throw new Error(DIRTY_DEPLOYMENT_CANCELLED_MESSAGE)
+  }
+
   const { commitMessage } = await runPrompt([
     {
       type: 'input',
       name: 'commitMessage',
-      message: 'Enter a commit message for pending changes before deployment',
+      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?.('Committing staged changes before deployment...')
+  logProcessing?.('Staging all pending changes before deployment...')
+  await runCommand('git', ['add', '-A'], { cwd: rootDir })
+
+  logProcessing?.('Committing pending changes before deployment...')
   await runCommand('git', gitCommitArgs(['-m', message], {skipGitHooks}), { cwd: rootDir })
 
   const prePushHookPresent = await hasPrePushHook(rootDir)
@@ -203,7 +269,8 @@ async function commitAndPushStagedChanges(targetBranch, rootDir, {
     throw error
   }
 
-  logSuccess?.(`Committed and pushed changes to origin/${targetBranch}.`)
+  logSuccess?.(`Committed pending changes with "${message}".`)
+  logSuccess?.(`Pushed committed changes to origin/${targetBranch}.`)
 
   const finalStatus = await getGitStatus(rootDir)
 
@@ -303,6 +370,7 @@ export async function ensureLocalRepositoryState(targetBranch, rootDir = process
   logSuccess,
   logWarning,
   skipGitHooks = false,
+  suggestCommitMessage: suggestCommitMessageFn = suggestCommitMessageImpl,
   getCurrentBranch: getCurrentBranchFn = getCurrentBranch,
   getGitStatus: getGitStatusFn = (dir) => getGitStatus(dir, { runCommandCapture }),
   readUpstreamSyncState: readUpstreamSyncStateFn = (branch, dir) =>
@@ -371,21 +439,17 @@ export async function ensureLocalRepositoryState(targetBranch, rootDir = process
     return
   }
 
-  if (!hasStagedChanges(statusAfterCheckout)) {
-    await ensureCommittedChangesPushedFn(targetBranch, rootDir)
-    logProcessing?.('No staged changes detected. Unstaged or untracked files will not affect deployment. Proceeding with deployment.')
-    return
-  }
-
-  logWarning?.(`Staged changes detected on ${targetBranch}. A commit is required before deployment.`)
-  await commitAndPushStagedChanges(targetBranch, rootDir, {
+  logWarning?.(`Pending changes detected on ${targetBranch}. A commit is required before deployment.`)
+  await commitAndPushPendingChanges(targetBranch, rootDir, {
     runPrompt,
     runCommand,
+    runCommandCapture,
     getGitStatus: getGitStatusFn,
     logProcessing,
     logSuccess,
     logWarning,
-    skipGitHooks
+    skipGitHooks,
+    suggestCommitMessage: suggestCommitMessageFn
   })
 
   await ensureCommittedChangesPushedFn(targetBranch, rootDir)

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/release/commit-message.mjs

@@ -0,0 +1,367 @@
+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 pending changes before .+$/i,
+  /^commit pending (release |deployment )?changes before .+$/i,
+  /^commit (all )?(current |pending )?changes( before .+)?$/i,
+  /^stage and commit (all )?(current |pending )?changes( before .+)?$/i,
+  /^(allow|enable|support) committing pending changes( before .+)?$/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',
+  'local',
+  'repo',
+  'prepare',
+  'commit',
+  'message',
+  'js',
+  'jsx',
+  'ts',
+  'tsx',
+  'mjs',
+  'cjs',
+  'php',
+  'json',
+  'yaml',
+  'yml',
+  'md',
+  'toml',
+  'lock'
+])
+
+function buildTargetedFallbackCommitMessage(statusEntries = []) {
+  const paths = statusEntries.map((entry) => entry.path.toLowerCase())
+  const touchesDeployPrep = paths.some((pathValue) => pathValue.includes('prepare-local-deployment'))
+  const touchesLocalRepo = paths.some((pathValue) => pathValue.includes('local-repo'))
+  const touchesCommitMessage = paths.some((pathValue) => pathValue.includes('commit-message'))
+  const touchesReleaseFlow = paths.some((pathValue) => pathValue.includes('/release/') || pathValue.includes('release-'))
+
+  if (touchesDeployPrep && touchesLocalRepo) {
+    return 'fix: prompt for dirty deploy changes before version bump'
+  }
+
+  if (touchesCommitMessage && touchesReleaseFlow) {
+    return 'fix: tighten release commit suggestions'
+  }
+
+  return null
+}
+
+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 targetedFallback = buildTargetedFallbackCommitMessage(statusEntries)
+  if (targetedFallback) {
+    return targetedFallback
+  }
+
+  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 suggestCommitMessage(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.',
+        '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')
+    ], {
+      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(() => {})
+    }
+  }
+}
+
+export {suggestCommitMessage as suggestReleaseCommitMessage}

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}