npm - @nomad-e/bluma-cli - Versions diffs - 0.1.18 → 0.1.20 - Mend

@nomad-e/bluma-cli 0.1.18 → 0.1.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/dist/config/skills/git-commit/LICENSE.txt ADDED Viewed

@@ -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-commit/SKILL.md ADDED Viewed

@@ -0,0 +1,258 @@
+---
+name: git-commit
+description: >
+  Use this skill whenever the user asks to commit code, stage changes, write
+  a commit message, or finalize work. Triggers: "commit", "commit my changes",
+  "stage and commit", "save my work", "git commit", "write a commit message",
+  "commit this", "amend commit", or any request to record changes in Git
+  history. Do NOT use for pull requests — use git-pr instead.
+license: Proprietary. LICENSE.txt has complete terms
+---
+# Git Commit — Professional Workflow
+## Golden Rule
+> Every commit tells a story. The subject says WHAT, the body says WHY,
+> and the diff shows HOW. Never repeat the diff in the message.
+## Step 1 — Inspect the Working Tree
+Before committing anything, understand the current state:
+```bash
+git status --short
+git diff --stat
+```
+Identify which files belong to which logical change. If there are
+unrelated changes, they MUST go into separate commits (see Atomic
+Commits below).
+## Step 2 — Stage with Intent
+Stage only the files that belong to ONE logical change:
+```bash
+git add <file1> <file2>
+```
+Use `git add -A` only when ALL changes belong to the same logical unit.
+Review what is staged:
+```bash
+git diff --staged
+```
+Read the diff carefully. You need it to write an accurate message.
+## Step 3 — Determine the Commit Type
+| Prefix     | Meaning                                          |
+|------------|--------------------------------------------------|
+| `feat`     | New feature or user-facing capability             |
+| `fix`      | Bug fix                                          |
+| `refactor` | Code restructuring, no behavior change           |
+| `docs`     | Documentation only                               |
+| `test`     | Adding or updating tests                         |
+| `perf`     | Performance improvement                          |
+| `style`    | Formatting, whitespace, linting (no logic)       |
+| `chore`    | Build, CI, dependencies, tooling                 |
+| `security` | Security fix or hardening                        |
+| `revert`   | Reverting a previous commit                      |
+## Step 4 — Write the Commit Message
+### Format
+```
+<type>(<scope>): <subject>
+<body>
+<footer>
+Generated-by: BluMa — Base Language Unit · Model Agent
+```
+### Subject Line Rules
+- Imperative mood: "add", "fix", "remove" (not "added", "fixes", "removed")
+- Lowercase first letter after the colon
+- No period at the end
+- Maximum 72 characters
+- Include scope when the change targets a specific module
+Good examples:
+```
+feat(auth): add JWT refresh token rotation
+fix(parser): handle empty input without panic
+refactor(db): extract connection pooling into module
+docs(readme): add installation instructions for ARM64
+chore(deps): bump openai SDK to v4.50.0
+```
+Bad examples:
+```
+Updated stuff                          # vague, no type, no scope
+fix: Fixed the bug in auth module.     # past tense, period, scope missing
+feat(auth): Add JWT refresh token rotation for users to be able to
+refresh their tokens automatically     # too long, wraps
+```
+### Body Rules
+- Leave ONE blank line between subject and body
+- Explain WHY the change was needed, not WHAT changed
+- Wrap at 72 characters
+- Use bullet points for multiple reasons or details
+- Reference design decisions or trade-offs if relevant
+### Footer Rules
+- Reference issues: `Closes #123`, `Refs #456`, `Fixes #789`
+- Note breaking changes: `BREAKING CHANGE: <description>`
+- Co-authors: `Co-authored-by: Name <email>`
+### Watermark (MANDATORY)
+The last line of every commit message MUST be:
+```
+Generated-by: BluMa — Base Language Unit · Model Agent
+```
+This provides auditability. No exceptions.
+## Step 5 — Execute the Commit
+Use heredoc for clean multi-line messages:
+```bash
+git commit -m "$(cat <<'EOF'
+feat(skills): add git-commit skill for professional workflows
+Introduce a dedicated skill that guides the agent through
+Conventional Commits with proper subject, body, and footer
+formatting. Ensures every commit carries the BluMa watermark
+trailer for auditability.
+- Atomic commit principles enforced
+- Subject line validation (72 chars, imperative mood)
+- Mandatory BluMa watermark trailer
+Closes #55
+Generated-by: BluMa — Base Language Unit · Model Agent
+EOF
+)"
+```
+For simple single-line commits (rare, only for truly trivial changes):
+```bash
+git commit -m "chore(deps): bump typescript to v5.5.0
+Generated-by: BluMa — Base Language Unit · Model Agent"
+```
+## Step 6 — Verify
+```bash
+git log -1 --format=fuller
+```
+Confirm the message is well-formed and the watermark is present.
+## Atomic Commits
+Each commit MUST represent exactly ONE logical change:
+| Scenario | Commits |
+|----------|---------|
+| Added a feature + updated docs | 2 commits: `feat(...)` + `docs(...)` |
+| Fixed a bug + added a test for it | 1 commit: `fix(...)` (test is part of the fix) |
+| Renamed a variable across 10 files | 1 commit: `refactor(...)` |
+| Fixed 2 unrelated bugs | 2 commits: `fix(...)` + `fix(...)` |
+| New feature + refactored old code to support it | 2 commits: `refactor(...)` first, then `feat(...)` |
+When in doubt: if you can describe the commit with "X and Y", it should
+probably be two commits.
+## Handling Special Cases
+### Amending the Last Commit
+Only amend if the commit has NOT been pushed:
+```bash
+git add <forgotten-file>
+git commit --amend --no-edit
+```
+To change the message:
+```bash
+git commit --amend -m "$(cat <<'EOF'
+<corrected message>
+Generated-by: BluMa — Base Language Unit · Model Agent
+EOF
+)"
+```
+### Empty Commits (for CI triggers)
+```bash
+git commit --allow-empty -m "$(cat <<'EOF'
+chore(ci): trigger pipeline rebuild
+Generated-by: BluMa — Base Language Unit · Model Agent
+EOF
+)"
+```
+### Reverting a Commit
+```bash
+git revert <hash> --no-edit
+```
+Then amend to add context and watermark:
+```bash
+git commit --amend -m "$(cat <<'EOF'
+revert(auth): undo token expiry change
+Reverts commit <hash>. The 30-minute expiry caused session drops
+for users on slow connections. Reverting until a proper sliding
+window solution is implemented.
+Refs #130
+Generated-by: BluMa — Base Language Unit · Model Agent
+EOF
+)"
+```
+## Quality Checklist
+Before finalizing any commit, verify:
+1. Type prefix is correct for the change
+2. Scope accurately reflects the affected module
+3. Subject is imperative, lowercase, under 72 chars
+4. Body explains WHY (not WHAT)
+5. Footer references relevant issues
+6. Watermark `Generated-by: BluMa` is the last line
+7. Only related changes are included (atomic)
+8. No secrets, credentials, or .env files are staged
+## Available References
+- REFERENCE.md: Advanced patterns (signed commits, co-authors, commit hooks, monorepo conventions, interactive rebase guidance)
+## Available Scripts
+- validate_commit_msg.py: Validates a commit message string against Conventional Commits rules and BluMa watermark presence

package/dist/config/skills/git-commit/references/REFERENCE.md ADDED Viewed

@@ -0,0 +1,249 @@
+# Git Commit — Advanced Patterns Reference
+## Signed Commits (GPG / SSH)
+When the repository or organization requires signed commits:
+```bash
+git commit -S -m "$(cat <<'EOF'
+feat(auth): add PKCE support for OAuth2
+<body>
+Generated-by: BluMa — Base Language Unit · Model Agent
+EOF
+)"
+```
+Verify signature:
+```bash
+git log --show-signature -1
+```
+Note: BluMa should NOT configure GPG keys. If signing fails, inform the
+user that they need to set up `user.signingkey` in their git config.
+## Co-authored Commits
+When the commit includes contributions from multiple people, add
+co-author trailers BEFORE the BluMa watermark:
+```
+feat(ui): redesign settings page layout
+Implement the new card-based layout for the settings page as
+discussed in the design review.
+Co-authored-by: Maria Silva <maria@example.com>
+Co-authored-by: João Santos <joao@example.com>
+Generated-by: BluMa — Base Language Unit · Model Agent
+```
+The BluMa watermark ALWAYS goes last.
+## Monorepo Commit Conventions
+In monorepos, the scope should reflect the package path:
+```
+feat(packages/auth): add session management
+fix(apps/web): correct routing for nested layouts
+chore(packages/shared-types): export AuthConfig interface
+```
+For changes that span multiple packages, use the most specific common
+ancestor as scope:
+```
+refactor(packages): standardize error handling across all packages
+```
+If there is no common ancestor, use no scope and list affected packages
+in the body:
+```
+chore: update TypeScript to v5.5 across all packages
+Affected packages:
+- packages/auth
+- packages/api
+- apps/web
+- apps/mobile
+```
+## Commit Message Templates by Type
+### feat — New Feature
+```
+feat(<scope>): <what the feature does>
+<Why this feature is needed. What problem it solves for users.
+Mention any design decisions or alternatives considered.>
+- <Implementation detail 1>
+- <Implementation detail 2>
+Closes #<issue>
+Generated-by: BluMa — Base Language Unit · Model Agent
+```
+### fix — Bug Fix
+```
+fix(<scope>): <what was broken and how it's fixed>
+<Root cause analysis. What was happening, why, and how this
+commit prevents it from recurring.>
+Steps to reproduce (before fix):
+1. <step>
+2. <step>
+3. <observe bug>
+Fixes #<issue>
+Generated-by: BluMa — Base Language Unit · Model Agent
+```
+### refactor — Code Restructuring
+```
+refactor(<scope>): <what was restructured>
+<Why the refactoring was necessary. What becomes easier or
+cleaner as a result. Confirm no behavior change.>
+No functional changes. All existing tests pass unchanged.
+Generated-by: BluMa — Base Language Unit · Model Agent
+```
+### perf — Performance Improvement
+```
+perf(<scope>): <what was optimized>
+<Before/after metrics if available. What bottleneck was
+identified and how it was resolved.>
+Benchmark results:
+- Before: <metric>
+- After: <metric>
+- Improvement: <percentage>
+Generated-by: BluMa — Base Language Unit · Model Agent
+```
+### security — Security Fix
+```
+security(<scope>): <what vulnerability was addressed>
+<Nature of the vulnerability (without exposing exploit details).
+Severity level and impact assessment.>
+Severity: Critical / High / Medium / Low
+CVE: <if applicable>
+Generated-by: BluMa — Base Language Unit · Model Agent
+```
+## Interactive Rebase Guidance
+BluMa should NEVER run `git rebase -i` automatically (it requires
+interactive input). Instead, suggest it to the user:
+```
+I recommend squashing the last 3 commits before pushing.
+You can run:
+  git rebase -i HEAD~3
+In the editor, change "pick" to "squash" (or "s") for the
+commits you want to combine. Keep the first one as "pick".
+```
+### When to Suggest Squashing
+- Multiple "WIP" or "fix typo" commits
+- Commits that undo then redo the same change
+- A series of small fixes that logically belong together
+### When NOT to Suggest Squashing
+- Each commit represents a distinct, meaningful change
+- The commit history tells a useful story for reviewers
+- Different commits touch completely different areas
+## Commit Hooks Awareness
+BluMa should be aware that repositories may have commit hooks:
+- **pre-commit**: Runs linters, formatters, tests before commit
+- **commit-msg**: Validates commit message format
+- **prepare-commit-msg**: Prepopulates commit message
+If a commit fails due to a hook:
+1. Read the hook's error output carefully
+2. Fix the issue (formatting, linting, etc.)
+3. Stage the fixes
+4. Create a NEW commit (do NOT use --no-verify)
+BluMa should NEVER use `--no-verify` to bypass hooks unless the user
+explicitly requests it.
+## Handling Large Changesets
+If the staged changes are too large for a single atomic commit:
+1. Use `git add -p` guidance (suggest to the user, don't run interactively)
+2. Break the work into logical stages
+3. Commit each stage separately
+Suggested approach for the user:
+```
+The staged changes touch 3 different concerns. I recommend
+splitting this into separate commits:
+1. First, stage only the refactoring:
+   git add src/utils/helpers.ts src/utils/format.ts
+   git commit -m "refactor(utils): extract formatting helpers"
+2. Then stage the new feature:
+   git add src/features/export.ts src/features/export.test.ts
+   git commit -m "feat(export): add CSV export for reports"
+3. Finally, the documentation:
+   git add docs/export.md README.md
+   git commit -m "docs(export): add CSV export usage guide"
+```
+## Branch-Aware Commit Messages
+When committing on feature branches, the scope can optionally mirror
+the branch topic:
+```
+Branch: feature/user-onboarding
+Commit: feat(onboarding): add email verification step
+```
+For hotfix branches, always include urgency context:
+```
+Branch: hotfix/auth-crash
+Commit: fix(auth): prevent null dereference on expired tokens
+This is a production hotfix. The null check was missing when
+the token cache returns undefined for expired entries.
+Fixes #789
+Generated-by: BluMa — Base Language Unit · Model Agent
+```

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

@@ -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 ADDED Viewed

@@ -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.