@nomad-e/bluma-cli 0.1.17 → 0.1.19

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

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

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

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

package/dist/config/skills/pdf/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: pdf
+description: >
+  Use this skill for any task involving PDF files. Triggers include: creating
+  new PDFs from scratch, reading or extracting text and tables from PDFs,
+  merging or splitting PDFs, rotating pages, adding watermarks, encrypting or
+  decrypting PDFs, filling PDF forms, extracting images, and OCR on scanned
+  PDFs to make them searchable. Use this skill whenever the user mentions
+  .pdf, "PDF document", "create a report as PDF", "extract from PDF",
+  "merge PDFs", "split PDF", "protect PDF", "fill a form", or any
+  PDF-related task — even if not explicitly stated as such.
+
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# PDF Processing Guide
+
+## Overview
+
+This guide covers essential PDF processing operations using Python libraries
+and command-line tools. For advanced features, JavaScript libraries, and
+detailed examples, see references/REFERENCE.md. If you need to fill out a
+PDF form, read references/FORMS.md and follow its instructions.
+
+## Quick Start
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+# Read a PDF
+reader = PdfReader("document.pdf")
+print(f"Pages: {len(reader.pages)}")
+
+# Extract text
+text = ""
+for page in reader.pages:
+    text += page.extract_text()
+```
+
+## Python Libraries
+
+### pypdf — Basic Operations
+
+#### Merge PDFs
+```python
+from pypdf import PdfWriter, PdfReader
+
+writer = PdfWriter()
+for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
+    reader = PdfReader(pdf_file)
+    for page in reader.pages:
+        writer.add_page(page)
+
+with open("merged.pdf", "wb") as output:
+    writer.write(output)
+```
+
+#### Split PDF
+```python
+reader = PdfReader("input.pdf")
+for i, page in enumerate(reader.pages):
+    writer = PdfWriter()
+    writer.add_page(page)
+    with open(f"page_{i+1}.pdf", "wb") as output:
+        writer.write(output)
+```
+
+#### Extract Metadata
+```python
+reader = PdfReader("document.pdf")
+meta = reader.metadata
+print(f"Title: {meta.title}")
+print(f"Author: {meta.author}")
+print(f"Subject: {meta.subject}")
+print(f"Creator: {meta.creator}")
+```
+
+#### Rotate Pages
+```python
+reader = PdfReader("input.pdf")
+writer = PdfWriter()
+
+page = reader.pages[0]
+page.rotate(90)  # Rotate 90 degrees clockwise
+writer.add_page(page)
+
+with open("rotated.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### pdfplumber — Text and Table Extraction
+
+#### Extract Text with Layout
+```python
+import pdfplumber
+
+with pdfplumber.open("document.pdf") as pdf:
+    for page in pdf.pages:
+        text = page.extract_text()
+        print(text)
+```
+
+#### Extract Tables
+```python
+with pdfplumber.open("document.pdf") as pdf:
+    for i, page in enumerate(pdf.pages):
+        tables = page.extract_tables()
+        for j, table in enumerate(tables):
+            print(f"Table {j+1} on page {i+1}:")
+            for row in table:
+                print(row)
+```
+
+#### Advanced Table Extraction
+```python
+import pandas as pd
+
+with pdfplumber.open("document.pdf") as pdf:
+    all_tables = []
+    for page in pdf.pages:
+        tables = page.extract_tables()
+        for table in tables:
+            if table:
+                df = pd.DataFrame(table[1:], columns=table[0])
+                all_tables.append(df)
+
+if all_tables:
+    combined_df = pd.concat(all_tables, ignore_index=True)
+    combined_df.to_excel("extracted_tables.xlsx", index=False)
+```
+
+### reportlab — Create PDFs
+
+#### Basic PDF Creation
+```python
+from reportlab.lib.pagesizes import A4
+from reportlab.pdfgen import canvas
+
+c = canvas.Canvas("hello.pdf", pagesize=A4)
+width, height = A4
+
+# Add text
+c.drawString(100, height - 100, "Hello World!")
+c.drawString(100, height - 120, "This is a PDF created with reportlab")
+
+# Add a line
+c.line(100, height - 140, 400, height - 140)
+
+c.save()
+```
+
+#### Create PDF with Multiple Pages
+```python
+from reportlab.lib.pagesizes import A4
+from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
+from reportlab.lib.styles import getSampleStyleSheet
+
+doc = SimpleDocTemplate("report.pdf", pagesize=A4)
+styles = getSampleStyleSheet()
+story = []
+
+# Add content
+title = Paragraph("Report Title", styles['Title'])
+story.append(title)
+story.append(Spacer(1, 12))
+
+body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
+story.append(body)
+story.append(PageBreak())
+
+# Page 2
+story.append(Paragraph("Page 2", styles['Heading1']))
+story.append(Paragraph("Content for page 2", styles['Normal']))
+
+# Build PDF
+doc.build(story)
+```
+
+#### Subscripts and Superscripts
+
+**IMPORTANT**: Never use Unicode subscript/superscript characters (₀₁₂₃₄₅₆₇₈₉,
+⁰¹²³⁴⁵⁶⁷⁸⁹) in ReportLab PDFs. The built-in fonts do not include these glyphs,
+causing them to render as solid black boxes.
+
+pdftk file1.pdf file2.pdf cat output merged.pdf
+
+# Split
+pdftk input.pdf burst
+from reportlab.lib.styles import getSampleStyleSheet
+
+styles = getSampleStyleSheet()
+
+# Subscripts: use <sub> tag
+chemical = Paragraph("H<sub>2</sub>O", styles['Normal'])
+
+# Superscripts: use <super> tag
+squared = Paragraph("x<super>2</super> + y<super>2</super>", styles['Normal'])
+```
+
+For canvas-drawn text (not Paragraph objects), manually adjust font size and
+position rather than using Unicode subscripts/superscripts.
+
+## Command-Line Tools
+
+### pdftotext (poppler-utils)
+```bash
+# Extract text
+pdftotext input.pdf output.txt
+
+# Extract text preserving layout
+pdftotext -layout input.pdf output.txt
+
+# Extract specific pages
+pdftotext -f 1 -l 5 input.pdf output.txt  # Pages 1-5
+```
+
+### qpdf
+```bash
+# Merge PDFs
+qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf
+
+# Split pages
+qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
+qpdf input.pdf --pages . 6-10 -- pages6-10.pdf
+
+# Rotate pages
+qpdf input.pdf output.pdf --rotate=+90:1  # Rotate page 1 by 90 degrees
+
+# Remove password
+qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf
+```
+
+### pdftk (if available)
+```bash
+# Merge
+pdftk file1.pdf file2.pdf cat output merged.pdf
+
+# Split
+pdftk input.pdf burst
+
+# Rotate
+pdftk input.pdf rotate 1east output rotated.pdf
+```
+
+## Common Tasks
+
+### Extract Text from Scanned PDFs
+```python
+# Requires: pip install pytesseract pdf2image
+import pytesseract
+from pdf2image import convert_from_path
+
+# Convert PDF to images
+images = convert_from_path('scanned.pdf')
+
+# OCR each page
+text = ""
+for i, image in enumerate(images):
+    text += f"Page {i+1}:\n"
+    text += pytesseract.image_to_string(image, lang="por+eng")
+    text += "\n\n"
+
+print(text)
+```
+
+### Add Watermark
+```python
+from pypdf import PdfReader, PdfWriter
+
+# Load watermark
+watermark = PdfReader("watermark.pdf").pages[0]
+
+# Apply to all pages
+reader = PdfReader("document.pdf")
+writer = PdfWriter()
+
+for page in reader.pages:
+    page.merge_page(watermark)
+    writer.add_page(page)
+
+with open("watermarked.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### Extract Images
+```bash
+# Using pdfimages (poppler-utils)
+pdfimages -j input.pdf output_prefix
+# Extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.
+```
+
+### Password Protection
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("input.pdf")
+writer = PdfWriter()
+
+for page in reader.pages:
+    writer.add_page(page)
+
+# Add password
+writer.encrypt("userpassword", "ownerpassword")
+
+with open("encrypted.pdf", "wb") as output:
+    writer.write(output)
+```
+
+## Quick Reference
+
+| Task                  | Best Tool    | Command/Code                        |
+|-----------------------|--------------|-------------------------------------|
+| Merge PDFs            | pypdf        | `writer.add_page(page)`             |
+| Split PDFs            | pypdf        | One page per file                   |
+| Extract text          | pdfplumber   | `page.extract_text()`               |
+| Extract tables        | pdfplumber   | `page.extract_tables()`             |
+| Create PDFs           | reportlab    | Canvas or Platypus                  |
+| Command line merge    | qpdf         | `qpdf --empty --pages ...`          |
+| OCR scanned PDFs      | pytesseract  | Convert to image first              |
+| Fill PDF forms        | pypdf / pdf-lib (see FORMS.md) | See references/FORMS.md |
+
+## Next Steps
+
+- For advanced pypdfium2 usage, see references/REFERENCE.md
+- For JavaScript libraries (pdf-lib), see references/REFERENCE.md
+- If you need to fill out a PDF form, follow the instructions in references/FORMS.md
+- For troubleshooting guides, see references/REFERENCE.md