maiass 5.12.2 → 5.12.9

package/README.md

@@ -1,7 +1,8 @@
 ![MAIASS Banner](https://raw.githubusercontent.com/vsmash/maiass/main/assets/maiassbanner2.png)
 
-# `|))` MAIASS (Node.js)
-**Modular AI-Augmented Semantic Scribe** — intelligent Git workflow automation
+# MAIASS
+
+**AI commit messages, version bumps, and changelogs from one command.**
 
 [![npm](https://img.shields.io/npm/v/maiass.svg)](https://www.npmjs.com/package/maiass)
 [![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
@@ -9,23 +10,31 @@
 
 ---
 
-MAIASS automates the repetitive parts of your Git workflow: staging, AI-powered commit messages, branch merging, version bumping, and changelog generation — all from a single command.
+Run `maiass` in any git repo and it stages your changes, writes the commit message, bumps the version, updates the changelog, and merges the branch. It's for developers who do this routine every day and want the keystrokes back. Anonymous on first run — no email, no card, no sign-up.
 
-> Looking for the shell/Homebrew version? See [bashmaiass](https://github.com/vsmash/bashmaiass).
+> Site: [maiass.net](https://maiass.net) · Bash/Homebrew source: [bashmaiass](https://github.com/vsmash/bashmaiass)
 
 ---
 
-## Installation
+## Install
+
+**npm — all platforms (primary):**
 
 ```bash
 npm install -g maiass
 ```
 
-Requires Node.js 20+.
+**Homebrew — macOS:**
+
+```bash
+brew tap vsmash/maiass && brew install maiass
+```
+
+Requires Node.js 20+ for the npm install. Linux script install and other options are in the [docs](docs/setup.md).
 
 ---
 
-## Quick Start
+## Quick start
 
 ```bash
 # First time in a project — run setup
@@ -47,29 +56,41 @@ maiass --dry-run patch
 
 ---
 
-## AI Commit Messages
+## CI auto-version-bump
 
-MAIASS uses its own proxy service for AI-powered commit message suggestions. On first run it creates an anonymous subscription automatically — no sign-up required.
-
-To use a named account (for credit top-ups):
+One flag installs a CI workflow that runs `maiass -a patch` every time a PR merges into your develop branch — so version bumps and changelog entries never get forgotten.
 
 ```bash
-maiass config set MAIASS_AI_TOKEN your_api_key
-```
+# GitHub Actions — writes .github/workflows/maiass-version-bump.yml
+maiass --create-gh-action
 
-AI mode is configured per-project in `.env.maiass`:
+# GitLab CI — prints a job stage to paste into .gitlab-ci.yml
+maiass --show-gl-excerpt
 
-```bash
-MAIASS_AI_MODE=ask        # ask each time (default)
-MAIASS_AI_MODE=autosuggest  # always use AI
-MAIASS_AI_MODE=off          # disable AI
+# Bitbucket Pipelines — prints a step to paste into bitbucket-pipelines.yml
+maiass --show-bb-excerpt
 ```
 
+The installed workflow sets `MAIASS_AI_MODE=off`, so the bump runs at zero AI credit cost. Your configured `MAIASS_DEVELOPBRANCH` is baked into the trigger filter at install time. Full setup (PAT scopes for GitHub, double-bump guard for GitLab/Bitbucket) in [the workflow docs](docs/workflow.md#-ci-auto-version-bump-on-pr-merge).
+
 ---
 
-## Key Features
+## Anonymous by default
+
+First run creates a subscription tied to a machine fingerprint — no email, no account, no card. When you need credits, top up at [maiass.net](https://maiass.net) or run `maiass --setup` to add an API key for a named account.
+
+API keys live in OS-level secure storage (Keychain on macOS, Secret Service on Linux, encrypted local store on Windows), never in your repo. Commit diffs are sent to the proxy to generate the message and aren't stored — token counts, model, timestamp, and source IP are kept for billing and abuse prevention.
+
+AI mode per project in `.env.maiass`: `ask` / `autosuggest` / `off`.
+
+Run `maiass account-info` to see your subscription ID, credit balance, and top-up link.
+
+---
+
+## Key features
 
 - **AI commit messages** — analyses your diff and suggests a structured commit message
+- **CI auto-version-bump** — one flag installs a GitHub Actions, GitLab CI, or Bitbucket Pipelines workflow that bumps the version on every merge to your develop branch, at zero AI credit cost
 - **Version management** — detects and bumps `package.json`, `composer.json`, `VERSION`, `.pbxproj` (Swift/Xcode), and more
 - **Changelog generation** — user-facing `CHANGELOG.md` and internal developer changelog
 - **Branch workflow** — feature → develop → staging → main with merge handling
@@ -131,7 +152,7 @@ MAIASS_DEBUG=true                 # verbose output
 
 Issues and PRs welcome. See [docs/development.md](docs/development.md) to get started.
 
-## 🙏 Acknowledgments
+## Acknowledgments
 
 - Git community for workflow inspiration
 - All contributors and testers
@@ -140,11 +161,11 @@ Issues and PRs welcome. See [docs/development.md](docs/development.md) to get st
 
 [GNU General Public License v3.0](LICENSE)
 
----
-
-**Made with ❤️ for developers who want to automate versioning, changelogs, and commit messages.**
-
-## 💸 Support MAIASS
+## Support MAIASS
 
 [![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?logo=github)](https://github.com/sponsors/vsmash)
 [![Ko-fi](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Ko--fi-29abe0?logo=ko-fi)](https://ko-fi.com/myass)
+
+---
+
+<sub>MAIASS is a backronym for *Modular AI-Assisted Semantic Scribe*. It's also pronounced however you like.</sub>

package/lib/account-info.js

@@ -442,9 +442,14 @@ export async function handleAccountInfoCommand(options = {}) {
     } else {
       console.log(`Status:          ${result.status || 'unknown'}`);
     }
-    
+
+    if (subscriptionId && subscriptionId.startsWith('sub_anon_')) {
+      const topupEndpoint = process.env.MAIASS_TOPUP_ENDPOINT || 'https://maiass.net/top-up';
+      console.log(`Top-up link:      ${topupEndpoint}/${subscriptionId}`);
+    }
+
     console.log('');
-    
+
   } catch (error) {
     if (debugMode) {
       log.debug(SYMBOLS.WARNING, `[MAIASS DEBUG] Account info error: ${error.stack || error.message}`);

package/lib/ci-templates.js

@@ -8,6 +8,17 @@ import { SYMBOLS } from './symbols.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(__dirname, '..', 'templates', 'ci');
 
+// Read a template from disk and substitute placeholders for the user's configured
+// branch names. The develop-branch trigger filter in GitHub Actions / GitLab CI /
+// Bitbucket Pipelines must be a YAML literal — there is no runtime escape hatch —
+// so we bake the value in at install time from MAIASS_DEVELOPBRANCH.
+function renderTemplate(src) {
+  // .trim() guards against a stray newline or whitespace from a mis-quoted
+  // .env.maiass entry silently breaking the YAML trigger filter
+  const developBranch = (process.env.MAIASS_DEVELOPBRANCH || 'develop').trim() || 'develop';
+  return fs.readFileSync(src, 'utf8').replaceAll('__MAIASS_DEVELOPBRANCH__', developBranch);
+}
+
 /**
  * Copy a CI template file to the target path in the current project.
  * Creates intermediate directories if needed.
@@ -32,7 +43,7 @@ function copyTemplate(templateFile, targetPath, label) {
 
   // Create parent directories (e.g. .github/workflows/)
   fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-  fs.copyFileSync(src, targetPath);
+  fs.writeFileSync(targetPath, renderTemplate(src));
 
   console.log(colors.BGreen(`${SYMBOLS.CHECKMARK} Created ${targetPath}`));
   console.log(colors.Gray(`  ${label}`));
@@ -52,7 +63,7 @@ function showTemplate(templateFile, label) {
 
   console.log(colors.BGreen(`\n${label}\n`));
   console.log(colors.Gray('─'.repeat(60)));
-  console.log(fs.readFileSync(src, 'utf8'));
+  console.log(renderTemplate(src));
   console.log(colors.Gray('─'.repeat(60)));
   console.log(colors.Gray('Copy the above into your bitbucket-pipelines.yml\n'));
 }

package/maiass.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// MAIASS: Modular AI-Augmented Semantic Scribe
+// MAIASS: Modular AI-Assisted Semantic Scribe
 import path from 'path';
 import fs from 'fs';
 import yargs from 'yargs';

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "maiass",
   "type": "module",
-  "version": "5.12.2",
-  "description": "AI commit message generator, semantic versioning, and changelog automation for Git. One command stages, commits with AI, bumps version, and merges branches. Free credits on install — no sign-up needed.",
+  "version": "5.12.9",
+  "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": {
     "maiass": "./maiass.mjs",

package/templates/ci/bitbucket-pipelines-excerpt.yml

@@ -11,17 +11,20 @@
 #   the last commit message. If it looks like a MAIASS version bump, it exits early.
 #
 # Setup:
-#   1. Merge this excerpt into your bitbucket-pipelines.yml (or use as-is)
-#   2. In Bitbucket: Repository Settings → Pipelines → SSH Keys
+#   1. Set MAIASS_DEVELOPBRANCH in your .env.maiass if your develop branch
+#      isn't called 'develop', then run `maiass --show-bb-excerpt` to print
+#      this template with your branch name baked in (defaults to 'develop'
+#      when unset).
+#   2. Merge the printed excerpt into your bitbucket-pipelines.yml (or use as-is)
+#   3. In Bitbucket: Repository Settings → Pipelines → SSH Keys
 #      Add a key pair and grant write access, OR use an app password:
 #        - Create an app password with Repositories: Read & Write scope
 #        - Add it as a repository variable named BB_APP_PASSWORD (secured)
 #        - Add your Bitbucket username as BB_USERNAME
-#   3. Set MAIASS_DEVELOPBRANCH in your .env.maiass if your branch isn't 'develop'
 
 pipelines:
   branches:
-    develop:  # Change to match your MAIASS_DEVELOPBRANCH if different
+    __MAIASS_DEVELOPBRANCH__:
       - step:
           name: MAIASS Version Bump
           image: node:20

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

@@ -3,21 +3,27 @@
 # What this does:
 #   When a pull request is merged into your develop branch, this workflow
 #   automatically runs `maiass -a patch` to bump the patch version, commit
-#   the change, and push it back to develop.
+#   the change, and push it back.
 #
 # Setup:
-#   1. Copy this file to .github/workflows/maiass-version-bump.yml in your repo
+#   1. Set MAIASS_DEVELOPBRANCH in your .env.maiass if your develop branch
+#      isn't called 'develop', then run `maiass --create-gh-action` so the
+#      branch name is baked into the installed workflow (defaults to 'develop'
+#      when unset).
 #   2. Create a fine-grained Personal Access Token (PAT) with:
 #        - Contents: Read & Write
 #        - Metadata: Read-only
 #        - Workflows: Read & Write
 #   3. Add the PAT as a repository secret named GH_PAT
-#   4. Set MAIASS_DEVELOPBRANCH in your .env.maiass if your branch isn't 'develop'
 #
 # Notes:
-#   - AI is disabled (MAIASS_AI_MODE: off) so no credits are used
-#   - The workflow reads MAIASS_DEVELOPBRANCH from your .env.maiass automatically
-#   - maiass pulls the latest develop before bumping to prevent stale version conflicts
+#   - AI is disabled (MAIASS_AI_MODE: off) so no credits are used.
+#   - The branch name below is substituted at install time from
+#     MAIASS_DEVELOPBRANCH. GitHub Actions requires `on.pull_request.branches`
+#     to be a YAML literal, so it cannot be read from env at runtime. Edit
+#     this file manually only if you rename your develop branch after install.
+#   - maiass pulls the latest of that branch before bumping to prevent stale
+#     version conflicts.
 
 name: Version Bump on PR Merge
 
@@ -25,7 +31,7 @@ on:
   pull_request:
     types: [closed]
     branches:
-      - develop  # Change this to match your MAIASS_DEVELOPBRANCH if different
+      - __MAIASS_DEVELOPBRANCH__
 
 jobs:
   bump-version:
@@ -57,8 +63,8 @@ jobs:
 
       # Explicitly check out the develop branch head (the pull_request closed
       # event checks out a merge ref, not the branch itself)
-      - name: Checkout develop
-        run: git checkout develop
+      - name: Checkout __MAIASS_DEVELOPBRANCH__
+        run: git checkout __MAIASS_DEVELOPBRANCH__
 
       - name: Bump version
         run: maiass -a patch

package/templates/ci/gitlab-ci-excerpt.yml

@@ -5,11 +5,14 @@
 #   (including merge requests). Bumps the patch version, commits, and pushes.
 #
 # Setup:
-#   1. Merge this excerpt into your existing .gitlab-ci.yml, or use it as-is
-#   2. In GitLab: Settings → Repository → Protected branches → allow pipelines to push
-#   3. Create a project access token or personal access token with write access
-#   4. Add it as a CI/CD variable named GITLAB_TOKEN (masked, protected)
-#   5. Set MAIASS_DEVELOPBRANCH in your .env.maiass if your branch isn't 'develop'
+#   1. Set MAIASS_DEVELOPBRANCH in your .env.maiass if your develop branch
+#      isn't called 'develop', then run `maiass --show-gl-excerpt` to print
+#      this template with your branch name baked in (defaults to 'develop'
+#      when unset).
+#   2. Merge the printed excerpt into your existing .gitlab-ci.yml, or use it as-is
+#   3. In GitLab: Settings → Repository → Protected branches → allow pipelines to push
+#   4. Create a project access token or personal access token with write access
+#   5. Add it as a CI/CD variable named GITLAB_TOKEN (masked, protected)
 #
 # Double-bump protection:
 #   The script checks the last commit author and skips if it was already made
@@ -22,7 +25,7 @@ maiass-version-bump:
   stage: version
   image: node:20
   only:
-    - develop  # Change to match your MAIASS_DEVELOPBRANCH if different
+    - __MAIASS_DEVELOPBRANCH__
   script:
     # Skip if the last commit was already a version bump from this pipeline
     - |