@nomad-e/bluma-cli 0.1.17 → 0.1.19

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

@@ -0,0 +1,298 @@
+---
+name: xlsx
+description: >
+  Use this skill any time a spreadsheet file is the primary input or output.
+  Triggers: open, read, edit, create, fix, or convert .xlsx, .xlsm, .csv,
+  or .tsv files — including adding columns, computing formulas, formatting,
+  charting, cleaning messy data, restructuring tabular data, or building
+  financial models. Also trigger when the user references a spreadsheet by
+  name or path and wants something done to it. The deliverable must be a
+  spreadsheet file. Do NOT trigger when the primary deliverable is a Word
+  document, HTML report, or standalone script.
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# XLSX — Spreadsheet Creation, Editing & Analysis
+
+## Core Principle
+
+> **Formulas, not hardcodes.** Every calculated value MUST be an Excel
+> formula so the spreadsheet stays dynamic. Never compute in Python and
+> paste the result into a cell.
+
+## Output Quality Standards
+
+### Professional Appearance
+- Consistent font throughout (Arial or Calibri, 10-11pt)
+- Headers bold with subtle background fill
+- Column widths auto-fitted to content
+- Number formatting applied to all numeric cells
+- Borders and alignment used consistently
+
+### Zero Formula Errors
+Every deliverable MUST have ZERO formula errors. After writing formulas,
+always run `scripts/recalc.py` and fix any errors before delivering.
+
+### Preserve Existing Templates
+When modifying an existing file, study and EXACTLY match its format,
+style, and conventions. Existing patterns override these guidelines.
+
+## Reading & Analyzing Data
+
+### Quick Analysis with pandas
+
+```python
+import pandas as pd
+
+df = pd.read_excel('file.xlsx')
+all_sheets = pd.read_excel('file.xlsx', sheet_name=None)
+
+df.head()
+df.info()
+df.describe()
+
+df.to_excel('output.xlsx', index=False)
+```
+
+### Reading with openpyxl (preserves formulas)
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook('file.xlsx')
+ws = wb.active
+
+for row in ws.iter_rows(min_row=1, max_row=5, values_only=True):
+    print(row)
+
+wb_data = load_workbook('file.xlsx', data_only=True)
+```
+
+**Warning**: Never open with `data_only=True` and save — formulas are
+permanently replaced with cached values.
+
+## Creating New Excel Files
+
+```python
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
+from openpyxl.utils import get_column_letter
+
+wb = Workbook()
+ws = wb.active
+ws.title = "Data"
+
+header_font = Font(bold=True, size=11, name='Arial')
+header_fill = PatternFill('solid', fgColor='D9E1F2')
+header_align = Alignment(horizontal='center', vertical='center')
+
+headers = ['Item', 'Qty', 'Unit Price', 'Total']
+for col, h in enumerate(headers, 1):
+    cell = ws.cell(row=1, column=col, value=h)
+    cell.font = header_font
+    cell.fill = header_fill
+    cell.alignment = header_align
+
+ws['D2'] = '=B2*C2'
+
+for col in range(1, len(headers) + 1):
+    ws.column_dimensions[get_column_letter(col)].width = 15
+
+wb.save('output.xlsx')
+```
+
+## Editing Existing Files
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook('existing.xlsx')
+ws = wb['SheetName']
+
+ws['A1'] = 'New Value'
+ws.insert_rows(2)
+ws.delete_cols(3)
+
+new_ws = wb.create_sheet('Summary')
+new_ws['A1'] = '=SUM(Data!B2:B100)'
+
+wb.save('modified.xlsx')
+```
+
+## Formula Rules
+
+### Always Use Excel Formulas
+
+```python
+# WRONG — hardcoded calculation
+total = sum(values)
+ws['B10'] = total
+
+# CORRECT — Excel formula
+ws['B10'] = '=SUM(B2:B9)'
+```
+
+This applies to ALL calculations: totals, averages, percentages,
+growth rates, ratios, conditional aggregations.
+
+### Common Formula Patterns
+
+| Operation | Formula |
+|-----------|---------|
+| Sum | `=SUM(B2:B9)` |
+| Average | `=AVERAGE(B2:B9)` |
+| Count non-empty | `=COUNTA(B2:B9)` |
+| Percentage | `=B2/B$10` |
+| Year-over-year growth | `=(C2-B2)/B2` |
+| Conditional sum | `=SUMIF(A:A,"Category",B:B)` |
+| Lookup | `=VLOOKUP(A2,Data!A:C,3,FALSE)` |
+| If/then | `=IF(B2>0,B2*C2,0)` |
+| Error handling | `=IFERROR(B2/C2,0)` |
+
+### Cross-Sheet References
+
+```python
+ws['A1'] = "=Summary!B5"
+ws['A2'] = "=VLOOKUP(A1,Data!A:C,3,FALSE)"
+```
+
+## Recalculating Formulas (MANDATORY)
+
+After creating or editing formulas with openpyxl, values are NOT
+calculated. You MUST run recalculation:
+
+```bash
+python scripts/recalc.py output.xlsx
+```
+
+The script returns JSON:
+
+```json
+{
+  "status": "success",
+  "total_errors": 0,
+  "total_formulas": 42,
+  "sheets_processed": ["Sheet1", "Summary"]
+}
+```
+
+If errors are found:
+
+```json
+{
+  "status": "errors_found",
+  "total_errors": 3,
+  "total_formulas": 42,
+  "error_summary": {
+    "#REF!": {"count": 2, "locations": ["Sheet1!B5", "Sheet1!C10"]},
+    "#DIV/0!": {"count": 1, "locations": ["Summary!D4"]}
+  }
+}
+```
+
+**Fix all errors and recalculate again until status is "success".**
+
+Common error fixes:
+- `#REF!` — Invalid cell reference; check if rows/columns were deleted
+- `#DIV/0!` — Wrap with `=IFERROR(formula, 0)`
+- `#VALUE!` — Wrong data type; check cell contents
+- `#NAME?` — Typo in function name or missing quotes on strings
+- `#N/A` — VLOOKUP/MATCH found no result; use `=IFERROR()`
+
+## Financial Model Standards
+
+### Color Coding (Industry Standard)
+
+| Color | RGB | Usage |
+|-------|-----|-------|
+| Blue text | `0000FF` | Hardcoded inputs and assumptions |
+| Black text | `000000` | All formulas and calculations |
+| Green text | `008000` | Links to other sheets in same workbook |
+| Red text | `FF0000` | External links to other files |
+| Yellow background | `FFFF00` | Key assumptions needing attention |
+
+```python
+from openpyxl.styles import Font, PatternFill
+
+input_font = Font(color='0000FF', name='Arial', size=11)
+formula_font = Font(color='000000', name='Arial', size=11)
+crossref_font = Font(color='008000', name='Arial', size=11)
+attention_fill = PatternFill('solid', fgColor='FFFF00')
+```
+
+### Number Formatting
+
+| Data Type | Format Code | Example |
+|-----------|-------------|---------|
+| Currency | `$#,##0;($#,##0);"-"` | $1,500 / ($200) / - |
+| Percentage | `0.0%` | 15.3% |
+| Multiples | `0.0x` | 8.5x |
+| Years | `@` (text) | 2024 (not 2,024) |
+| Large numbers | `$#,##0.0,,"mm"` | $1.5mm |
+| Integers | `#,##0;(#,##0);"-"` | 1,500 / (200) / - |
+
+```python
+ws['B2'].number_format = '$#,##0;($#,##0);"-"'
+ws['C2'].number_format = '0.0%'
+ws['D2'].number_format = '0.0x'
+```
+
+### Assumptions Placement
+
+Place ALL assumptions in dedicated cells with blue text. Never
+hardcode values inside formulas:
+
+```python
+ws['B3'] = 0.05
+ws['B3'].font = input_font
+ws['B3'].number_format = '0.0%'
+ws['B3'].comment = openpyxl.comments.Comment(
+    'Revenue growth assumption — Source: Management guidance FY2025',
+    'BluMa'
+)
+
+ws['C5'] = '=C4*(1+$B$3)'
+ws['C5'].font = formula_font
+```
+
+### Documentation for Hardcoded Values
+
+Every hardcoded number needs a source comment:
+- `Source: Company 10-K, FY2024, Page 45, Revenue Note`
+- `Source: Bloomberg Terminal, 2025-08-15, AAPL US Equity`
+- `Source: FactSet, Consensus Estimates, 2025-08-20`
+
+## Verification Checklist
+
+Before delivering any xlsx file:
+
+1. Run `scripts/recalc.py` — status must be "success"
+2. Spot-check 3-5 formulas against expected values
+3. Verify column mappings (Excel columns are 1-indexed)
+4. Check row offsets (DataFrame row 5 = Excel row 6 with header)
+5. Confirm no NaN or None values leaked into cells
+6. Validate number formatting on all numeric columns
+7. Ensure all hardcodes have source comments (financial models)
+8. Test edge cases: zero values, empty cells, negative numbers
+
+## Library Selection Guide
+
+| Task | Use |
+|------|-----|
+| Data analysis, filtering, grouping | pandas |
+| Formulas, formatting, styles | openpyxl |
+| Complex formatting + data analysis | Both (pandas to process, openpyxl to format) |
+| Read calculated values (no edit) | openpyxl with `data_only=True` |
+| Very large files (read-only) | openpyxl with `read_only=True` |
+
+## Available References
+
+- REFERENCE.md: Advanced financial modeling patterns, chart creation, pivot tables, conditional formatting, data validation, print layout
+
+## Available Scripts
+
+- recalc.py: Recalculate all formulas via LibreOffice and scan for errors (MANDATORY after formula changes)
+- office/soffice.py: LibreOffice process management for sandboxed environments (internal)
+- office/pack.py: Compress Office XML files into .xlsx (internal)
+- office/unpack.py: Decompress .xlsx into Office XML structure (internal)
+- office/validate.py: Validate Office XML structure against schemas (internal)

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

@@ -0,0 +1,337 @@
+# XLSX — Advanced Patterns Reference
+
+## Chart Creation with openpyxl
+
+### Bar Chart
+
+```python
+from openpyxl.chart import BarChart, Reference
+
+chart = BarChart()
+chart.type = "col"
+chart.title = "Revenue by Quarter"
+chart.y_axis.title = "Revenue ($mm)"
+chart.x_axis.title = "Quarter"
+chart.style = 10
+
+data = Reference(ws, min_col=2, min_row=1, max_col=5, max_row=10)
+cats = Reference(ws, min_col=1, min_row=2, max_row=10)
+chart.add_data(data, titles_from_data=True)
+chart.set_categories(cats)
+chart.shape = 4
+
+ws.add_chart(chart, "G2")
+```
+
+### Line Chart (Time Series)
+
+```python
+from openpyxl.chart import LineChart, Reference
+
+chart = LineChart()
+chart.title = "Revenue Trend"
+chart.y_axis.title = "Revenue ($mm)"
+chart.x_axis.title = "Year"
+chart.style = 13
+chart.width = 20
+chart.height = 12
+
+data = Reference(ws, min_col=2, min_row=1, max_col=2, max_row=10)
+cats = Reference(ws, min_col=1, min_row=2, max_row=10)
+chart.add_data(data, titles_from_data=True)
+chart.set_categories(cats)
+
+series = chart.series[0]
+series.graphicalProperties.line.width = 25000
+
+ws.add_chart(chart, "D2")
+```
+
+### Pie Chart
+
+```python
+from openpyxl.chart import PieChart, Reference
+
+chart = PieChart()
+chart.title = "Market Share"
+chart.style = 26
+
+data = Reference(ws, min_col=2, min_row=1, max_row=6)
+cats = Reference(ws, min_col=1, min_row=2, max_row=6)
+chart.add_data(data, titles_from_data=True)
+chart.set_categories(cats)
+
+ws.add_chart(chart, "D2")
+```
+
+## Conditional Formatting
+
+### Color Scale (Heatmap)
+
+```python
+from openpyxl.formatting.rule import ColorScaleRule
+
+ws.conditional_formatting.add(
+    'B2:B100',
+    ColorScaleRule(
+        start_type='min', start_color='F8696B',
+        mid_type='percentile', mid_value=50, mid_color='FFEB84',
+        end_type='max', end_color='63BE7B'
+    )
+)
+```
+
+### Data Bars
+
+```python
+from openpyxl.formatting.rule import DataBarRule
+
+ws.conditional_formatting.add(
+    'C2:C100',
+    DataBarRule(
+        start_type='min', end_type='max',
+        color='5B9BD5', showValue=True
+    )
+)
+```
+
+### Highlight Cells by Condition
+
+```python
+from openpyxl.formatting.rule import CellIsRule
+from openpyxl.styles import PatternFill
+
+red_fill = PatternFill('solid', fgColor='FFC7CE')
+green_fill = PatternFill('solid', fgColor='C6EFCE')
+
+ws.conditional_formatting.add(
+    'D2:D100',
+    CellIsRule(operator='lessThan', formula=['0'], fill=red_fill)
+)
+ws.conditional_formatting.add(
+    'D2:D100',
+    CellIsRule(operator='greaterThan', formula=['0'], fill=green_fill)
+)
+```
+
+## Data Validation (Dropdowns)
+
+```python
+from openpyxl.worksheet.datavalidation import DataValidation
+
+dv = DataValidation(
+    type="list",
+    formula1='"Option A,Option B,Option C"',
+    allow_blank=True
+)
+dv.error = "Invalid selection"
+dv.errorTitle = "Input Error"
+dv.prompt = "Select from the list"
+dv.promptTitle = "Choose Option"
+
+ws.add_data_validation(dv)
+dv.add('E2:E100')
+```
+
+### Numeric Range Validation
+
+```python
+dv_num = DataValidation(
+    type="decimal",
+    operator="between",
+    formula1=0,
+    formula2=1
+)
+dv_num.error = "Value must be between 0% and 100%"
+ws.add_data_validation(dv_num)
+dv_num.add('F2:F100')
+```
+
+## Pivot-Style Summary Tables
+
+openpyxl does not have native pivot tables. Build them manually:
+
+```python
+import pandas as pd
+from openpyxl import load_workbook
+from openpyxl.styles import Font, PatternFill, Border, Side, Alignment
+
+df = pd.read_excel('data.xlsx')
+pivot = df.pivot_table(
+    index='Category',
+    columns='Year',
+    values='Revenue',
+    aggfunc='sum',
+    margins=True,
+    margins_name='Total'
+)
+
+wb = load_workbook('data.xlsx')
+ws = wb.create_sheet('Pivot')
+
+header_font = Font(bold=True, name='Arial', size=11)
+header_fill = PatternFill('solid', fgColor='4472C4')
+header_font_white = Font(bold=True, name='Arial', size=11, color='FFFFFF')
+border = Border(
+    bottom=Side(style='thin', color='D9D9D9')
+)
+
+ws.cell(row=1, column=1, value='Category').font = header_font_white
+ws['A1'].fill = header_fill
+for j, col_name in enumerate(pivot.columns, 2):
+    cell = ws.cell(row=1, column=j, value=str(col_name))
+    cell.font = header_font_white
+    cell.fill = header_fill
+    cell.alignment = Alignment(horizontal='center')
+
+for i, (idx, row_data) in enumerate(pivot.iterrows(), 2):
+    ws.cell(row=i, column=1, value=idx).font = Font(
+        bold=(idx == 'Total'), name='Arial', size=11
+    )
+    for j, val in enumerate(row_data, 2):
+        cell = ws.cell(row=i, column=j, value=val)
+        cell.number_format = '$#,##0;($#,##0);"-"'
+        cell.border = border
+        if idx == 'Total':
+            cell.font = Font(bold=True, name='Arial', size=11)
+
+wb.save('data.xlsx')
+```
+
+## Print Layout Configuration
+
+```python
+ws.page_setup.orientation = 'landscape'
+ws.page_setup.paperSize = ws.PAPERSIZE_A4
+ws.page_setup.fitToWidth = 1
+ws.page_setup.fitToHeight = 0
+
+ws.sheet_properties.pageSetUpPr.fitToPage = True
+
+ws.oddHeader.center.text = "Company Name — Confidential"
+ws.oddFooter.left.text = "Page &P of &N"
+ws.oddFooter.right.text = "&D"
+
+ws.print_title_rows = '1:2'
+ws.print_area = 'A1:H50'
+
+ws.page_margins = openpyxl.worksheet.page.PageMargins(
+    left=0.5, right=0.5, top=0.75, bottom=0.75,
+    header=0.3, footer=0.3
+)
+```
+
+## Freeze Panes and Auto-Filter
+
+```python
+ws.freeze_panes = 'B2'
+
+ws.auto_filter.ref = f'A1:{get_column_letter(ws.max_column)}{ws.max_row}'
+```
+
+## Named Ranges
+
+```python
+from openpyxl.workbook.defined_name import DefinedName
+
+ref = f"'{ws.title}'!$B$3"
+defn = DefinedName('GrowthRate', attr_text=ref)
+wb.defined_names.add(defn)
+
+ws['C5'] = '=C4*(1+GrowthRate)'
+```
+
+## Merging Cells and Grouped Headers
+
+```python
+ws.merge_cells('A1:D1')
+ws['A1'] = 'Quarterly Revenue Summary'
+ws['A1'].font = Font(bold=True, size=14, name='Arial')
+ws['A1'].alignment = Alignment(horizontal='center')
+
+ws.merge_cells('B2:C2')
+ws['B2'] = 'Q1-Q2'
+ws.merge_cells('D2:E2')
+ws['D2'] = 'Q3-Q4'
+```
+
+## Working with Large Datasets
+
+### Write-Only Mode (memory efficient)
+
+```python
+wb = Workbook(write_only=True)
+ws = wb.create_sheet()
+
+for row_data in generate_rows():
+    ws.append(row_data)
+
+wb.save('large_output.xlsx')
+```
+
+### Read-Only Mode
+
+```python
+wb = load_workbook('large_file.xlsx', read_only=True)
+ws = wb.active
+
+for row in ws.iter_rows(min_row=2, values_only=True):
+    process(row)
+
+wb.close()
+```
+
+## Financial Model Templates
+
+### DCF Valuation Layout
+
+```
+Sheet: Assumptions
+  B3: Revenue Growth Rate (blue, input)
+  B4: EBITDA Margin (blue, input)
+  B5: Tax Rate (blue, input)
+  B6: WACC (blue, input)
+  B7: Terminal Growth (blue, input)
+
+Sheet: Projections
+  Row 1: Headers (Year 1, Year 2, ... Year 5)
+  Row 3: Revenue = =Prior*(1+Assumptions!$B$3)
+  Row 4: EBITDA = =B3*Assumptions!$B$4
+  Row 5: D&A (blue, input)
+  Row 6: EBIT = =B4-B5
+  Row 7: Tax = =B6*Assumptions!$B$5
+  Row 8: NOPAT = =B6-B7
+  Row 9: CapEx (blue, input)
+  Row 10: Change in WC (blue, input)
+  Row 11: FCF = =B8+B5-B9-B10
+
+Sheet: Valuation
+  B3: PV of FCFs = =NPV(Assumptions!$B$6, Projections!B11:F11)
+  B4: Terminal Value = =Projections!F11*(1+Assumptions!$B$7)/(Assumptions!$B$6-Assumptions!$B$7)
+  B5: PV of Terminal = =B4/(1+Assumptions!$B$6)^5
+  B6: Enterprise Value = =B3+B5
+  B7: Less: Net Debt (blue, input)
+  B8: Equity Value = =B6-B7
+  B9: Shares Outstanding (blue, input)
+  B10: Implied Price = =B8/B9
+```
+
+### Sensitivity Table
+
+```python
+base_row = 15
+scenarios = [-0.02, -0.01, 0, 0.01, 0.02]
+
+for i, delta in enumerate(scenarios):
+    col = i + 2
+    ws.cell(row=base_row, column=col, value=base_wacc + delta)
+    ws.cell(row=base_row, column=col).number_format = '0.0%'
+
+    for j, tg_delta in enumerate(scenarios):
+        row = base_row + 1 + j
+        ws.cell(row=row, column=1, value=base_tg + tg_delta)
+        ws.cell(row=row, column=1).number_format = '0.0%'
+        ws.cell(row=row, column=col).value = (
+            f'=Projections!F11*(1+A{row})/({get_column_letter(col)}{base_row}-A{row})'
+        )
+```

package/dist/config/skills/xlsx/scripts/office/__init__.py

@@ -0,0 +1,2 @@
+# office — Shared utilities for LibreOffice-based document processing.
+# Used internally by xlsx, docx, and pptx skills.

package/dist/config/skills/xlsx/scripts/office/pack.py

@@ -0,0 +1,58 @@
+"""
+Pack an unpacked Office Open XML directory back into an .xlsx/.docx/.pptx file.
+
+Office files are ZIP archives containing XML. This module compresses a
+directory structure back into a valid Office file, respecting the required
+entry order ([Content_Types].xml first).
+"""
+
+import os
+import zipfile
+
+
+CONTENT_TYPES = '[Content_Types].xml'
+
+
+def pack(source_dir: str, output_path: str) -> str:
+    """
+    Compress a directory into an Office Open XML file.
+
+    The [Content_Types].xml file is written first as required by the
+    Office Open XML specification.
+
+    Args:
+        source_dir: Path to the unpacked directory.
+        output_path: Destination .xlsx/.docx/.pptx file path.
+
+    Returns:
+        Absolute path to the created file.
+    """
+    abs_source = os.path.abspath(source_dir)
+    abs_output = os.path.abspath(output_path)
+
+    if not os.path.isdir(abs_source):
+        raise FileNotFoundError(f'Source directory not found: {abs_source}')
+
+    entries = []
+    ct_path = None
+
+    for root, _, files in os.walk(abs_source):
+        for fname in files:
+            full = os.path.join(root, fname)
+            arcname = os.path.relpath(full, abs_source)
+
+            if arcname == CONTENT_TYPES:
+                ct_path = full
+            else:
+                entries.append((full, arcname))
+
+    entries.sort(key=lambda x: x[1])
+
+    with zipfile.ZipFile(abs_output, 'w', zipfile.ZIP_DEFLATED) as zf:
+        if ct_path:
+            zf.write(ct_path, CONTENT_TYPES)
+
+        for full_path, arcname in entries:
+            zf.write(full_path, arcname)
+
+    return abs_output