@nomad-e/bluma-cli 0.1.18 → 0.1.20

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

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

@@ -0,0 +1,180 @@
+"""
+LibreOffice process management for sandboxed and standard environments.
+
+Handles:
+- Finding the soffice binary across platforms
+- Running recalculation macros in headless mode
+- Configuring Unix sockets for restricted environments
+"""
+
+import os
+import platform
+import shutil
+import subprocess
+import tempfile
+
+
+SOFFICE_SEARCH_PATHS = [
+    '/usr/bin/soffice',
+    '/usr/bin/libreoffice',
+    '/usr/lib/libreoffice/program/soffice',
+    '/snap/bin/libreoffice',
+    '/opt/libreoffice/program/soffice',
+]
+
+MACOS_PATHS = [
+    '/Applications/LibreOffice.app/Contents/MacOS/soffice',
+    os.path.expanduser('~/Applications/LibreOffice.app/Contents/MacOS/soffice'),
+]
+
+
+def find_soffice() -> str | None:
+    """Find the soffice binary on this system."""
+    found = shutil.which('soffice') or shutil.which('libreoffice')
+    if found:
+        return found
+
+    search = MACOS_PATHS if platform.system() == 'Darwin' else SOFFICE_SEARCH_PATHS
+
+    for path in search:
+        if os.path.isfile(path) and os.access(path, os.X_OK):
+            return path
+
+    return None
+
+
+def _prepare_user_profile(base_dir: str) -> str:
+    """Create a temporary user profile to avoid lock conflicts."""
+    profile_dir = os.path.join(base_dir, 'libreoffice-profile')
+    os.makedirs(profile_dir, exist_ok=True)
+    return profile_dir
+
+
+def _build_macro_content(filepath: str) -> str:
+    """Build a LibreOffice Basic macro that recalculates all sheets."""
+    abs_path = os.path.abspath(filepath)
+    url = 'file://' + abs_path.replace(' ', '%20')
+
+    return f"""
+Sub RecalcAndSave
+    Dim oDoc As Object
+    Dim oSheets As Object
+    Dim oSheet As Object
+    Dim i As Integer
+
+    oDoc = StarDesktop.loadComponentFromURL( _
+        "{url}", "_blank", 0, _
+        Array(MakePropertyValue("Hidden", True), _
+              MakePropertyValue("MacroExecutionMode", 4)))
+
+    If IsNull(oDoc) Or IsEmpty(oDoc) Then
+        MsgBox "Failed to open document"
+        Exit Sub
+    End If
+
+    oSheets = oDoc.getSheets()
+    For i = 0 To oSheets.getCount() - 1
+        oSheet = oSheets.getByIndex(i)
+    Next i
+
+    oDoc.calculateAll()
+    oDoc.calculateAll()
+
+    oDoc.store()
+    oDoc.close(True)
+End Sub
+
+Function MakePropertyValue(sName As String, vValue As Variant) As com.sun.star.beans.PropertyValue
+    Dim oProperty As New com.sun.star.beans.PropertyValue
+    oProperty.Name = sName
+    oProperty.Value = vValue
+    MakePropertyValue = oProperty
+End Function
+"""
+
+
+def run_soffice_recalc(
+    soffice_path: str,
+    filepath: str,
+    timeout: int = 60,
+) -> tuple[bool, str]:
+    """
+    Recalculate an Excel file using LibreOffice headless mode.
+
+    Returns (success: bool, message: str).
+    """
+    abs_path = os.path.abspath(filepath)
+
+    if not os.path.isfile(abs_path):
+        return False, f'File not found: {abs_path}'
+
+    with tempfile.TemporaryDirectory(prefix='bluma-lo-') as tmp_dir:
+        profile_dir = _prepare_user_profile(tmp_dir)
+
+        macro_content = _build_macro_content(abs_path)
+        macro_dir = os.path.join(
+            profile_dir, 'user', 'basic', 'Standard'
+        )
+        os.makedirs(macro_dir, exist_ok=True)
+
+        macro_file = os.path.join(macro_dir, 'BluMaRecalc.xba')
+        with open(macro_file, 'w') as f:
+            f.write('<?xml version="1.0" encoding="UTF-8"?>\n')
+            f.write('<!DOCTYPE script:module PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "module.dtd">\n')
+            f.write('<script:module xmlns:script="http://openoffice.org/2000/script" ')
+            f.write('script:name="BluMaRecalc" script:language="StarBasic">\n')
+            f.write(macro_content)
+            f.write('\n</script:module>\n')
+
+        dialog_lc = os.path.join(macro_dir, 'dialog.xlc')
+        with open(dialog_lc, 'w') as f:
+            f.write('<?xml version="1.0" encoding="UTF-8"?>\n')
+            f.write('<!DOCTYPE library:library PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "library.dtd">\n')
+            f.write('<library:library xmlns:library="http://openoffice.org/2000/library" ')
+            f.write('library:name="Standard" library:readonly="false" library:passwordprotected="false">\n')
+            f.write('</library:library>\n')
+
+        script_lc = os.path.join(macro_dir, 'script.xlc')
+        with open(script_lc, 'w') as f:
+            f.write('<?xml version="1.0" encoding="UTF-8"?>\n')
+            f.write('<!DOCTYPE library:library PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "library.dtd">\n')
+            f.write('<library:library xmlns:library="http://openoffice.org/2000/library" ')
+            f.write('library:name="Standard" library:readonly="false" library:passwordprotected="false">\n')
+            f.write(f' <library:element library:name="BluMaRecalc"/>\n')
+            f.write('</library:library>\n')
+
+        env = os.environ.copy()
+        env['HOME'] = tmp_dir
+        env['SAL_USE_VCLPLUGIN'] = 'gen'
+
+        cmd = [
+            soffice_path,
+            '--headless',
+            '--invisible',
+            '--nologo',
+            '--norestore',
+            f'-env:UserInstallation=file://{profile_dir}',
+            f'macro:///Standard.BluMaRecalc.RecalcAndSave',
+        ]
+
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                env=env,
+            )
+
+            if proc.returncode != 0:
+                stderr = proc.stderr.strip()[:500] if proc.stderr else 'No error output'
+                return False, f'LibreOffice exited with code {proc.returncode}: {stderr}'
+
+            return True, 'Recalculation completed'
+
+        except subprocess.TimeoutExpired:
+            return False, f'LibreOffice timed out after {timeout} seconds'
+        except FileNotFoundError:
+            return False, f'soffice binary not found at: {soffice_path}'
+        except Exception as e:
+            return False, f'Unexpected error: {str(e)}'

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

@@ -0,0 +1,63 @@
+"""
+Unpack an Office Open XML file (.xlsx/.docx/.pptx) into a directory.
+
+This allows direct manipulation of the internal XML structure, which is
+useful for repairs, validation, or modifications not possible through
+standard libraries.
+"""
+
+import os
+import zipfile
+
+
+def unpack(filepath: str, dest_dir: str | None = None) -> str:
+    """
+    Extract an Office file into a directory.
+
+    Args:
+        filepath: Path to the .xlsx/.docx/.pptx file.
+        dest_dir: Destination directory. If None, creates one next to
+                  the source file with '_unpacked' suffix.
+
+    Returns:
+        Absolute path to the unpacked directory.
+    """
+    abs_path = os.path.abspath(filepath)
+
+    if not os.path.isfile(abs_path):
+        raise FileNotFoundError(f'File not found: {abs_path}')
+
+    if dest_dir is None:
+        base = os.path.splitext(abs_path)[0]
+        dest_dir = base + '_unpacked'
+
+    abs_dest = os.path.abspath(dest_dir)
+    os.makedirs(abs_dest, exist_ok=True)
+
+    try:
+        with zipfile.ZipFile(abs_path, 'r') as zf:
+            zf.extractall(abs_dest)
+    except zipfile.BadZipFile:
+        raise ValueError(f'Not a valid Office/ZIP file: {abs_path}')
+
+    return abs_dest
+
+
+def list_contents(filepath: str) -> list[dict]:
+    """
+    List the internal structure of an Office file.
+
+    Returns a list of dicts with 'name', 'size', and 'compressed_size'.
+    """
+    abs_path = os.path.abspath(filepath)
+
+    with zipfile.ZipFile(abs_path, 'r') as zf:
+        return [
+            {
+                'name': info.filename,
+                'size': info.file_size,
+                'compressed_size': info.compress_size,
+            }
+            for info in zf.infolist()
+            if not info.is_dir()
+        ]