@nomad-e/bluma-cli 0.1.17 → 0.1.19

package/dist/config/skills/pdf/references/FORMS.md

@@ -0,0 +1,69 @@
+# PDF Forms — Filling and Processing Guide
+
+This reference covers PDF form filling using Python and JavaScript libraries.
+
+## Detecting Form Fields (Python)
+
+```python
+from pypdf import PdfReader
+
+reader = PdfReader("form.pdf")
+fields = reader.get_fields()
+for name, field in fields.items():
+    print(f"Field: {name}, Type: {field.get('/FT')}, Value: {field.get('/V')}")
+```
+
+## Filling Forms with pypdf
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("form.pdf")
+writer = PdfWriter()
+writer.append(reader)
+
+writer.update_page_form_field_values(
+    writer.pages[0],
+    {
+        "name_field": "John Doe",
+        "email_field": "john@example.com",
+        "date_field": "2026-01-15",
+    }
+)
+
+with open("filled_form.pdf", "wb") as output:
+    writer.write(output)
+```
+
+## Filling Forms with pdf-lib (JavaScript)
+
+```javascript
+import { PDFDocument } from 'pdf-lib';
+import fs from 'fs';
+
+const pdfBytes = fs.readFileSync('form.pdf');
+const pdfDoc = await PDFDocument.load(pdfBytes);
+const form = pdfDoc.getForm();
+
+form.getTextField('name').setText('John Doe');
+form.getTextField('email').setText('john@example.com');
+form.getCheckBox('agree').check();
+
+const filledBytes = await pdfDoc.save();
+fs.writeFileSync('filled_form.pdf', filledBytes);
+```
+
+## Common Form Field Types
+
+| Type | pypdf Code | pdf-lib Code |
+|------|-----------|-------------|
+| Text | `update_page_form_field_values` | `getTextField().setText()` |
+| Checkbox | Set to `/Yes` or `/Off` | `getCheckBox().check()` |
+| Radio | Set to option value | `getRadioGroup().select()` |
+| Dropdown | Set to option value | `getDropdown().select()` |
+
+## Tips
+
+- Always flatten forms after filling if the PDF will be shared (prevents editing).
+- Some PDFs have XFA forms (XML-based) which are harder to fill programmatically.
+- For XFA forms, consider using pdftk or a commercial library.

package/dist/config/skills/pdf/references/REFERENCE.md

@@ -0,0 +1,52 @@
+# PDF Processing — Advanced Reference
+
+This document covers advanced PDF processing techniques beyond the basics in SKILL.md.
+
+## pypdfium2 — High-Performance Rendering
+
+```python
+import pypdfium2 as pdfium
+
+pdf = pdfium.PdfDocument("document.pdf")
+for i, page in enumerate(pdf):
+    bitmap = page.render(scale=2)
+    image = bitmap.to_pil()
+    image.save(f"page_{i+1}.png")
+```
+
+## JavaScript Libraries (pdf-lib)
+
+For browser-based or Node.js PDF manipulation:
+
+```javascript
+import { PDFDocument } from 'pdf-lib';
+
+const pdfDoc = await PDFDocument.create();
+const page = pdfDoc.addPage([600, 400]);
+page.drawText('Hello, PDF!', { x: 50, y: 350, size: 30 });
+const pdfBytes = await pdfDoc.save();
+```
+
+## pdf-lib — Modify Existing PDFs
+
+```javascript
+import { PDFDocument } from 'pdf-lib';
+import fs from 'fs';
+
+const existingPdfBytes = fs.readFileSync('input.pdf');
+const pdfDoc = await PDFDocument.load(existingPdfBytes);
+const pages = pdfDoc.getPages();
+const firstPage = pages[0];
+firstPage.drawText('WATERMARK', { x: 200, y: 400, size: 50, opacity: 0.3 });
+const pdfBytes = await pdfDoc.save();
+fs.writeFileSync('output.pdf', pdfBytes);
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "PdfReadError: EOF marker not found" | File is corrupted or not a valid PDF |
+| Empty text extraction | PDF might be image-based; use OCR (pytesseract) |
+| Tables not extracted correctly | Adjust pdfplumber table settings or try camelot |
+| Large PDF processing slow | Process pages in chunks or use pypdfium2 |

package/dist/config/skills/pdf/scripts/create_report.py

@@ -0,0 +1,59 @@
+"""
+Create a simple PDF report from CSV data using reportlab.
+
+Usage:
+    python create_report.py --input data.csv --output ./artifacts/report.pdf
+    python create_report.py --input data.csv --output report.pdf --title "Sales Report Q1 2026"
+"""
+import argparse
+import csv
+import sys
+
+def create_report(input_csv: str, output_pdf: str, title: str = "Report") -> None:
+    try:
+        from reportlab.lib.pagesizes import A4
+        from reportlab.lib import colors
+        from reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Paragraph, Spacer
+        from reportlab.lib.styles import getSampleStyleSheet
+    except ImportError:
+        print("Error: reportlab is required. Install with: pip install reportlab", file=sys.stderr)
+        sys.exit(1)
+
+    with open(input_csv, "r", encoding="utf-8") as f:
+        reader = csv.reader(f)
+        data = list(reader)
+
+    if not data:
+        print("Error: CSV file is empty", file=sys.stderr)
+        sys.exit(1)
+
+    doc = SimpleDocTemplate(output_pdf, pagesize=A4)
+    styles = getSampleStyleSheet()
+    elements = []
+
+    elements.append(Paragraph(title, styles["Title"]))
+    elements.append(Spacer(1, 20))
+
+    table = Table(data)
+    table.setStyle(TableStyle([
+        ("BACKGROUND", (0, 0), (-1, 0), colors.grey),
+        ("TEXTCOLOR", (0, 0), (-1, 0), colors.whitesmoke),
+        ("ALIGN", (0, 0), (-1, -1), "CENTER"),
+        ("FONTNAME", (0, 0), (-1, 0), "Helvetica-Bold"),
+        ("FONTSIZE", (0, 0), (-1, 0), 12),
+        ("BOTTOMPADDING", (0, 0), (-1, 0), 12),
+        ("BACKGROUND", (0, 1), (-1, -1), colors.beige),
+        ("GRID", (0, 0), (-1, -1), 1, colors.black),
+    ]))
+    elements.append(table)
+
+    doc.build(elements)
+    print(f"Report created: {output_pdf} ({len(data)-1} data rows)")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Create PDF report from CSV")
+    parser.add_argument("--input", "-i", required=True, help="Input CSV file")
+    parser.add_argument("--output", "-o", required=True, help="Output PDF path")
+    parser.add_argument("--title", "-t", default="Report", help="Report title")
+    args = parser.parse_args()
+    create_report(args.input, args.output, args.title)

package/dist/config/skills/pdf/scripts/merge_pdfs.py

@@ -0,0 +1,39 @@
+"""
+Merge multiple PDF files into a single output PDF.
+
+Usage:
+    python merge_pdfs.py --output merged.pdf file1.pdf file2.pdf file3.pdf
+    python merge_pdfs.py --output ./artifacts/combined.pdf *.pdf
+"""
+import argparse
+import sys
+
+def merge_pdfs(input_files: list[str], output_path: str) -> None:
+    try:
+        from pypdf import PdfWriter, PdfReader
+    except ImportError:
+        print("Error: pypdf is required. Install with: pip install pypdf", file=sys.stderr)
+        sys.exit(1)
+
+    writer = PdfWriter()
+    for pdf_file in input_files:
+        try:
+            reader = PdfReader(pdf_file)
+            for page in reader.pages:
+                writer.add_page(page)
+            print(f"Added: {pdf_file} ({len(reader.pages)} pages)")
+        except Exception as e:
+            print(f"Error reading {pdf_file}: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    with open(output_path, "wb") as f:
+        writer.write(f)
+
+    print(f"Merged {len(input_files)} files -> {output_path}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Merge PDF files")
+    parser.add_argument("files", nargs="+", help="PDF files to merge")
+    parser.add_argument("--output", "-o", required=True, help="Output file path")
+    args = parser.parse_args()
+    merge_pdfs(args.files, args.output)

package/dist/config/skills/skill-creator/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/skill-creator/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: skill-creator
+description: >
+  Use this skill when the user wants to create, write, build, or author a new
+  BluMa skill. Triggers include: "create a skill", "make a new skill",
+  "build a skill for X", "I need a skill that does Y", "skill template",
+  or any request to package knowledge/workflows as a reusable skill module.
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# Instructions
+
+## Context
+You are a Skill Builder. You create new BluMa skills with the full Progressive Disclosure structure. Every skill you create MUST follow the standard layout.
+
+## Standard Skill Layout
+
+Every skill is a directory with this structure:
+
+```
+skill-name/
+  SKILL.md              # Core instructions (Level 2)
+  LICENSE.txt           # License terms
+  references/           # Additional docs loaded on-demand (Level 3a)
+    REFERENCE.md        # Advanced guide (if applicable)
+  scripts/              # Ready-made scripts (Level 3b)
+    (domain-relevant scripts)
+```
+
+The 3 levels of Progressive Disclosure:
+- **Level 1**: `description` in frontmatter — always visible in the skills list, acts as a trigger
+- **Level 2**: Body of SKILL.md — loaded when the skill is activated via `load_skill`
+- **Level 3**: `references/` and `scripts/` — accessed only when the task requires them
+
+## Procedure
+
+### Step 1: Ask Location (REQUIRED)
+
+Before anything else, ask the user where to create the skill:
+
+```
+message({
+  content: "Where should I create this skill?\n\n**1. Project** (`.bluma/skills/`) - Only available in THIS project\n**2. Global** (`~/.bluma/skills/`) - Available in ALL projects\n\nChoose 1 or 2:",
+  message_type: "result"
+})
+```
+
+Wait for user response before continuing.
+
+### Step 2: Analyze User Input
+
+Extract from user's content:
+- Purpose/domain
+- Responsibilities and workflows
+- Rules/constraints
+- Error scenarios
+- Whether the content is short (<100 lines) or extensive (>100 lines)
+
+### Step 3: Generate Skill Name
+
+Create kebab-case name from domain:
+- "git workflow" -> `git-workflow`
+- "api testing" -> `api-testing`
+- "pdf processing" -> `pdf`
+
+### Step 4: Determine Path
+
+Based on user's choice in Step 1:
+- **Project (1)**: `.bluma/skills/{name}/`
+- **Global (2)**: `~/.bluma/skills/{name}/`
+
+### Step 5: Check Directory
+
+```
+ls_tool({ path: "{chosen-path}/{name}" })
+```
+
+Verify directory doesn't exist (or confirm overwrite with user).
+
+### Step 6: Plan Content Split
+
+Decide what goes where based on content size:
+
+**If content is SHORT (<100 lines):**
+- Everything goes in SKILL.md body
+- references/ gets a minimal REFERENCE.md placeholder
+- scripts/ stays empty (or gets a single utility script if applicable)
+
+**If content is EXTENSIVE (>100 lines):**
+- SKILL.md body gets: overview, quick start, core procedure (the essentials)
+- references/ gets: advanced docs, detailed API guides, specialized topics
+- scripts/ gets: reusable scripts the agent can execute
+
+### Step 7: Create the Skill Structure
+
+Create the following files in order:
+
+**7a. Create SKILL.md**
+
+Use `edit_tool` with this template:
+
+```markdown
+---
+name: {kebab-case-name}
+description: >
+  Use this skill for any task involving {domain}. Triggers include: {list
+  of trigger phrases and keywords that should activate this skill}. Use
+  this skill whenever the user mentions {key terms} or any {domain}-related
+  task.
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# {Domain} Guide
+
+## Overview
+
+{Brief description of what this skill covers and when to use it.}
+{If extensive content exists in references/, mention it here:}
+{For advanced features, see references/REFERENCE.md.}
+
+## Quick Start
+
+{Minimal example to get started — 5-10 lines max.}
+
+## Procedure
+
+### Step 1: {First Action}
+{Instructions}
+
+### Step 2: {Second Action}
+{Instructions}
+
+## Error Reference
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| {error} | {cause} | {fix} |
+
+## Available References
+
+{List each reference file with when to use it:}
+- REFERENCE.md: For advanced features and detailed API docs
+{Add more as needed}
+
+## Available Scripts
+
+{List each script with what it does:}
+- {script_name.py}: {one-line description}
+{Or "No scripts available for this skill." if none}
+
+## Next Steps
+
+{Point to references/ for advanced topics.}
+{Point to scripts/ for automation.}
+```
+
+**7b. Create LICENSE.txt**
+
+```
+edit_tool({
+  file_path: "{path}/{name}/LICENSE.txt",
+  old_string: "",
+  new_string: "© 2026 NomadEngenuity LDA. All rights reserved.\n\nLICENSE: Use of these materials..."
+})
+```
+
+Use the standard NomadEngenuity proprietary license (same as other native skills).
+
+**7c. Create references/REFERENCE.md**
+
+If extensive content exists, put advanced documentation here.
+If content is short, create a placeholder:
+
+```markdown
+# {Domain} — Advanced Reference
+
+{Advanced documentation, detailed examples, specialized topics.}
+{This file is loaded on-demand when the task requires deeper knowledge.}
+```
+
+**7d. Create scripts/ (if applicable)**
+
+If the domain benefits from ready-made scripts, create them.
+Each script should:
+- Be self-contained and executable with `python script.py [args]`
+- Include a docstring explaining what it does
+- Accept arguments via argparse or sys.argv
+- Print results to stdout or write to a specified output path
+
+Example script header:
+```python
+"""
+{description of what this script does}
+
+Usage:
+    python {script_name}.py --input data.csv --output ./artifacts/result.pdf
+"""
+import argparse
+```
+
+### Step 8: Report Result
+
+```
+message({
+  content: "Skill **{name}** created at `{path}/{name}/`\n\nStructure:\n- SKILL.md (core instructions)\n- LICENSE.txt\n- references/REFERENCE.md\n- scripts/ {list or empty}\n\nLocation: {Project|Global}\nThe skill is now available and will appear in the skills list.",
+  message_type: "result"
+})
+```
+
+## Location Reference
+
+| Location | Path | Scope | Use When |
+|----------|------|-------|----------|
+| Project | `.bluma/skills/` | This project only | Skill is specific to this codebase |
+| Global | `~/.bluma/skills/` | All projects | Skill is generic and reusable |
+
+## Guidelines
+
+- ALWAYS ask location first with `message_type: "result"`
+- ALWAYS create the full structure: SKILL.md + LICENSE.txt + references/ + scripts/
+- The `description` field is CRITICAL — it is the only text always visible and determines when the skill is activated. Include trigger words and phrases.
+- SKILL.md body should contain only the essentials (quick start + procedure). Advanced docs go in references/.
+- Scripts should be self-contained, executable, and well-documented.
+- Use lists not tables where possible (saves tokens)
+- No emojis in skill content
+- English only for skill content (translate user input if needed)
+- Professional, specific language
+- Extract ALL information from user input
+- NEVER create a skill with the same name as a native BluMa skill (check available_skills list first)

package/dist/config/skills/xlsx/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.