@auto-engineer/release-automation 1.148.0 → 1.149.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @auto-engineer/release-automation
 
+## 1.149.0
+
+### Minor Changes
+
+- [`e1eebbd`](https://github.com/BeOnAuto/auto-engineer/commit/e1eebbdf4f209780e790094d2e6887c4fa809f98) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **server-generator-apollo-emmett**: add Given state ref hints to state.ts.ejs
+  - **server-generator-apollo-emmett**: context-aware nonCommandField instructions
+  - **server-generator-apollo-emmett**: add state context instruction
+  - **server-generator-apollo-emmett**: extract shared template helpers
+  - **server-generator-apollo-emmett**: filter state refs from hasGivenEvents in decide.ts.ejs
+
+### Patch Changes
+
+- [`d38c81e`](https://github.com/BeOnAuto/auto-engineer/commit/d38c81e7bb442a39626564cf4f6d8d55b60d0a38) Thanks [@SamHatoum](https://github.com/SamHatoum)! -
+
 ## 1.148.0
 
 ### Minor Changes

package/README.md

@@ -1,16 +1,14 @@
 # @auto-engineer/release-automation
 
-Automated release management with changesets and conventional commits.
+Generate changesets from conventional commits with optional AI-generated changelogs.
 
-## Features
+---
 
-- ✅ **Automated changeset generation** from conventional commits
-- ✅ **AI-powered changelogs** with Claude CLI, Anthropic API, or simple fallback
-- ✅ **Git hook integration** for pre-push automation
-- ✅ **GitHub Actions support** for CI/CD workflows
-- ✅ **Configurable** via environment variables or config files
-- ✅ **OSS-friendly** with free tier AI options and simple fallback
-- ✅ **Library + CLI** - use programmatically or from command line
+## Purpose
+
+This package bridges the gap between conventional commits and [changesets](https://github.com/changesets/changesets). It parses your git history, determines the semver bump type, generates a human-readable changelog (using Claude CLI, the Anthropic API, or a simple formatter), and writes a changeset file. It works as a CLI in git hooks or CI, and as a library for programmatic use.
+
+---
 
 ## Installation
 
@@ -20,209 +18,28 @@ pnpm add -D @auto-engineer/release-automation
 
 ## Quick Start
 
-### CLI Usage
-
 ```bash
-# Generate changeset from conventional commits
+# Make conventional commits
+git commit -m "feat(auth): add OAuth support"
+git commit -m "fix(api): handle timeout errors"
+
+# Generate a changeset from those commits
 release-automation generate
 
-# Preview without creating file
+# Preview without writing a file
 release-automation generate --dry-run
 
-# Check if changesets exist
-release-automation check --verbose
-
-# Force simple changelog (no AI)
-release-automation generate --provider simple
+# Check whether changesets exist (useful in CI)
+release-automation check --require-changesets
 ```
 
-### Library Usage
+---
 
-```typescript
-import {
-  getCommitsSinceLastChangeset,
-  parseConventionalCommits,
-  determineBumpType,
-  generateChangelog,
-  createChangesetFile,
-  discoverPackages,
-} from '@auto-engineer/release-automation';
+## How-to Guides
 
-// Get commits since last changeset
-const commitHashes = getCommitsSinceLastChangeset();
-
-// Parse conventional commits
-const commits = parseConventionalCommits(commitHashes);
-
-// Determine semver bump type
-const bumpType = determineBumpType(commits); // 'major' | 'minor' | 'patch'
-
-// Generate AI changelog
-const description = await generateChangelog(commits);
-
-// Discover packages from changeset config
-const packages = await discoverPackages();
-
-// Create changeset file
-createChangesetFile({ bumpType, commits, description }, packages);
-```
-
-## CLI Commands
-
-### `generate`
+### Configure for CI/CD
 
-Generate changeset from conventional commits.
-
-```bash
-release-automation generate [options]
-
-Options:
-  --since <ref>           Git reference to compare against
-  --provider <type>       Changelog provider (claude-cli|anthropic-api|simple|auto) (default: "auto")
-  --no-amend              Do not amend the last commit
-  --dry-run               Preview changeset without creating file
-  --config <path>         Path to release config file
-  --changeset-dir <path>  Changeset directory (default: .changeset)
-  --packages <names>      Comma-separated package names (overrides config)
-```
-
-**Exit codes:**
-- `0` - Success
-- `1` - General error
-- `10` - No changesets found (with `--require-changesets`)
-- `11` - No commits to process
-- `12` - No conventional commits found
-- `20` - Configuration error
-- `30` - Git error
-
-### `check`
-
-Check for pending changesets or commits that need changesets.
-
-```bash
-release-automation check [options]
-
-Options:
-  --since <ref>          Check commits since this reference
-  -v, --verbose          Show detailed information
-  --require-changesets   Exit with error if no changesets exist
-```
-
-## Configuration
-
-### Environment Variables
-
-```bash
-# Enable/disable features
-AUTO_CHANGESET_ENABLED=true|false           # Enable auto-changeset (default: true)
-AUTO_CHANGESET_AMEND=true|false             # Auto-amend commits (default: true)
-
-# Changelog generation
-AUTO_CHANGESET_PROVIDER=auto|claude-cli|anthropic-api|simple  # Provider (default: auto)
-ANTHROPIC_API_KEY=sk-ant-...                # For anthropic-api provider
-
-# Paths
-AUTO_CHANGESET_CONFIG_PATH=.changeset/config.json  # Changeset config path
-AUTO_CHANGESET_DIR=.changeset                      # Changeset directory
-
-# Package discovery
-AUTO_CHANGESET_PACKAGES=@pkg/a,@pkg/b       # Override package discovery
-```
-
-### Config File
-
-Create `.release-automation.json`:
-
-```json
-{
-  "changesetConfigPath": ".changeset/config.json",
-  "changelogProvider": "auto",
-  "autoAmend": true,
-  "changesetDir": ".changeset"
-}
-```
-
-Or add to `package.json`:
-
-```json
-{
-  "releaseAutomation": {
-    "changelogProvider": "auto",
-    "autoAmend": true
-  }
-}
-```
-
-## Changelog Providers
-
-The package tries providers in order until one succeeds:
-
-### 1. Claude CLI (Fastest)
-
-Requires `claude` in PATH.
-
-```bash
-# Check availability
-which claude
-
-# Install Claude CLI
-# See: https://docs.anthropic.com/claude/docs/claude-cli
-```
-
-### 2. Anthropic API
-
-Requires `ANTHROPIC_API_KEY` environment variable.
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-```
-
-**Free tier:** $5 credit = 5000+ changeset generations (at ~$0.001 each)
-
-**Get API key:** https://console.anthropic.com
-
-### 3. Simple Fallback
-
-Always available. Formats commit messages into bullet points:
-
-- Groups by type (feat, fix, others)
-- Adds scope formatting
-- Limits to 5 items
-
-## Git Hook Integration
-
-Add to `.husky/pre-push`:
-
-```bash
-#!/bin/sh
-
-# Check if enabled
-if [ "${AUTO_CHANGESET_ENABLED:-true}" = "false" ]; then
-  echo "⏭️  Auto-changeset disabled"
-  exit 0
-fi
-
-# Generate changesets
-pnpm release-automation generate
-
-# Check exit code
-EXIT_CODE=$?
-if [ $EXIT_CODE -ne 0 ] && [ $EXIT_CODE -ne 11 ] && [ $EXIT_CODE -ne 12 ]; then
-  echo "❌ Failed to generate changeset"
-  exit $EXIT_CODE
-fi
-
-# Amend commit if configured
-if [ "${AUTO_CHANGESET_AMEND:-true}" = "true" ]; then
-  if [ -n "$(git status --porcelain .changeset/*.md 2>/dev/null)" ]; then
-    git add .changeset/*.md
-    git commit --amend --no-edit --no-verify
-    echo "✅ Changesets added to commit!"
-  fi
-fi
-```
-
-## GitHub Actions Integration
+Add a changeset check step to your GitHub Actions workflow:
 
 ```yaml
 - name: Check for changesets
@@ -248,266 +65,184 @@ fi
     git push
 ```
 
-## Library API
-
-### Git Operations
-
-```typescript
-import {
-  getCommitsSinceLastChangeset,
-  getCommitsInRange,
-  getAllCommits,
-  getCommitsSinceLastTag,
-  getLastChangesetCommit,
-  getLastReleaseTag,
-  getCommitMessage,
-  isGitRepository,
-} from '@auto-engineer/release-automation';
-
-// Get commits since last changeset
-const commits = getCommitsSinceLastChangeset('.changeset');
-
-// Get commits in range
-const commits = getCommitsInRange('v1.0.0', 'HEAD');
-
-// Check if in git repo
-if (isGitRepository()) {
-  // ...
-}
-```
+### Set Up a Pre-push Hook
 
-### Conventional Commit Parsing
+Add to `.husky/pre-push`:
 
-```typescript
-import {
-  parseConventionalCommit,
-  parseConventionalCommits,
-  isConventionalCommit,
-  extractBreakingChange,
-} from '@auto-engineer/release-automation';
+```bash
+#!/bin/sh
 
-// Parse single commit
-const commit = parseConventionalCommit('abc123');
+if [ "${AUTO_CHANGESET_ENABLED:-true}" = "false" ]; then
+  exit 0
+fi
 
-// Parse multiple commits
-const commits = parseConventionalCommits(['abc123', 'def456']);
+pnpm release-automation generate
 
-// Validate format
-if (isConventionalCommit('feat(cli): add feature')) {
-  // Valid
-}
+EXIT_CODE=$?
+if [ $EXIT_CODE -ne 0 ] && [ $EXIT_CODE -ne 11 ] && [ $EXIT_CODE -ne 12 ]; then
+  exit $EXIT_CODE
+fi
 
-// Check for breaking changes
-if (extractBreakingChange('feat!: breaking change')) {
-  // Has breaking change
-}
+if [ "${AUTO_CHANGESET_AMEND:-true}" = "true" ]; then
+  if [ -n "$(git status --porcelain .changeset/*.md 2>/dev/null)" ]; then
+    git add .changeset/*.md
+    git commit --amend --no-edit --no-verify
+  fi
+fi
 ```
 
-### Semver Logic
+### Use as a Library
 
 ```typescript
 import {
+  getCommitsSinceLastChangeset,
+  parseConventionalCommits,
   determineBumpType,
-  hasBreakingChanges,
-  hasFeatures,
+  generateChangelog,
+  createChangesetFile,
+  discoverPackages,
 } from '@auto-engineer/release-automation';
 
-const commits = parseConventionalCommits(hashes);
-
-// Determine bump type (major > minor > patch)
+const commitHashes = getCommitsSinceLastChangeset();
+const commits = parseConventionalCommits(commitHashes);
 const bumpType = determineBumpType(commits);
+const description = await generateChangelog(commits);
+const packages = await discoverPackages();
 
-// Check for breaking changes
-if (hasBreakingChanges(commits)) {
-  // Major version bump
-}
-
-// Check for features
-if (hasFeatures(commits)) {
-  // Minor version bump
-}
+createChangesetFile({ bumpType, commits, description }, packages);
 ```
 
-### Changelog Generation
+### Choose a Changelog Provider
 
-```typescript
-import { generateChangelog } from '@auto-engineer/release-automation';
-
-const commits = parseConventionalCommits(hashes);
+In `auto` mode (the default), providers are tried in order until one succeeds:
 
-// Generate with auto provider selection
-const changelog = await generateChangelog(commits);
+1. **Claude CLI** -- requires `claude` on `PATH`.
+2. **Anthropic API** -- requires `ANTHROPIC_API_KEY` env var.
+3. **Simple** -- always available; formats commits as bullet points grouped by type.
 
-// Force specific provider
-const changelog = await generateChangelog(commits, {
-  changelogProvider: 'simple',
-});
+Force a specific provider:
 
-// Use Anthropic API
-const changelog = await generateChangelog(commits, {
-  changelogProvider: 'anthropic-api',
-  anthropicApiKey: 'sk-ant-...',
-});
+```bash
+release-automation generate --provider simple
 ```
 
-### Package Discovery
+---
 
-```typescript
-import {
-  discoverPackages,
-  readChangesetConfig,
-  getFixedGroupPackages,
-} from '@auto-engineer/release-automation';
+## CLI Reference
 
-// Discover from changeset config
-const packages = await discoverPackages('.changeset/config.json');
+### `generate`
 
-// Read config
-const config = await readChangesetConfig();
+Generate a changeset from conventional commits.
 
-// Get fixed group packages
-const packages = getFixedGroupPackages(config);
+```bash
+release-automation generate [options]
 ```
 
-### Changeset Writer
+| Option | Description | Default |
+|---|---|---|
+| `--since <ref>` | Git reference to compare against | auto-detect |
+| `--provider <type>` | Changelog provider: `claude-cli`, `anthropic-api`, `simple`, `auto` | `auto` |
+| `--no-amend` | Do not amend the last commit | -- |
+| `--dry-run` | Preview changeset without creating a file | -- |
+| `--config <path>` | Path to release config file | -- |
+| `--changeset-dir <path>` | Changeset directory | `.changeset` |
+| `--packages <names>` | Comma-separated package names (overrides discovery) | -- |
 
-```typescript
-import {
-  createChangesetFile,
-  generateChangesetFrontmatter,
-  generateChangesetFilename,
-} from '@auto-engineer/release-automation';
+### `check`
 
-// Create changeset file
-const result = createChangesetFile(
-  {
-    bumpType: 'minor',
-    commits,
-    description: 'Changelog content',
-  },
-  ['@pkg/a', '@pkg/b'],
-  '.changeset'
-);
-
-console.log(result.filename); // 'auto-a1b2c3d4.md'
-console.log(result.path);     // '/path/to/.changeset/auto-a1b2c3d4.md'
-
-// Generate frontmatter
-const frontmatter = generateChangesetFrontmatter(
-  ['@pkg/a', '@pkg/b'],
-  'minor'
-);
-```
+Check for pending changesets or commits that need changesets.
 
-### Configuration Loading
+```bash
+release-automation check [options]
+```
 
-```typescript
-import { loadConfig } from '@auto-engineer/release-automation';
+| Option | Description | Default |
+|---|---|---|
+| `--since <ref>` | Check commits since this reference | auto-detect |
+| `-v, --verbose` | Show detailed information | -- |
+| `--require-changesets` | Exit with error if no changesets exist | -- |
 
-// Load from all sources (env, file, defaults)
-const config = await loadConfig();
+### Exit Codes
 
-// Override specific values
-const config = await loadConfig({
-  changelogProvider: 'simple',
-  autoAmend: false,
-});
-```
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | General error |
+| `10` | No changesets found (with `--require-changesets`) |
+| `11` | No commits to process |
+| `12` | No conventional commits found |
+| `20` | Configuration error |
+| `30` | Git error |
 
-## Conventional Commit Format
+### Configuration File
 
-This package follows the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+Create `.release-automation.json` in the project root:
 
+```json
+{
+  "changesetConfigPath": ".changeset/config.json",
+  "changelogProvider": "auto",
+  "autoAmend": true,
+  "changesetDir": ".changeset"
+}
 ```
-<type>(<scope>): <subject>
 
-[optional body]
+Or add a `releaseAutomation` key to `package.json`:
 
-[optional footer]
+```json
+{
+  "releaseAutomation": {
+    "changelogProvider": "auto",
+    "autoAmend": true
+  }
+}
 ```
 
-**Types:**
-- `feat` - New feature (minor bump)
-- `fix` - Bug fix (patch bump)
-- `docs` - Documentation changes
-- `style` - Code style changes (formatting, etc)
-- `refactor` - Code refactoring
-- `perf` - Performance improvements
-- `test` - Test changes
-- `build` - Build system changes
-- `ci` - CI configuration changes
-- `chore` - Other changes
-- `revert` - Revert previous commit
-
-**Breaking changes:**
-- Add `!` after type: `feat!: breaking change`
-- Add footer: `BREAKING CHANGE: description`
-
-## Examples
+### Environment Variables
 
-### Example 1: Basic Usage
+| Variable | Description | Default |
+|---|---|---|
+| `AUTO_CHANGESET_ENABLED` | Enable/disable changeset generation | `true` |
+| `AUTO_CHANGESET_AMEND` | Auto-amend commits with changeset | `true` |
+| `AUTO_CHANGESET_PROVIDER` | Changelog provider | `auto` |
+| `AUTO_CHANGESET_CONFIG_PATH` | Path to changeset config | `.changeset/config.json` |
+| `AUTO_CHANGESET_DIR` | Changeset directory | `.changeset` |
+| `AUTO_CHANGESET_PACKAGES` | Comma-separated package names | -- |
+| `ANTHROPIC_API_KEY` | API key for `anthropic-api` provider | -- |
 
-```bash
-# Make some commits
-git commit -m "feat(cli): add new command"
-git commit -m "fix(server): resolve connection issue"
+Configuration priority: CLI options > environment variables > config file > defaults.
 
-# Generate changeset
-pnpm release-automation generate
-
-# Output:
-# ✅ Found 2 valid conventional commit(s)
-# 📊 Determined version bump: minor
-# ✨ Generating changelog...
-# ✅ Created changeset: auto-a1b2c3d4.md
-```
+---
 
-### Example 2: Dry Run
+## Troubleshooting
 
-```bash
-pnpm release-automation generate --dry-run
-
-# Output:
-# 📋 Changeset Preview:
-# ---
-# Bump type: minor
-# Packages: @auto-engineer/cli, @auto-engineer/server
-#
-# Changelog:
-# - Added new command functionality
-# - Fixed connection stability issues
-# ---
-```
+### Enable Debug Logging
 
-### Example 3: CI/CD Check
+The CLI uses `ora` spinners and `chalk`-colored log lines. To see raw output without spinners, pipe to a file:
 
 ```bash
-# Check if changesets exist (for CI)
-pnpm release-automation check --require-changesets
-
-# Exit code 0 if changesets exist
-# Exit code 10 if no changesets
+release-automation generate 2>&1 | tee release.log
 ```
 
-## Troubleshooting
-
 ### "No conventional commits found"
 
-Ensure commits follow the format:
+Commits must follow the `type(scope): subject` format:
 
 ```bash
-# ✅ Good
-git commit -m "feat(cli): add feature"
-git commit -m "fix: bug fix"
+# Valid
+git commit -m "feat(cli): add new command"
+git commit -m "fix: resolve timeout"
 
-# ❌ Bad
+# Invalid -- will be skipped
 git commit -m "added feature"
 git commit -m "WIP"
 ```
 
+Supported types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
+
 ### "Failed to discover packages"
 
-Check that `.changeset/config.json` exists and has a `fixed` array:
+The package reads `.changeset/config.json` and looks for a `fixed` array:
 
 ```json
 {
@@ -515,46 +250,63 @@ Check that `.changeset/config.json` exists and has a `fixed` array:
 }
 ```
 
+Glob patterns (e.g., `@auto-engineer/*`) are expanded by scanning `packages/*/package.json`. If you have no `packages/` directory, list package names explicitly with `--packages` or the `AUTO_CHANGESET_PACKAGES` env var.
+
 ### "Claude CLI not found"
 
-Install Claude CLI or set `ANTHROPIC_API_KEY`:
+If the `claude-cli` provider is unavailable, the tool falls back to `anthropic-api`, then `simple`. To skip AI entirely:
 
 ```bash
-# Option 1: Install Claude CLI
-# See: https://docs.anthropic.com/claude/docs/claude-cli
+release-automation generate --provider simple
+```
 
-# Option 2: Use Anthropic API
-export ANTHROPIC_API_KEY=sk-ant-...
+Or set the env var:
 
-# Option 3: Use simple mode
-pnpm release-automation generate --provider simple
+```bash
+export AUTO_CHANGESET_PROVIDER=simple
 ```
 
-## Development
+### Changeset not created in expected directory
 
-```bash
-# Install dependencies
-pnpm install
+Verify the `--changeset-dir` option or `AUTO_CHANGESET_DIR` env var points to the correct path relative to the working directory. The directory is created automatically if it does not exist.
+
+---
 
-# Build
-pnpm build
+## Architecture
 
-# Run tests (when implemented)
-pnpm test
+```mermaid
+graph TD
+    CLI["bin/release-automation"]
+    CLI --> RunCli["cli/index.ts — runCli()"]
+    RunCli --> GenCmd["commands/generate"]
+    RunCli --> ChkCmd["commands/check"]
 
-# Type check
-pnpm type-check
+    GenCmd --> Git["lib/git — commit history"]
+    GenCmd --> Parser["lib/changeset/parser — conventional commit parsing"]
+    GenCmd --> Semver["lib/changeset/semver — bump type detection"]
+    GenCmd --> Changelog["lib/changelog/generator — changelog text"]
+    GenCmd --> Packages["lib/packages/discovery — package list from config"]
+    GenCmd --> Writer["lib/changeset/writer — .changeset/*.md files"]
+    GenCmd --> Config["lib/config/loader — merged configuration"]
 
-# Watch mode
-pnpm test:watch
+    Changelog --> ClaudeCli["providers/claude-cli"]
+    Changelog --> AnthropicApi["providers/anthropic-api"]
+    Changelog --> Simple["providers/simple"]
 ```
 
-## License
+### Subpath Exports
 
-MIT
+| Export | Entry point | Contents |
+|---|---|---|
+| `@auto-engineer/release-automation` | `src/index.ts` | Full public API (lib + types) |
+| `@auto-engineer/release-automation/lib` | `src/lib/index.ts` | Library functions only |
+| `@auto-engineer/release-automation/cli` | `src/cli/index.ts` | `runCli()` entry point |
 
-## Related
+### Dependencies
 
-- [Changesets](https://github.com/changesets/changesets)
-- [Conventional Commits](https://www.conventionalcommits.org/)
-- [Anthropic API](https://docs.anthropic.com/)
+| Dependency | Purpose |
+|---|---|
+| `commander` | CLI argument parsing |
+| `chalk` | Terminal colors for log output |
+| `ora` | Spinner during changelog generation |
+| `minimatch` | Glob matching for package discovery |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auto-engineer/release-automation",
-  "version": "1.148.0",
+  "version": "1.149.0",
   "type": "module",
   "description": "Automated release management with changesets and conventional commits",
   "main": "./dist/src/index.js",