@nomad-e/bluma-cli 0.1.17 → 0.1.19

package/dist/config/skills/git-commit/scripts/validate_commit_msg.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+Validate a commit message against Conventional Commits format
+and BluMa watermark requirements.
+
+Usage:
+    python validate_commit_msg.py "<commit message>"
+    python validate_commit_msg.py --last
+    python validate_commit_msg.py --range main..HEAD
+
+Exit codes:
+    0  Message is valid
+    1  Message has issues
+"""
+
+import subprocess
+import sys
+import re
+
+TYPES = {"feat", "fix", "refactor", "docs", "test", "perf", "style", "chore", "security", "revert"}
+
+SUBJECT_RE = re.compile(
+    r'^(' + '|'.join(TYPES) + r')'
+    r'(\([a-zA-Z0-9_/.-]+\))?'
+    r'!?:\s'
+    r'.{1,68}$'
+)
+
+WATERMARK = "Generated-by: BluMa"
+
+
+def validate_message(msg: str) -> list[str]:
+    issues = []
+    lines = msg.strip().split('\n')
+
+    if not lines:
+        return ["Empty commit message"]
+
+    subject = lines[0].strip()
+
+    if not SUBJECT_RE.match(subject):
+        parts = subject.split(':', 1)
+        if not parts or parts[0].split('(')[0] not in TYPES:
+            issues.append(f"Invalid type prefix. Expected one of: {', '.join(sorted(TYPES))}")
+        elif len(subject) > 72:
+            issues.append(f"Subject too long ({len(subject)} chars, max 72)")
+        else:
+            issues.append(f"Subject format invalid: \"{subject}\"")
+
+    if subject and subject[-1] == '.':
+        issues.append("Subject should not end with a period")
+
+    if subject and subject.split(': ', 1)[-1][:1].isupper():
+        issues.append("Subject description should start with lowercase")
+
+    if len(lines) > 1 and lines[1].strip() != '':
+        issues.append("Missing blank line between subject and body")
+
+    if WATERMARK not in msg:
+        issues.append("Missing BluMa watermark trailer")
+    else:
+        last_non_empty = ''
+        for line in reversed(lines):
+            if line.strip():
+                last_non_empty = line.strip()
+                break
+        if not last_non_empty.startswith("Generated-by:"):
+            issues.append("BluMa watermark should be the last non-empty line")
+
+    return issues
+
+
+def get_last_commit_msg() -> str:
+    result = subprocess.run(
+        ["git", "log", "-1", "--format=%B"],
+        capture_output=True, text=True
+    )
+    if result.returncode != 0:
+        print(f"Error: {result.stderr.strip()}")
+        sys.exit(1)
+    return result.stdout.strip()
+
+
+def get_commit_msgs(commit_range: str) -> list[tuple[str, str]]:
+    result = subprocess.run(
+        ["git", "log", commit_range, "--format=%h|||%B---END---"],
+        capture_output=True, text=True
+    )
+    if result.returncode != 0:
+        print(f"Error: {result.stderr.strip()}")
+        sys.exit(1)
+
+    commits = []
+    for block in result.stdout.split("---END---"):
+        block = block.strip()
+        if not block:
+            continue
+        parts = block.split("|||", 1)
+        if len(parts) == 2:
+            commits.append((parts[0].strip(), parts[1].strip()))
+    return commits
+
+
+def print_result(label: str, msg: str, issues: list[str]):
+    subject = msg.split('\n')[0][:60]
+    if issues:
+        print(f"  FAIL [{label}] {subject}")
+        for issue in issues:
+            print(f"       - {issue}")
+    else:
+        print(f"  OK   [{label}] {subject}")
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage:")
+        print('  python validate_commit_msg.py "<message>"')
+        print("  python validate_commit_msg.py --last")
+        print("  python validate_commit_msg.py --range main..HEAD")
+        sys.exit(1)
+
+    has_errors = False
+
+    if sys.argv[1] == "--last":
+        msg = get_last_commit_msg()
+        issues = validate_message(msg)
+        print("Validating last commit:\n")
+        print_result("HEAD", msg, issues)
+        has_errors = bool(issues)
+
+    elif sys.argv[1] == "--range":
+        if len(sys.argv) < 3:
+            print("Error: --range requires a commit range (e.g. main..HEAD)")
+            sys.exit(1)
+        commits = get_commit_msgs(sys.argv[2])
+        if not commits:
+            print(f"No commits in range {sys.argv[2]}")
+            sys.exit(0)
+        print(f"Validating {len(commits)} commit(s) in {sys.argv[2]}:\n")
+        for h, msg in commits:
+            issues = validate_message(msg)
+            print_result(h, msg, issues)
+            if issues:
+                has_errors = True
+
+    else:
+        msg = sys.argv[1]
+        issues = validate_message(msg)
+        print("Validating message:\n")
+        print_result("input", msg, issues)
+        has_errors = bool(issues)
+
+    print()
+    if has_errors:
+        print("Some commits need attention.")
+        sys.exit(1)
+    else:
+        print("All messages are valid.")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/dist/config/skills/git-pr/LICENSE.txt

@@ -0,0 +1,18 @@
+BluMa — Base Language Unit · Model Agent
+Proprietary License
+
+Copyright (c) 2024-2026 BluMa Contributors
+
+This skill is part of the BluMa CLI distribution.
+It is provided as a bundled native skill and may not be
+redistributed, modified, or used outside of the BluMa agent
+framework without prior written permission.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/dist/config/skills/git-pr/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: git-pr
+description: >
+  Use this skill for any task involving Git commits, pull requests, or code
+  review preparation. Triggers include: "commit", "create a PR", "pull request",
+  "open a PR", "prepare a merge request", "push changes", "commit my work",
+  "stage and commit", "git push", "submit for review", "create MR", or any
+  request to finalize, package, or submit code changes for review. Also use
+  when asked to write commit messages or PR descriptions.
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# Git PR & Commit — Professional Workflow
+
+## Overview
+
+This skill produces **production-grade** commits and pull requests with
+consistent structure, meaningful descriptions, and full traceability.
+Every commit and PR carries a BluMa watermark for auditability.
+
+For advanced patterns (monorepo PRs, release PRs, hotfix workflows),
+see references/REFERENCE.md.
+
+## Commit Workflow
+
+### Step 1: Inspect Changes
+
+```bash
+git status --short
+git diff --staged --stat
+```
+
+If nothing is staged, stage the relevant files first:
+
+```bash
+git add <files>
+# or
+git add -A
+```
+
+Review what will be committed:
+
+```bash
+git diff --staged
+```
+
+### Step 2: Determine Commit Type
+
+| Prefix | When to use |
+|--------|-------------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `refactor` | Code restructuring without behavior change |
+| `docs` | Documentation only |
+| `test` | Adding or updating tests |
+| `perf` | Performance improvement |
+| `style` | Formatting, whitespace, linting (no logic change) |
+| `chore` | Build, CI, dependencies, tooling |
+| `security` | Security fix or hardening |
+| `revert` | Reverting a previous commit |
+
+### Step 3: Write the Commit Message
+
+Format:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+
+Generated-by: BluMa — Base Language Unit · Model Agent
+```
+
+Rules:
+- **Subject line**: imperative mood, lowercase, no period, max 72 chars.
+  - Good: `feat(auth): add JWT refresh token rotation`
+  - Bad: `Added JWT refresh token rotation.`
+- **Scope**: the module, component, or area affected (optional but preferred).
+- **Body**: explain WHY the change was made, not WHAT (the diff shows what).
+  Wrap at 72 chars. Leave a blank line after subject.
+- **Footer**: reference issues (`Closes #123`, `Refs #456`), note breaking
+  changes (`BREAKING CHANGE: ...`).
+- **Watermark**: always include the `Generated-by` trailer as the last line.
+
+### Step 4: Execute the Commit
+
+```bash
+git commit -m "<type>(<scope>): <subject>
+
+<body>
+
+Closes #<issue>
+
+Generated-by: BluMa — Base Language Unit · Model Agent"
+```
+
+For multi-line messages, prefer heredoc:
+
+```bash
+git commit -m "$(cat <<'EOF'
+feat(pdf): add CSV-to-PDF report generation
+
+Implement create_report.py script that reads CSV data and produces
+a formatted PDF report using reportlab. Supports custom titles and
+outputs to the artifacts directory.
+
+- Added scripts/create_report.py with argparse CLI
+- Table styling with header highlighting and grid borders
+- Automatic page sizing based on data volume
+
+Closes #42
+
+Generated-by: BluMa — Base Language Unit · Model Agent
+EOF
+)"
+```
+
+## Pull Request Workflow
+
+### Step 1: Ensure Clean Branch State
+
+```bash
+git log --oneline main..HEAD
+git diff main..HEAD --stat
+```
+
+Verify:
+- All commits follow Conventional Commits (see above).
+- No untracked or unstaged changes remain.
+- Branch is up to date with the target branch.
+
+### Step 2: Push the Branch
+
+```bash
+git push -u origin HEAD
+```
+
+### Step 3: Analyze All Changes for the PR
+
+Read every commit since divergence from the target branch:
+
+```bash
+git log main..HEAD --format="%h %s"
+git diff main..HEAD
+```
+
+Understand the full scope of changes — not just the last commit, but ALL
+commits that will be included. This is critical for writing an accurate
+PR description.
+
+### Step 4: Generate the PR Description
+
+Use this template exactly. Fill every section. Do not skip sections — mark
+them as "N/A" if they do not apply.
+
+```markdown
+## Description
+<!-- 2-5 sentences explaining WHAT changed and WHY -->
+
+{Concise but complete description of the changes. Focus on the problem
+being solved and the approach taken. Mention any design decisions or
+trade-offs made.}
+
+## Related Issue
+
+Closes #{issue_number}
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+- [ ] Performance improvement
+- [ ] Code cleanup
+- [ ] Security fix
+
+## Changes Made
+
+{Bullet list of specific changes, organized by file or module:}
+
+- **module/file.ts**: Description of change
+- **module/other.ts**: Description of change
+
+## Testing
+
+- [ ] Manual testing completed
+- [ ] Functionality verified in development environment
+- [ ] No breaking changes introduced
+- [ ] Edge cases considered and tested
+- [ ] Tested with different scenarios (if applicable)
+
+{Describe specific test scenarios and results:}
+
+1. **Scenario**: {what was tested}
+   **Result**: {what happened}
+
+## Breaking Changes
+
+{If any, describe what breaks and how to migrate. If none, write "None."}
+
+## Screenshots (if applicable)
+
+{Add screenshots for UI changes. If none, write "N/A."}
+
+## Checklist
+
+- [ ] Code follows the project's style guidelines
+- [ ] Self-review of code completed
+- [ ] Hard-to-understand areas are commented
+- [ ] Documentation updated (if applicable)
+- [ ] No new warnings generated
+- [ ] Changes tested thoroughly
+- [ ] Dependent changes merged and published
+
+## Additional Notes
+
+{Any context, concerns, follow-up tasks, or questions for reviewers.}
+
+---
+
+> *Generated by [BluMa — Base Language Unit · Model Agent](https://github.com/Nomad-e/bluma-cli)*
+```
+
+### Step 5: Create the PR
+
+```bash
+gh pr create \
+  --title "<type>(<scope>): <subject>" \
+  --body "$(cat <<'EOF'
+<full PR body from Step 4>
+EOF
+)"
+```
+
+The PR title MUST follow the same Conventional Commits format as commit
+subjects. If the PR contains multiple commits of different types, use the
+most significant type (feat > fix > refactor > chore).
+
+### Step 6: Verify
+
+```bash
+gh pr view --web
+```
+
+Confirm the PR looks correct in the browser.
+
+## Quality Standards
+
+Every PR generated by BluMa must:
+
+1. Have a title in Conventional Commits format.
+2. Include a complete description with all template sections filled.
+3. Reference the related issue (if one exists).
+4. Mark the correct "Type of Change" checkboxes.
+5. List specific changes made, organized by file/module.
+6. Describe testing scenarios and results.
+7. Document breaking changes (or explicitly state "None").
+8. Include the BluMa watermark at the bottom.
+9. Have all checklist items reviewed (checked or unchecked with justification).
+
+## Watermarks
+
+**Commit trailer** (last line of every commit message):
+```
+Generated-by: BluMa — Base Language Unit · Model Agent
+```
+
+**PR footer** (last line of every PR body):
+```markdown
+---
+
+> *Generated by [BluMa — Base Language Unit · Model Agent](https://github.com/Nomad-e/bluma-cli)*
+```
+
+These watermarks provide auditability and attribution. They MUST be present
+in every commit and PR generated by BluMa, with no exceptions.
+
+## Available References
+
+- REFERENCE.md: Advanced patterns (monorepo PRs, release PRs, hotfix workflows, PR labels, reviewer assignment)
+
+## Available Scripts
+
+- validate_commits.py: Validates that all commits in a range follow Conventional Commits format
+
+## Next Steps
+
+- For advanced PR workflows, see references/REFERENCE.md
+- To validate commits before creating a PR, run scripts/validate_commits.py