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

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

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

@@ -0,0 +1,256 @@
+# Git PR — Advanced Patterns Reference
+## Monorepo Pull Requests
+When working in a monorepo, PRs should be scoped to a single package or
+service when possible.
+### Title Convention
+```
+feat(packages/auth): add PKCE support for OAuth2 flow
+```
+### Description Structure
+Add a **Scope** section after Description:
+```markdown
+## Scope
+This PR affects only the `packages/auth` module. No changes to other
+packages.
+### Packages Modified
+- `packages/auth` — Core changes
+- `packages/shared-types` — Updated `AuthConfig` interface
+```
+### Cross-Package Dependencies
+If the PR touches multiple packages, list the dependency graph:
+```markdown
+## Cross-Package Impact
+```
+packages/auth (changed)
+  └── packages/shared-types (interface update)
+      └── packages/api (consumer — no code changes, recompile needed)
+```
+```
+## Release Pull Requests
+Release PRs aggregate multiple feature/fix PRs into a versioned release.
+### Title Format
+```
+chore(release): v2.4.0
+```
+### Body Template Addition
+Add a **Changelog** section:
+```markdown
+## Changelog
+### Features
+- feat(auth): add JWT refresh token rotation (#123)
+- feat(pdf): add CSV-to-PDF report generation (#125)
+### Bug Fixes
+- fix(agent): handle empty tool responses gracefully (#124)
+### Breaking Changes
+- BREAKING: `AuthConfig.tokenExpiry` renamed to `AuthConfig.accessTokenTTL` (#123)
+### Migration Guide
+1. Update all references to `tokenExpiry` → `accessTokenTTL`
+2. Set `refreshTokenTTL` (new required field, default: 7d)
+```
+## Hotfix Pull Requests
+Hotfixes bypass the normal development flow and go directly to production.
+### Branch Naming
+```
+hotfix/<issue-id>-<short-description>
+```
+Example: `hotfix/456-fix-auth-crash`
+### Title Format
+```
+fix(auth): prevent null pointer on expired session [HOTFIX]
+```
+### Additional Body Sections
+```markdown
+## Hotfix Justification
+**Severity**: Critical / High / Medium
+**Impact**: {describe user impact}
+**Root Cause**: {brief root cause analysis}
+**Temporary or Permanent**: {is this a permanent fix or a stopgap?}
+## Rollback Plan
+1. Revert commit {hash}
+2. Redeploy previous version {tag}
+3. Verify via {health check endpoint}
+```
+## PR Labels
+Suggest appropriate labels based on the change type:
+| Change Type | Suggested Labels |
+|-------------|-----------------|
+| Bug fix | `bug`, `priority:high` (if critical) |
+| New feature | `enhancement`, `feature` |
+| Breaking change | `breaking-change`, `major` |
+| Documentation | `documentation` |
+| Refactoring | `refactoring`, `tech-debt` |
+| Performance | `performance`, `optimization` |
+| Security | `security`, `priority:critical` |
+| Dependencies | `dependencies`, `chore` |
+When using `gh pr create`, add labels:
+```bash
+gh pr create \
+  --title "feat(auth): add MFA support" \
+  --label "enhancement" \
+  --label "feature" \
+  --body "..."
+```
+## Reviewer Assignment
+Suggest reviewers based on files changed:
+```bash
+# Find who has most commits in the changed files
+git log --format='%an' -- <changed-files> | sort | uniq -c | sort -rn | head -5
+```
+Add reviewers when creating the PR:
+```bash
+gh pr create \
+  --title "..." \
+  --reviewer "username1,username2" \
+  --body "..."
+```
+## Draft Pull Requests
+For work-in-progress changes, create draft PRs:
+```bash
+gh pr create \
+  --title "feat(agent): implement streaming responses" \
+  --draft \
+  --body "..."
+```
+Add a **Status** section to draft PR bodies:
+```markdown
+## Status
+🚧 **Work in Progress** — Do not merge
+### Completed
+- [x] Core streaming implementation
+- [x] Token-by-token output
+### Remaining
+- [ ] Error handling for stream interruption
+- [ ] Unit tests
+- [ ] Documentation update
+```
+## Stacked Pull Requests
+For large features, break into smaller, reviewable PRs:
+### Naming Convention
+```
+feat(auth)/1-data-models
+feat(auth)/2-api-endpoints
+feat(auth)/3-frontend-ui
+```
+### Body Addition
+```markdown
+## PR Stack
+This is PR **2 of 3** in the auth feature stack.
+| # | PR | Status |
+|---|---|--------|
+| 1 | #100 — Data models | ✅ Merged |
+| 2 | #101 — API endpoints (this PR) | 🔄 In Review |
+| 3 | #102 — Frontend UI | ⏳ Blocked on #101 |
+**Base branch**: `feat/auth-1-data-models` (not `main`)
+```
+## Commit Squashing Strategy
+Before creating a PR, consider squashing noisy commits:
+### When to Squash
+- Multiple "fix typo" or "WIP" commits
+- Commits that only fix linting or formatting
+- Commits that undo then redo changes
+### When NOT to Squash
+- Each commit represents a logical, reviewable unit
+- Commit history tells a useful story of the implementation
+- Different commits affect different modules
+### Interactive Rebase (manual, not for BluMa to run automatically)
+```bash
+git rebase -i main
+# Mark commits as 'squash' or 'fixup'
+```
+Note: BluMa should NOT automatically rebase or squash. Instead, suggest
+it to the user when appropriate.
+## Multi-Issue PRs
+When a PR addresses multiple issues:
+```markdown
+## Related Issues
+Closes #123
+Closes #125
+Refs #130 (partial — remaining work tracked separately)
+```
+## PR Size Guidelines
+| Size | Files Changed | Lines Changed | Review Time |
+|------|--------------|---------------|-------------|
+| XS | 1-2 | < 50 | 10 min |
+| S | 3-5 | 50-200 | 30 min |
+| M | 6-10 | 200-500 | 1 hour |
+| L | 11-20 | 500-1000 | 2+ hours |
+| XL | 20+ | 1000+ | Split recommended |
+If a PR exceeds **L** size, BluMa should suggest splitting it into
+stacked PRs (see above).

package/dist/config/skills/git-pr/scripts/validate_commits.py ADDED Viewed

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+Validate that commits in a given range follow Conventional Commits format
+and include the BluMa watermark trailer.
+Usage:
+    python validate_commits.py [base_branch]
+Arguments:
+    base_branch   Target branch to compare against (default: main)
+Exit codes:
+    0  All commits are valid
+    1  One or more commits have issues
+"""
+import subprocess
+import sys
+import re
+CONVENTIONAL_PATTERN = re.compile(
+    r'^(feat|fix|refactor|docs|test|perf|style|chore|security|revert)'
+    r'(\([a-zA-Z0-9_/.-]+\))?'
+    r'!?:\s.{1,72}$'
+)
+WATERMARK = "Generated-by: BluMa"
+def get_commits(base: str) -> list[dict]:
+    result = subprocess.run(
+        ["git", "log", f"{base}..HEAD", "--format=%H|||%s|||%b%n---END---"],
+        capture_output=True, text=True
+    )
+    if result.returncode != 0:
+        print(f"Error running git log: {result.stderr.strip()}")
+        sys.exit(1)
+    raw = result.stdout.strip()
+    if not raw:
+        return []
+    commits = []
+    for block in raw.split("---END---"):
+        block = block.strip()
+        if not block:
+            continue
+        parts = block.split("|||", 2)
+        if len(parts) >= 2:
+            commits.append({
+                "hash": parts[0].strip()[:8],
+                "subject": parts[1].strip(),
+                "body": parts[2].strip() if len(parts) > 2 else ""
+            })
+    return commits
+def validate(commits: list[dict]) -> list[str]:
+    issues = []
+    for c in commits:
+        h = c["hash"]
+        subj = c["subject"]
+        if not CONVENTIONAL_PATTERN.match(subj):
+            issues.append(
+                f"  [{h}] Subject does not follow Conventional Commits: \"{subj}\""
+            )
+        if len(subj) > 72:
+            issues.append(
+                f"  [{h}] Subject exceeds 72 chars ({len(subj)}): \"{subj}\""
+            )
+        if WATERMARK not in c["body"] and WATERMARK not in subj:
+            issues.append(
+                f"  [{h}] Missing BluMa watermark trailer"
+            )
+    return issues
+def main():
+    base = sys.argv[1] if len(sys.argv) > 1 else "main"
+    commits = get_commits(base)
+    if not commits:
+        print(f"No commits found between {base} and HEAD.")
+        sys.exit(0)
+    print(f"Validating {len(commits)} commit(s) against {base}...\n")
+    for c in commits:
+        status = "OK" if CONVENTIONAL_PATTERN.match(c["subject"]) else "WARN"
+        print(f"  [{c['hash']}] {status}: {c['subject']}")
+    issues = validate(commits)
+    print()
+    if issues:
+        print(f"Found {len(issues)} issue(s):\n")
+        for issue in issues:
+            print(issue)
+        print("\nPlease fix the above before creating a PR.")
+        sys.exit(1)
+    else:
+        print("All commits are valid. Ready for PR.")
+        sys.exit(0)
+if __name__ == "__main__":
+    main()

package/dist/config/skills/pdf/LICENSE.txt ADDED Viewed

@@ -0,0 +1,26 @@
+© 2026 NomadEngenuity LDA. All rights reserved.
+LICENSE: Use of these materials (including all code, prompts, assets, files,
+and other components of this Skill) is governed by your agreement with
+NomadEngenuity LDA regarding use of NomadEngenuity LDA's services. If no
+separate agreement exists, use is governed by NomadEngenuity LDA's applicable
+Terms of Service.
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the
+contrary, users may not:
+- Extract these materials from the Services or retain copies of these
+  materials outside the Services
+- Reproduce or copy these materials, except for temporary copies created
+  automatically during authorized use of the Services
+- Create derivative works based on these materials
+- Distribute, sublicense, or transfer these materials to any third party
+- Make, offer to sell, sell, or import any inventions embodied in these
+  materials
+- Reverse engineer, decompile, or disassemble these materials
+The receipt, viewing, or possession of these materials does not convey or
+imply any license or right beyond those expressly granted above.
+NomadEngenuity LDA retains all right, title, and interest in these materials,
+including all copyrights, patents, and other intellectual property rights.