maiass 5.13.0 → 5.14.2

package/lib/arg-utils.js

@@ -0,0 +1,54 @@
+// Pure argv parsing helpers shared between maiass.mjs and unit tests.
+//
+// Kept dependency-free and side-effect-free so it can be imported in a unit
+// test without triggering maiass.mjs's top-level CLI bootstrap.
+
+/**
+ * Extract the -m / --message commit-message value from argv (MAI-51 parity).
+ *
+ * Supported forms (single value only — NOT git-style repeated -m):
+ *   -m <value>
+ *   --message <value>
+ *   --message=<value>
+ *
+ * The value is taken VERBATIM (no escape-sequence interpretation, no newline
+ * collapsing). Only the whole-string leading/trailing whitespace is trimmed,
+ * and that trimming happens at the point of use (lib/commit.js) so that empty /
+ * whitespace-only values still fall through to the "No commit message provided"
+ * path. Here we return the raw string.
+ *
+ * Last occurrence wins if the flag appears more than once.
+ *
+ * @param {string[]} argv
+ * @returns {{ message: string|null, valueIndices: Set<number> }}
+ *   message      — the raw message string, or null if -m/--message not present.
+ *   valueIndices — argv positions of the VALUE token only (the space-separated
+ *                  form's value). The flag tokens (-m/--message) are NOT included
+ *                  because (a) they start with '-' so command derivation already
+ *                  skips them, and (b) the flag-validator still needs to validate
+ *                  them against the allow-list. The value token is recorded so
+ *                  command derivation doesn't mistake it for a command/bump type
+ *                  and so the validator skips it if it happens to start with '-'.
+ */
+export function extractMessageFlag(argv) {
+  let message = null;
+  const valueIndices = new Set();
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '-m' || arg === '--message') {
+      if (i + 1 < argv.length) {
+        message = argv[i + 1];
+        valueIndices.add(i + 1);
+      } else {
+        // Flag given with no following token — treat as empty so it falls
+        // through to the "No commit message provided" error rather than
+        // silently consuming nothing.
+        message = '';
+      }
+    } else if (arg.startsWith('--message=')) {
+      message = arg.slice('--message='.length);
+      valueIndices.add(i);
+    }
+  }
+  return { message, valueIndices };
+}

package/lib/bootstrap.js

@@ -612,6 +612,11 @@ MAIASS_STAGINGBRANCH=${config.branches.staging}
 
 # Example: Personal debug settings
 #MAIASS_DEBUG=true
+
+# Example: devlog tagging (optional)
+#MAIASS_DEVLOG_CLIENT="yourclient"
+#MAIASS_DEVLOG_SUBCLIENT=""
+#MAIASS_DEVLOG_PROJECT="yourproject"
 `;
     fs.writeFileSync('.env.maiass.local', localContent, 'utf8');
     log.success(SYMBOLS.CHECKMARK, 'Created .env.maiass.local for personal settings');

package/lib/commit.js

@@ -16,6 +16,45 @@ import { logCommit } from './devlog.js';
 import colors from './colors.js';
 import chalk from 'chalk';
 
+/**
+ * Pick the AI model used for commit message generation.
+ *
+ * Resolution order:
+ *  1. MAIASS_AI_COMMIT_MODEL — explicit per-commit override. Wins absolutely.
+ *  2. MAIASS_AI_MODEL — legacy global override. Preserves prior behaviour for
+ *     users who configured it explicitly.
+ *  3. Auto-pick by diff size (post-truncation char count of the staged diff
+ *     that will actually be sent to the model):
+ *       <  30000 chars  -> gpt-4o-mini   (tier 1)
+ *       30000..100000   -> gpt-4-turbo   (tier 2)
+ *       > 100000        -> gpt-4o        (tier 3)
+ *
+ * In practice MAIASS_AI_MAX_CHARACTERS defaults to 8000, so tier 1 is the
+ * common case. Tiers 2 and 3 only fire when a user has raised that cap. The
+ * ladder is forward-compatible with future increases.
+ *
+ * Returns { model, tier, source } where source is 'override' | 'legacy' |
+ * 'auto', and tier is 1/2/3 (only meaningful when source === 'auto').
+ */
+export function pickCommitModel(diffLength, env = process.env) {
+  const override = env.MAIASS_AI_COMMIT_MODEL;
+  if (override && override.trim()) {
+    return { model: override.trim(), tier: null, source: 'override' };
+  }
+  const legacy = env.MAIASS_AI_MODEL;
+  if (legacy && legacy.trim()) {
+    return { model: legacy.trim(), tier: null, source: 'legacy' };
+  }
+  const len = typeof diffLength === 'number' && diffLength >= 0 ? diffLength : 0;
+  if (len < 30000) {
+    return { model: 'gpt-4o-mini', tier: 1, source: 'auto' };
+  }
+  if (len <= 100000) {
+    return { model: 'gpt-4-turbo', tier: 2, source: 'auto' };
+  }
+  return { model: 'gpt-4o', tier: 3, source: 'auto' };
+}
+
 /**
  * Simple spinner for AI API calls
  */
@@ -291,7 +330,8 @@ async function getAICommitSuggestion(gitInfo) {
   const aiHost = process.env.MAIASS_AI_HOST || 'https://pound.maiass.net';
   const aiPath = process.env.MAIASS_AI_PATH || '/proxy';
   const aiEndpoint = aiHost + aiPath;
-  const aiModel = process.env.MAIASS_AI_MODEL || 'gpt-3.5-turbo';
+  // aiModel is resolved AFTER the diff is collected and truncated — the
+  // auto-pick layer needs the final diff size. See pickCommitModel() below.
   const aiTemperature = parseFloat(process.env.MAIASS_AI_TEMPERATURE || '0.7');
   const commitMessageStyle = process.env.MAIASS_AI_COMMIT_MESSAGE_STYLE || 'bullet';
   const maxCharacters = parseInt(process.env.MAIASS_AI_MAX_CHARACTERS || '8000');
@@ -372,7 +412,29 @@ async function getAICommitSuggestion(gitInfo) {
       log.info(SYMBOLS.INFO, `Git diff truncated to ${maxCharacters} characters`);
     }
 
+    // Pick the AI model AFTER truncation — the auto-pick layer reads the final
+    // diff size that will actually be sent to the model. MAIASS_AI_COMMIT_MODEL
+    // overrides everything; MAIASS_AI_MODEL is the legacy fallback; otherwise
+    // we ladder based on diff length.
+    const modelPick = pickCommitModel(gitDiff.length);
+    const aiModel = modelPick.model;
+
     if (debugMode) {
+      let pickSummary;
+      if (modelPick.source === 'override') {
+        pickSummary = `[MAIASS DEBUG] AI commit model: ${aiModel} (override via MAIASS_AI_COMMIT_MODEL)`;
+      } else if (modelPick.source === 'legacy') {
+        pickSummary = `[MAIASS DEBUG] AI commit model: ${aiModel} (legacy MAIASS_AI_MODEL)`;
+      } else {
+        const ranges = {
+          1: '< 30000',
+          2: '30000-100000',
+          3: '> 100000'
+        };
+        pickSummary = `[MAIASS DEBUG] AI commit model: ${aiModel} (tier ${modelPick.tier}, diff ${gitDiff.length} chars, threshold ${ranges[modelPick.tier]})`;
+      }
+      log.debug(SYMBOLS.INFO, pickSummary);
+
       log.debug(SYMBOLS.INFO, '[MAIASS DEBUG] --- AI Commit Suggestion Context ---');
       log.debug(SYMBOLS.INFO, `[MAIASS DEBUG] Model: ${aiModel}`);
       log.debug(SYMBOLS.INFO, `[MAIASS DEBUG] Temperature: ${aiTemperature}`);
@@ -628,20 +690,47 @@ async function getMultiLineCommitMessage(jiraTicket) {
  * @returns {Promise<string>} Final commit message
  */
 async function getCommitMessage(gitInfo, options = {}) {
-  const { silent = false } = options;
-  
+  const { silent = false, providedMessage = null } = options;
+
   // Load environment config to ensure tokens are loaded from secure storage
   loadEnvironmentConfig();
-  
+
   const aiMode = process.env.MAIASS_AI_MODE || 'ask';
   const maiassToken = process.env.MAIASS_AI_TOKEN;
   const jiraTicket = gitInfo.jiraTicket;
-  
+
   // Display JIRA ticket if found
   if (jiraTicket) {
     log.info(SYMBOLS.INFO, `Jira Ticket Number: ${jiraTicket}`);
   }
-  
+
+  // -m / --message: verbatim, non-interactive commit message (MAI-XX parity).
+  //
+  // When supplied, this short-circuits BEFORE any AI proxy call and before any
+  // interactive prompt — so it works with no token and no credit, and never
+  // hits the network. The message is used EXACTLY as given except for trimming
+  // leading/trailing whitespace of the whole string: internal newlines,
+  // indentation and blank lines are preserved verbatim (do NOT reformat — the
+  // canonical "title\n  - bullet" layout with no blank line between title and
+  // bullets must survive intact for changelog parsing). Escape sequences are
+  // NOT interpreted (a literal "\n" stays literal).
+  //
+  // Empty / whitespace-only → return '' so the caller emits the existing
+  // "No commit message provided" error and does not commit.
+  if (providedMessage !== null && providedMessage !== undefined) {
+    const trimmed = providedMessage.trim();
+    if (!trimmed) {
+      return '';
+    }
+    // Prepend the Jira ticket if detected and not already present (matches the
+    // AI / manual paths). The caller (handleStagedCommit) also guards against
+    // double-prepend via startsWith, so this is idempotent.
+    if (jiraTicket && !trimmed.startsWith(jiraTicket)) {
+      return `${jiraTicket} ${trimmed}`;
+    }
+    return trimmed;
+  }
+
   let useAI = false;
   let aiSuggestion = null;
   
@@ -787,27 +876,34 @@ async function getCommitMessage(gitInfo, options = {}) {
  * @returns {Promise<boolean>} True if commit was successful
  */
 async function handleStagedCommit(gitInfo, options = {}) {
-  const { silent = false } = options;
-  // Check if there are actually staged changes
-  if (!gitInfo.status || gitInfo.status.stagedCount === 0) {
+  const { silent = false, dryRun = false, forceStaged = false, providedMessage = null } = options;
+  // Check if there are actually staged changes.
+  // In dry-run with forceStaged, nothing was really staged (the `git add` was
+  // only previewed), so skip this guard — the working-tree changes are what
+  // *would* be committed.
+  if (!forceStaged && (!gitInfo.status || gitInfo.status.stagedCount === 0)) {
     log.warning(SYMBOLS.INFO, 'Nothing to commit, working tree clean');
     return true;
   }
-  
-  // Show staged changes
-  const stagedOutput = executeGitCommand('git diff --cached --name-status', true);
+
+  // Show the changes that are (or would be) committed. For a forced dry run
+  // nothing is actually staged, so preview the working-tree changes instead.
+  const diffCommand = forceStaged
+    ? 'git diff HEAD --name-status'
+    : 'git diff --cached --name-status';
+  const stagedOutput = executeGitCommand(diffCommand, true);
   if (!stagedOutput) {
     log.warning(SYMBOLS.INFO, 'No staged changes to show');
     return true;
   }
-  
-  log.critical(SYMBOLS.INFO, 'Staged changes detected:');
-  
+
+  log.critical(SYMBOLS.INFO, forceStaged ? 'Changes that would be committed:' : 'Staged changes detected:');
+
   // Display the staged changes
   console.log(stagedOutput);
-  
+
   // Get commit message
-  const commitMessage = await getCommitMessage(gitInfo, { silent });
+  const commitMessage = await getCommitMessage(gitInfo, { silent, providedMessage });
   if (!commitMessage) {
     log.error(SYMBOLS.CROSS, 'No commit message provided');
     return false;
@@ -826,24 +922,28 @@ async function handleStagedCommit(gitInfo, options = {}) {
     if (jiraTicket && finalCommitMessage && !finalCommitMessage.startsWith(jiraTicket)) {
       finalCommitMessage = `${jiraTicket} ${finalCommitMessage}`;
     }
-    // Write commit message to a temp file on all platforms — avoids shell quoting and injection risks
-    {
+    if (dryRun) {
+      // Preview the commit instead of performing it
+      const previewMessage = finalCommitMessage.split('\n')[0];
+      console.log(colors.BBlue(`${SYMBOLS.INFO} Dry run - would commit with message: "${previewMessage}"`));
+    } else {
+      // Write commit message to a temp file on all platforms — avoids shell quoting and injection risks
       const tmpFile = path.join(os.tmpdir(), `maiass-commit-msg-${Date.now()}.txt`);
       fs.writeFileSync(tmpFile, finalCommitMessage, { encoding: 'utf8' });
       result = executeGitCommand(`git commit -F "${tmpFile}"`, quietMode);
       fs.unlinkSync(tmpFile);
+
+      if (result === null) {
+        log.error(SYMBOLS.CROSS, 'Commit failed');
+        return false;
+      }
+
+      log.success(SYMBOLS.CHECKMARK, 'Changes committed successfully');
+
+      // Log the commit to devlog.sh (equivalent to logthis in maiass.sh)
+      logCommit(commitMessage, gitInfo);
     }
-    
-    if (result === null) {
-      log.error(SYMBOLS.CROSS, 'Commit failed');
-      return false;
-    }
-    
-    log.success(SYMBOLS.CHECKMARK, 'Changes committed successfully');
-    
-    // Log the commit to devlog.sh (equivalent to logthis in maiass.sh)
-    logCommit(commitMessage, gitInfo);
-    
+
     // Ask about pushing to remote
     if (remoteExists('origin')) {
       let reply;
@@ -872,13 +972,17 @@ async function handleStagedCommit(gitInfo, options = {}) {
       }
       
       if (reply === 'y') {
-        
-        const pushResult = executeGitCommand(`git push --set-upstream origin ${gitInfo.branch}`, false);
-        if (pushResult !== null) {
-          log.success(SYMBOLS.CHECKMARK, 'Commit pushed.');
+        if (dryRun) {
+          // Preview the push instead of performing it
+          console.log(colors.BBlue(`${SYMBOLS.INFO} Dry run - would push to origin ${gitInfo.branch} (git push --set-upstream origin ${gitInfo.branch})`));
         } else {
-          log.error(SYMBOLS.CROSS, 'Push failed');
-          return false;
+          const pushResult = executeGitCommand(`git push --set-upstream origin ${gitInfo.branch}`, false);
+          if (pushResult !== null) {
+            log.success(SYMBOLS.CHECKMARK, 'Commit pushed.');
+          } else {
+            log.error(SYMBOLS.CROSS, 'Push failed');
+            return false;
+          }
         }
       }
     } else {
@@ -898,7 +1002,7 @@ async function handleStagedCommit(gitInfo, options = {}) {
  * @returns {Promise<boolean>} True if process completed successfully
  */
 export async function commitThis(options = {}) {
-  const { autoStage = false, commitsOnly = false, silent = false } = options;
+  const { autoStage = false, commitsOnly = false, silent = false, dryRun = false, providedMessage = null } = options;
   
   // Get git information
   const gitInfo = getGitInfo();
@@ -947,21 +1051,26 @@ export async function commitThis(options = {}) {
         reply = await getSingleCharInput('Do you want to stage and commit them? [y/N] ');
       }
       if (reply === 'y') {
+        if (dryRun) {
+          // Preview the stage instead of performing it
+          console.log(colors.BBlue(`${SYMBOLS.INFO} Dry run - would stage all changes (git add -A)`));
+          return await handleStagedCommit(gitInfo, { silent, dryRun, forceStaged: true, providedMessage });
+        }
         // Stage all changes
         const stageResult = executeGitCommand('git add -A', false);
         if (stageResult === null) {
           log.error(SYMBOLS.CROSS, 'Failed to stage changes');
           return false;
         }
-        
+
         // Refresh git info to get updated status
         const updatedGitInfo = getGitInfo();
-        return await handleStagedCommit(updatedGitInfo, { silent });
+        return await handleStagedCommit(updatedGitInfo, { silent, dryRun, providedMessage });
       } else {
         // Check if there are staged changes to commit
         if (status.stagedCount > 0) {
           log.info(SYMBOLS.INFO, 'Proceeding with staged changes only');
-          return await handleStagedCommit(gitInfo, { silent });
+          return await handleStagedCommit(gitInfo, { silent, dryRun, providedMessage });
         }
         
         // Handle the case where user declined to stage and there are no staged changes
@@ -979,20 +1088,25 @@ export async function commitThis(options = {}) {
         }
       }
     } else {
+      if (dryRun) {
+        // Preview the stage instead of performing it
+        console.log(colors.BBlue(`${SYMBOLS.INFO} Dry run - would stage all changes (git add -A)`));
+        return await handleStagedCommit(gitInfo, { silent, dryRun, forceStaged: true, providedMessage });
+      }
       // Auto-stage all changes
       const stageResult = executeGitCommand('git add -A', false);
       if (stageResult === null) {
         console.log(colors.Red(`${SYMBOLS.CROSS} Failed to stage changes`));
         return false;
       }
-      
+
       // Refresh git info and commit
       const updatedGitInfo = getGitInfo();
-      return await handleStagedCommit(updatedGitInfo, { silent });
+      return await handleStagedCommit(updatedGitInfo, { silent, dryRun, providedMessage });
     }
   } else if (status.stagedCount > 0) {
     // Only staged changes present, proceed directly to commit
-    return await handleStagedCommit(gitInfo, { silent });
+    return await handleStagedCommit(gitInfo, { silent, dryRun, providedMessage });
   }
   
   return true;

package/lib/config-command.js

@@ -81,7 +81,7 @@ function displayConfig(config, options = {}) {
   // Group by category for better display
   const categories = {
     'Core System': ['MAIASS_DEBUG', 'MAIASS_VERBOSITY', 'MAIASS_LOGGING', 'MAIASS_BRAND'],
-    'AI Integration': ['MAIASS_AI_MODE', 'MAIASS_AI_TOKEN', 'MAIASS_AI_MODEL', 'MAIASS_AI_TEMPERATURE', 'MAIASS_AI_HOST', 'MAIASS_AI_MAX_CHARACTERS', 'MAIASS_AI_COMMIT_MESSAGE_STYLE'],
+    'AI Integration': ['MAIASS_AI_MODE', 'MAIASS_AI_TOKEN', 'MAIASS_AI_MODEL', 'MAIASS_AI_COMMIT_MODEL', 'MAIASS_AI_TEMPERATURE', 'MAIASS_AI_HOST', 'MAIASS_AI_MAX_CHARACTERS', 'MAIASS_AI_COMMIT_MESSAGE_STYLE'],
     'Git Branches': ['MAIASS_DEVELOPBRANCH', 'MAIASS_STAGINGBRANCH', 'MAIASS_MAINBRANCH'],
     'Repository Settings': ['MAIASS_REPO_TYPE', 'MAIASS_GITHUB_OWNER', 'MAIASS_GITHUB_REPO', 'MAIASS_BITBUCKET_WORKSPACE', 'MAIASS_BITBUCKET_REPO_SLUG'],
     'Pull Requests': ['MAIASS_DEVELOP_PULLREQUESTS'],

package/lib/config-manager.js

@@ -112,7 +112,7 @@ export function writeConfig(configPath, config, options = {}) {
     // Group variables by category for better organization
     const categories = {
       'Core': ['MAIASS_DEBUG', 'MAIASS_VERBOSITY', 'MAIASS_LOGGING', 'MAIASS_BRAND'],
-      'AI': ['MAIASS_AI_MODE', 'MAIASS_AI_TOKEN', 'MAIASS_AI_MODEL', 'MAIASS_AI_TEMPERATURE', 'MAIASS_AI_ENDPOINT', 'MAIASS_AI_MAX_CHARACTERS', 'MAIASS_AI_COMMIT_MESSAGE_STYLE'],
+      'AI': ['MAIASS_AI_MODE', 'MAIASS_AI_TOKEN', 'MAIASS_AI_MODEL', 'MAIASS_AI_COMMIT_MODEL', 'MAIASS_AI_TEMPERATURE', 'MAIASS_AI_ENDPOINT', 'MAIASS_AI_MAX_CHARACTERS', 'MAIASS_AI_COMMIT_MESSAGE_STYLE'],
       'Branches': ['MAIASS_DEVELOPBRANCH', 'MAIASS_STAGINGBRANCH', 'MAIASS_MAINBRANCH'],
       'Repository': ['MAIASS_REPO_TYPE', 'MAIASS_GITHUB_OWNER', 'MAIASS_GITHUB_REPO', 'MAIASS_BITBUCKET_WORKSPACE', 'MAIASS_BITBUCKET_REPO_SLUG'],
       'Pull Requests': ['MAIASS_DEVELOP_PULLREQUESTS'],

package/lib/flag-validator.js

@@ -89,13 +89,19 @@ export function suggestFlag(unknown, candidates) {
  * Validate the argv flags for a given subcommand.
  * @param {string[]} args - The raw argv tail (process.argv.slice(2))
  * @param {string[]} subcommandFlags - FLAGS export from the active subcommand handler
+ * @param {Set<number>} [ignoreIndices] - argv positions to skip entirely. Used
+ *   for option VALUES that may legitimately start with '-' (e.g. the -m/--message
+ *   value, where a caller might pass `-m "-- not a flag --"`). Without this, such
+ *   a value token would be misread as an unknown flag and rejected.
  * @returns {{valid: true} | {valid: false, flag: string, suggestion: string|null, validFlags: string[]}}
  */
-export function validateFlags(args, subcommandFlags = []) {
+export function validateFlags(args, subcommandFlags = [], ignoreIndices = new Set()) {
   // Dedupe so callers don't have to worry about overlap between the always-
   // valid set and a subcommand's FLAGS (e.g. account-info also lists --json).
   const validFlags = Array.from(new Set([...ALWAYS_VALID_FLAGS, ...subcommandFlags]));
-  for (const arg of args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (ignoreIndices.has(i)) continue;
     if (!arg.startsWith('-')) continue;
     // Support `--tag=value` form — only the name portion is validated.
     const flagName = arg.split('=')[0];

package/lib/maiass-command.js

@@ -19,6 +19,10 @@ export const FLAGS = [
   '--force', '-f',
   '--silent', '-s',
   '--tag', '-t',
+  // -m / --message <value>: supply the commit message verbatim, non-interactively
+  // (MAI-XX node+bash parity). Bypasses AI + interactive prompt. Works with the
+  // default workflow and commits-only (-c / -ac).
+  '--message', '-m',
 ];
 
 /**
@@ -34,7 +38,9 @@ export async function handleMaiassCommand(args) {
     'dry-run': dryRun,
     tag,
     force,
-    silent
+    silent,
+    // Verbatim commit message from -m/--message (MAI-XX). null when not supplied.
+    message: providedMessage = null
   } = args;
   
   // Extract version bump from positional arguments if provided
@@ -63,7 +69,8 @@ export async function handleMaiassCommand(args) {
       dryRun,
       tag,
       force,
-      silent
+      silent,
+      providedMessage
     });
     
     if (result.success) {

package/lib/maiass-pipeline.js

@@ -246,16 +246,18 @@ async function validateAndHandleBranching(options = {}) {
  * @returns {Promise<Object>} Commit result
  */
 async function handleCommitWorkflow(branchInfo, options = {}) {
-  const { commitsOnly = false, autoStage = false, silent = false } = options;
-  
+  const { commitsOnly = false, autoStage = false, silent = false, dryRun = false, providedMessage = null } = options;
+
   logger.header(SYMBOLS.INFO, 'Commit Workflow Phase');
-  
+
   try {
     // Run the commit workflow
     const commitSuccess = await commitThis({
       autoStage,
       commitsOnly,
-      silent
+      silent,
+      dryRun,
+      providedMessage
     });
     
     // Check if commit workflow succeeded
@@ -829,7 +831,9 @@ export async function runMaiassPipeline(options = {}) {
     dryRun = false,
     tag = false,
     force = false,
-    silent = false
+    silent = false,
+    // Verbatim commit message from -m/--message (MAI-XX). null = not supplied.
+    providedMessage = null
   } = options;
   
   // Display branded header with MAIASS's own version (not project version)
@@ -867,7 +871,7 @@ export async function runMaiassPipeline(options = {}) {
     
     // Phase 2: Commit Workflow
     logger.debug('Phase 2: Commit Workflow');
-    const commitResult = await handleCommitWorkflow(branchInfo, { commitsOnly, autoStage, silent });
+    const commitResult = await handleCommitWorkflow(branchInfo, { commitsOnly, autoStage, silent, dryRun, providedMessage });
     
     if (!commitResult.success) {
       // Check if it was cancelled by user vs actual failure
@@ -886,9 +890,13 @@ export async function runMaiassPipeline(options = {}) {
     // If commits-only mode, stop here
     if (commitsOnly) {
       console.log();
-      console.log(colors.BGreen(`${SYMBOLS.CHECKMARK} Commits-only mode completed successfully`));
+      if (dryRun) {
+        console.log(colors.BGreen(`${SYMBOLS.CHECKMARK} Commits-only mode dry run completed (no changes made)`));
+      } else {
+        console.log(colors.BGreen(`${SYMBOLS.CHECKMARK} Commits-only mode completed successfully`));
+      }
       console.log(colors.BBlue(`${SYMBOLS.INFO} Current branch: ${getCurrentBranch()}`));
-      return { success: true, phase: 'commits-only' };
+      return { success: true, phase: 'commits-only', dryRun };
     }
     
     console.log();

package/lib/maiass-variables.js

@@ -22,6 +22,7 @@ export const MAIASS_VARIABLES = {
   'MAIASS_AI_MODE': { default: 'ask', description: 'AI interaction mode' },
   'MAIASS_AI_TOKEN': { default: '', description: 'AI API token', sensitive: true },
   'MAIASS_AI_MODEL': { default: 'gpt-3.5-turbo', description: 'AI model to use' },
+  'MAIASS_AI_COMMIT_MODEL': { default: '', description: 'Override the AI model used for commit message generation. If set, skips auto-pick. Defaults to MAIASS_AI_MODEL if set, otherwise auto-picks by diff size.' },
   'MAIASS_AI_TEMPERATURE': { default: '0.7', description: 'AI temperature setting' },
   'MAIASS_AI_MAX_CHARACTERS': { default: '8000', description: 'Max characters for AI requests' },
   'MAIASS_AI_TIMEOUT': { default: '30', description: 'AI request timeout in seconds' },
@@ -33,7 +34,7 @@ export const MAIASS_VARIABLES = {
   'MAIASS_VERSION_PRIMARY_FILE': { default: '', description: 'Primary version file path' },
   'MAIASS_VERSION_PRIMARY_TYPE': { default: '', description: 'Primary version file type' },
   'MAIASS_VERSION_PRIMARY_LINE_START': { default: '', description: 'Line start pattern for version' },
-  'MAIASS_VERSION_SECONDARY_FILES': { default: '', description: 'Secondary version files (comma-separated)' },
+  'MAIASS_VERSION_SECONDARY_FILES': { default: '', description: 'Secondary version files (pipe-separated file:type:pattern entries)' },
 
   // Branch configuration
   'MAIASS_DEVELOPBRANCH': { default: 'develop', description: 'Development branch name' },

package/maiass.mjs

@@ -55,11 +55,25 @@ import { SYMBOLS } from './lib/symbols.js';
 import { bootstrapProject } from './lib/bootstrap.js';
 import { createGithubAction, showGitlabExcerpt, showBitbucketExcerpt } from './lib/ci-templates.js';
 import { validateFlags } from './lib/flag-validator.js';
+import { extractMessageFlag } from './lib/arg-utils.js';
 
 // Simple CLI setup for pkg compatibility
 const args = process.argv.slice(2);
-// Skip flags (starting with -) to find the first meaningful argument
-const firstArg = args.find(a => !a.startsWith('-'));
+
+// -m / --message <value>: a verbatim commit message supplied non-interactively
+// (MAI-XX node+bash parity). The flag CONSUMES the next token as its value, so
+// that value must NOT be treated as the command name / version-bump type during
+// command derivation below. Supported forms: `-m <value>`, `--message <value>`,
+// `--message=<value>`. Single value only (no git-style repeated -m).
+//
+// extractMessageFlag returns { message, valueIndices } where valueIndices marks
+// argv positions that belong to the flag (the flag token and, for the space-
+// separated form, its value) so command derivation can skip them.
+const { message: providedMessage, valueIndices: messageArgIndices } = extractMessageFlag(args);
+
+// Skip flags (starting with -) AND the -m/--message value token to find the
+// first meaningful positional argument (command / version-bump).
+const firstArg = args.find((a, i) => !a.startsWith('-') && !messageArgIndices.has(i));
 
 // Handle --setup/--bootstrap flag early
 if (args.includes('--setup') || args.includes('--bootstrap')) {
@@ -146,7 +160,10 @@ const SUBCOMMAND_FLAGS = {
 };
 
 const activeSubcommandFlags = SUBCOMMAND_FLAGS[command] ?? [];
-const flagValidation = validateFlags(args, activeSubcommandFlags);
+// Skip the -m/--message value token during validation — it may legitimately
+// begin with '-' (e.g. `-m "-- breaking change --"`) and must not be treated
+// as an unknown flag.
+const flagValidation = validateFlags(args, activeSubcommandFlags, messageArgIndices);
 
 if (!flagValidation.valid) {
   console.error(colors.Red(`${SYMBOLS.CROSS} Error: Unrecognized option '${flagValidation.flag}' for command '${command}'`));
@@ -167,6 +184,14 @@ if (!flagValidation.valid) {
   process.exit(1);
 }
 
+// An explicitly-supplied but empty/whitespace-only -m/--message is a usage
+// error — fail fast with a non-zero exit (parity with bash, which aborts here).
+// An absent flag (providedMessage === null) is unaffected.
+if (providedMessage !== null && providedMessage.trim() === '') {
+  console.error(colors.Red(`${SYMBOLS.CROSS} Error: --message/-m requires a non-empty value`));
+  process.exit(1);
+}
+
 // Apply auto-mode env vars now that validation has passed. Setting these
 // before validation would leak MAIASS_AUTO_* into process.env for commands
 // that reject --auto (e.g. `account-info --auto`) — see MAI-43 code review.
@@ -221,6 +246,8 @@ if (args.includes('--help') || args.includes('-h') || command === 'help') {
   console.log('  --auto, -a         Full auto — stage, commit, push, merge to develop, bump version');
   console.log('  --auto-commit, -ac Auto-yes for commit phase only — stops after commit (no merge, no bump)');
   console.log('  --commits-only, -c Generate AI commits without version management');
+  console.log('  --message, -m <msg> Use this commit message verbatim (skips AI + the message prompt; no credit/token needed).');
+  console.log('                     Supplies the message only; for fully unattended use combine with -ac (or --auto-stage).');
   console.log('  --auto-stage       Automatically stage all changes');
   console.log('  --setup, --bootstrap Run interactive project setup');
   console.log('  --help, -h         Show this help message');
@@ -263,7 +290,12 @@ if (args.includes('--show-bb-excerpt'))  { showBitbucketExcerpt(); process.exit(
       '.env.maiass.local',
       `# .env.maiass.local — personal/local MAIASS settings (never committed)\n` +
       `# Generated on first run: ${new Date().toISOString()}\n` +
-      `# Use this file for personal overrides, e.g. MAIASS_AI_MODE=autosuggest\n`,
+      `# Use this file for personal overrides, e.g. MAIASS_AI_MODE=autosuggest\n` +
+      `\n` +
+      `# Example: devlog tagging (optional)\n` +
+      `#MAIASS_DEVLOG_CLIENT="yourclient"\n` +
+      `#MAIASS_DEVLOG_SUBCLIENT=""\n` +
+      `#MAIASS_DEVLOG_PROJECT="yourproject"\n`,
       'utf8'
     );
 
@@ -326,7 +358,9 @@ if (args.includes('--show-bb-excerpt'))  { showBitbucketExcerpt(); process.exit(
     case 'maiass':
       // Handle the main MAIASS workflow
       await handleMaiassCommand({
-        _: process.argv.slice(2).filter(arg => !arg.startsWith('-')),
+        // Positionals must exclude the -m/--message value token (it doesn't start
+        // with '-' but is NOT a command/bump-type positional).
+        _: process.argv.slice(2).filter((arg, i) => !arg.startsWith('-') && !messageArgIndices.has(i)),
         // -ac is equivalent to -c (commits-only) plus auto-yes prompts
         'commits-only': args.includes('--commits-only') || args.includes('-c') || args.includes('--auto-commit') || args.includes('-ac'),
         'auto-stage': args.includes('--auto-stage'),
@@ -335,7 +369,10 @@ if (args.includes('--show-bb-excerpt'))  { showBitbucketExcerpt(); process.exit(
         'dry-run': args.includes('--dry-run') || args.includes('-d'),
         force: args.includes('--force') || args.includes('-f'),
         silent: args.includes('--silent') || args.includes('-s'),
-        tag: getArgValue(args, '--tag') || getArgValue(args, '-t')
+        tag: getArgValue(args, '--tag') || getArgValue(args, '-t'),
+        // Verbatim commit message supplied via -m/--message (or null). Threaded
+        // through the pipeline to the commit phase; bypasses AI + interactive.
+        message: providedMessage
       });
       break;
       
@@ -363,3 +400,6 @@ function getArgValue(args, flag) {
   }
   return null;
 }
+
+// extractMessageFlag is imported from ./lib/arg-utils.js — extracted (MAI-51)
+// so it can be unit-tested without booting the CLI on import.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "maiass",
   "type": "module",
-  "version": "5.13.0",
+  "version": "5.14.2",
   "description": "AI commit messages, version bumps, and changelogs from one command. Stages, commits, merges, tags. Anonymous on first run — no email, no card.",
   "main": "maiass.mjs",
   "bin": {

package/templates/ci/github-version-bump.yml

@@ -50,8 +50,11 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          cache: 'npm'
+          node-version: '24'
+          # No cache: this workflow only does `npm install -g maiass`, which
+          # needs no project-level npm cache. Setting cache: 'npm' makes
+          # setup-node fail on projects without a Node lock file (e.g.
+          # WordPress/PHP plugins): "Dependencies lock file is not found".
 
       - name: Install maiass
         run: npm install -g maiass --no-fund --no-audit