@cteno/sdk-linux-x64 0.0.0-stage → 2.10.13

package/skills/xlsx/scripts/xlsx_create.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""Create an .xlsx workbook from a JSON spec.
+
+Spec (JSON object):
+  {
+    "full_calc_on_load": true,          # force recalculation on open (optional)
+    "defined_names": {"Rates": "'Data'!$B$2:$B$4"},   # workbook scope
+    "sheets": [
+      {
+        "name": "Data",
+        "rows": [["Header", 1, true], ...],   # scalars or cell objects (see below)
+        "cells": {"A1": {"value": 5, "format": "0.00%"}},  # sparse overrides
+        "column_widths": {"A": 22, "B": 12},
+        "row_heights": {"1": 24},
+        "merges": ["A1:C1"],
+        "freeze_panes": "A2",
+        "autofilter": "A1:C10",
+        "conditional_formats": [
+          {"range": "B2:B9", "type": "cell_is", "operator": "greaterThan",
+           "formula": ["100"], "fill": "FFC7CE"},
+          {"range": "C2:C9", "type": "color_scale"}
+        ],
+        "charts": [
+          {"type": "bar", "title": "Sales", "anchor": "F2",
+           "data": "B1:B5", "categories": "A2:A5"}
+        ],
+        "validations": [
+          {"range": "D2:D9", "type": "list", "formula1": "\"Yes,No,Maybe\""}
+        ],
+        "tables": [
+          {"name": "Sales", "range": "A1:C4",
+           "style": "TableStyleMedium9"}        # native Excel table
+        ],
+        "protection": {"password": "your-password",   # NOT security --
+                       "unlock": ["B2:B9"]}           # see SKILL.md Pitfalls
+      }
+    ]
+  }
+
+Cell object keys (all optional except value/formula):
+  value          scalar; JSON true/false -> bool, numbers stay numeric
+  type           "date" or "datetime" -> value parsed from ISO string
+  formula        e.g. "=SUM(A2:A9)" (leading '=' optional)
+  hyperlink      URL; value becomes the display text
+  note           cell note text (or {"text": ..., "author": ...})
+  format         Excel number format, e.g. "$#,##0.00", "0.0%", "yyyy-mm-dd"
+  bold, italic   booleans
+  font_size      points
+  font_color     hex RGB like "FF0000"
+  fill           solid fill hex RGB like "DDEBF7"
+  border         "thin" | "medium" | "thick" (all four sides)
+  align          "left" | "center" | "right"
+  valign         "top" | "center" | "bottom"
+  wrap           boolean (wrap text)
+
+Usage:
+  xlsx_create.py spec.json out.xlsx
+  xlsx_create.py - out.xlsx   (spec on stdin)
+
+Prints a JSON summary to stdout; exits non-zero on failure.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import date, datetime
+
+from openpyxl import Workbook
+from openpyxl.chart import BarChart, LineChart, PieChart, Reference
+from openpyxl.comments import Comment
+from openpyxl.formatting.rule import CellIsRule, ColorScaleRule
+from openpyxl.styles import (Alignment, Border, Font, PatternFill,
+                             Protection, Side)
+from openpyxl.utils import column_index_from_string, range_boundaries
+from openpyxl.workbook.defined_name import DefinedName
+from openpyxl.worksheet.datavalidation import DataValidation
+from openpyxl.worksheet.table import Table, TableStyleInfo
+
+
+def parse_typed(value, type_hint=None):
+    if type_hint == "date" and isinstance(value, str):
+        return date.fromisoformat(value)
+    if type_hint == "datetime" and isinstance(value, str):
+        return datetime.fromisoformat(value)
+    return value
+
+
+def apply_cell(ws, coord, spec):
+    cell = ws[coord]
+    if isinstance(spec, dict):
+        if "formula" in spec:
+            f = spec["formula"]
+            cell.value = f if f.startswith("=") else "=" + f
+        elif "value" in spec:
+            cell.value = parse_typed(spec["value"], spec.get("type"))
+        if "hyperlink" in spec:
+            cell.hyperlink = spec["hyperlink"]
+            if cell.value is None:
+                cell.value = spec["hyperlink"]
+            cell.style = "Hyperlink"
+        if "note" in spec:
+            note = spec["note"]
+            if isinstance(note, dict):
+                cell.comment = Comment(note.get("text", ""),
+                                       note.get("author", "xlsx-skill"))
+            else:
+                cell.comment = Comment(str(note), "xlsx-skill")
+        if "format" in spec:
+            cell.number_format = spec["format"]
+        font_kw = {}
+        if spec.get("bold"):
+            font_kw["bold"] = True
+        if spec.get("italic"):
+            font_kw["italic"] = True
+        if "font_size" in spec:
+            font_kw["size"] = spec["font_size"]
+        if "font_color" in spec:
+            font_kw["color"] = spec["font_color"]
+        if font_kw:
+            cell.font = Font(**font_kw)
+        if "fill" in spec:
+            cell.fill = PatternFill("solid", fgColor=spec["fill"])
+        if "border" in spec:
+            side = Side(style=spec["border"])
+            cell.border = Border(left=side, right=side, top=side, bottom=side)
+        align_kw = {}
+        if "align" in spec:
+            align_kw["horizontal"] = spec["align"]
+        if "valign" in spec:
+            align_kw["vertical"] = spec["valign"]
+        if spec.get("wrap"):
+            align_kw["wrap_text"] = True
+        if align_kw:
+            cell.alignment = Alignment(**align_kw)
+    else:
+        cell.value = spec
+
+
+def ref_from_range(ws, rng):
+    min_col, min_row, max_col, max_row = range_boundaries(rng)
+    return Reference(ws, min_col=min_col, min_row=min_row,
+                     max_col=max_col, max_row=max_row)
+
+
+def add_chart(ws, spec):
+    kind = spec.get("type", "bar")
+    chart = {"bar": BarChart, "line": LineChart, "pie": PieChart}[kind]()
+    if "title" in spec:
+        chart.title = spec["title"]
+    data = ref_from_range(ws, spec["data"])
+    chart.add_data(data, titles_from_data=spec.get("titles_from_data", True))
+    if "categories" in spec:
+        chart.set_categories(ref_from_range(ws, spec["categories"]))
+    ws.add_chart(chart, spec.get("anchor", "H2"))
+
+
+def add_conditional(ws, spec):
+    rng = spec["range"]
+    kind = spec.get("type", "cell_is")
+    if kind == "color_scale":
+        rule = ColorScaleRule(
+            start_type="min", start_color=spec.get("start_color", "FFF8696B"),
+            end_type="max", end_color=spec.get("end_color", "FF63BE7B"))
+    else:
+        fill = PatternFill("solid", fgColor=spec.get("fill", "FFC7CE"))
+        rule = CellIsRule(operator=spec.get("operator", "greaterThan"),
+                          formula=spec.get("formula", ["0"]), fill=fill)
+    ws.conditional_formatting.add(rng, rule)
+
+
+def build_sheet(ws, spec):
+    for row in spec.get("rows", []):
+        values, styled = [], []
+        for item in row:
+            if isinstance(item, dict):
+                values.append(None)
+                styled.append(item)
+            else:
+                values.append(item)
+                styled.append(None)
+        ws.append(values)
+        r = ws.max_row
+        for idx, item in enumerate(styled, start=1):
+            if item is not None:
+                apply_cell(ws, ws.cell(row=r, column=idx).coordinate, item)
+    for coord, cell_spec in spec.get("cells", {}).items():
+        apply_cell(ws, coord, cell_spec)
+    for col, width in spec.get("column_widths", {}).items():
+        ws.column_dimensions[col].width = width
+    for row, height in spec.get("row_heights", {}).items():
+        ws.row_dimensions[int(row)].height = height
+    for rng in spec.get("merges", []):
+        ws.merge_cells(rng)
+    if spec.get("freeze_panes"):
+        ws.freeze_panes = spec["freeze_panes"]
+    if spec.get("autofilter"):
+        ws.auto_filter.ref = spec["autofilter"]
+    for cf in spec.get("conditional_formats", []):
+        add_conditional(ws, cf)
+    for ch in spec.get("charts", []):
+        add_chart(ws, ch)
+    for dv_spec in spec.get("validations", []):
+        dv = DataValidation(type=dv_spec.get("type", "list"),
+                            formula1=dv_spec["formula1"],
+                            allow_blank=dv_spec.get("allow_blank", True))
+        dv.add(dv_spec["range"])
+        ws.add_data_validation(dv)
+    for t_spec in spec.get("tables", []):
+        table = Table(displayName=t_spec["name"], ref=t_spec["range"])
+        table.tableStyleInfo = TableStyleInfo(
+            name=t_spec.get("style", "TableStyleMedium9"),
+            showRowStripes=t_spec.get("row_stripes", True),
+            showColumnStripes=t_spec.get("column_stripes", False))
+        ws.add_table(table)
+    prot = spec.get("protection")
+    if prot:
+        for rng in prot.get("unlock", []):
+            for row in ws[rng]:
+                for cell in row:
+                    cell.protection = Protection(locked=False)
+        if prot.get("password"):
+            ws.protection.password = prot["password"]
+        ws.protection.sheet = True
+
+
+def main(argv=None):
+    # Text I/O is UTF-8 regardless of the locale (GBK on Chinese Windows).
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    ap = argparse.ArgumentParser(description="Create .xlsx from a JSON spec.")
+    ap.add_argument("spec", help="path to JSON spec, or '-' for stdin")
+    ap.add_argument("output", help="output .xlsx path")
+    args = ap.parse_args(argv)
+
+    if args.spec == "-":
+        spec = json.load(sys.stdin)
+    else:
+        with open(args.spec, encoding="utf-8") as fh:
+            spec = json.load(fh)
+
+    wb = Workbook()
+    wb.remove(wb.active)
+    for sheet_spec in spec.get("sheets", []):
+        ws = wb.create_sheet(sheet_spec.get("name", "Sheet1"))
+        build_sheet(ws, sheet_spec)
+    for name, ref in spec.get("defined_names", {}).items():
+        wb.defined_names[name] = DefinedName(name, attr_text=ref)
+    if spec.get("full_calc_on_load"):
+        wb.calculation.fullCalcOnLoad = True
+    wb.save(args.output)
+    print(json.dumps({"ok": True, "output": args.output,
+                      "sheets": wb.sheetnames}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:
+        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+        sys.exit(1)

package/skills/xlsx/scripts/xlsx_edit.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Edit an existing .xlsx workbook in place (or to --out).
+
+Operations (repeatable where noted, applied in the order listed below):
+  --rename-sheet OLD:NEW        rename a sheet
+  --copy-sheet SRC:NEW          duplicate a sheet under a new name
+  --insert-rows IDX[:N]         insert N rows before row IDX (default N=1)
+  --delete-rows IDX[:N]         delete N rows starting at row IDX
+  --insert-cols IDX[:N]         insert N columns before column IDX (number)
+  --delete-cols IDX[:N]         delete N columns starting at column IDX
+  --set CELL=VALUE              repeatable; type-inferred (int, float, bool,
+                                ISO date, else string). '=...' sets a formula.
+  --append ROWJSON              repeatable; JSON array appended as a row
+  --add-table NAME:RANGE[:STYLE]  create a native Excel table (ListObject)
+  --table-append NAME=ROWJSON   append a row inside a table, auto-extending
+                                the table's range (repeatable)
+  --list-tables                 print tables on the target sheet and exit
+  --define-name NAME=REF        workbook-scope defined name, e.g.
+                                "Rates='Data'!$B$2:$B$9" (repeatable)
+  --delete-name NAME            remove a defined name (repeatable)
+  --hyperlink CELL=URL[|TEXT]   set a hyperlink (optional display text)
+  --note CELL=TEXT[|AUTHOR]     set a cell note/comment (repeatable)
+  --clear-note CELL             remove a cell note (repeatable)
+  --protect [PASSWORD]          enable sheet protection; combine with
+                                --unlock RANGE to leave ranges editable.
+                                NOT security: trivially strippable (see
+                                SKILL.md Pitfalls).
+  --recalc                      set fullCalcOnLoad so Excel/LibreOffice
+                                recomputes all formulas on next open
+
+WARNING: openpyxl does NOT shift merged-cell ranges, chart anchors, or
+formula references when rows/columns are inserted or deleted. Verify any
+sheet containing merges or formulas after structural edits — or use
+xlsx_restructure.py, which rewrites references for you.
+
+Usage:
+  xlsx_edit.py book.xlsx --sheet Data --set B2=42 --set C2=2026-01-01 \
+      --set "D2==SUM(B2:C2)" --recalc
+  xlsx_edit.py book.xlsx --sheet Data --append '["Widget", 9.99, true]'
+  xlsx_edit.py book.xlsx --copy-sheet Data:Backup --rename-sheet Data:Main
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import date, datetime
+
+from openpyxl import load_workbook
+from openpyxl.comments import Comment
+from openpyxl.styles import Protection
+from openpyxl.utils import get_column_letter, range_boundaries
+from openpyxl.workbook.defined_name import DefinedName
+from openpyxl.worksheet.table import Table, TableStyleInfo
+
+
+def infer(text):
+    if text.startswith("="):
+        return text  # formula
+    low = text.lower()
+    if low in ("true", "false"):
+        return low == "true"
+    for caster in (int, float):
+        try:
+            return caster(text)
+        except ValueError:
+            pass
+    for parser in (date.fromisoformat, datetime.fromisoformat):
+        try:
+            return parser(text)
+        except ValueError:
+            pass
+    return text
+
+
+def parse_idx(arg):
+    if ":" in arg:
+        idx, n = arg.split(":", 1)
+        return int(idx), int(n)
+    return int(arg), 1
+
+
+def add_table(ws, spec):
+    parts = spec.split(":")
+    if len(parts) < 3:
+        raise ValueError("--add-table needs NAME:RANGE like Sales:A1:C9")
+    name = parts[0]
+    rng = ":".join(parts[1:3])
+    style = parts[3] if len(parts) > 3 else "TableStyleMedium9"
+    table = Table(displayName=name, ref=rng)
+    table.tableStyleInfo = TableStyleInfo(name=style, showRowStripes=True)
+    ws.add_table(table)
+
+
+def table_append(ws, name, row_values):
+    table = ws.tables[name]
+    min_col, min_row, max_col, max_row = range_boundaries(table.ref)
+    new_row = max_row + 1
+    for offset, value in enumerate(row_values):
+        ws.cell(row=new_row, column=min_col + offset, value=value)
+    table.ref = (f"{get_column_letter(min_col)}{min_row}:"
+                 f"{get_column_letter(max_col)}{new_row}")
+
+
+def main(argv=None):
+    # Text I/O is UTF-8 regardless of the locale (GBK on Chinese Windows).
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    ap = argparse.ArgumentParser(
+        description="Edit an existing .xlsx workbook.",
+        epilog="Plain insert/delete does not shift merges/formula refs — "
+               "use xlsx_restructure.py for reference-aware moves.")
+    ap.add_argument("file", help="path to .xlsx file")
+    ap.add_argument("--sheet", help="target sheet (default: active)")
+    ap.add_argument("--out", help="output path (default: edit in place)")
+    ap.add_argument("--rename-sheet", action="append", default=[],
+                    metavar="OLD:NEW")
+    ap.add_argument("--copy-sheet", action="append", default=[],
+                    metavar="SRC:NEW")
+    ap.add_argument("--insert-rows", action="append", default=[],
+                    metavar="IDX[:N]")
+    ap.add_argument("--delete-rows", action="append", default=[],
+                    metavar="IDX[:N]")
+    ap.add_argument("--insert-cols", action="append", default=[],
+                    metavar="IDX[:N]")
+    ap.add_argument("--delete-cols", action="append", default=[],
+                    metavar="IDX[:N]")
+    ap.add_argument("--set", action="append", default=[], metavar="CELL=VALUE")
+    ap.add_argument("--append", action="append", default=[], metavar="ROWJSON")
+    ap.add_argument("--add-table", action="append", default=[],
+                    metavar="NAME:RANGE[:STYLE]")
+    ap.add_argument("--table-append", action="append", default=[],
+                    metavar="NAME=ROWJSON")
+    ap.add_argument("--list-tables", action="store_true",
+                    help="print tables on the target sheet and exit")
+    ap.add_argument("--define-name", action="append", default=[],
+                    metavar="NAME=REF")
+    ap.add_argument("--delete-name", action="append", default=[],
+                    metavar="NAME")
+    ap.add_argument("--hyperlink", action="append", default=[],
+                    metavar="CELL=URL[|TEXT]")
+    ap.add_argument("--note", action="append", default=[],
+                    metavar="CELL=TEXT[|AUTHOR]")
+    ap.add_argument("--clear-note", action="append", default=[],
+                    metavar="CELL")
+    ap.add_argument("--protect", nargs="?", const="", metavar="PASSWORD",
+                    help="protect the target sheet (integrity signal only, "
+                    "NOT security)")
+    ap.add_argument("--unlock", action="append", default=[], metavar="RANGE",
+                    help="cell range left editable under --protect")
+    ap.add_argument("--recalc", action="store_true",
+                    help="force full recalculation when the file is opened")
+    args = ap.parse_args(argv)
+
+    wb = load_workbook(args.file)
+    changes = []
+
+    for pair in args.rename_sheet:
+        old, new = pair.split(":", 1)
+        wb[old].title = new
+        changes.append(f"rename {old}->{new}")
+    for pair in args.copy_sheet:
+        src, new = pair.split(":", 1)
+        copy = wb.copy_worksheet(wb[src])
+        copy.title = new
+        changes.append(f"copy {src}->{new}")
+
+    ws = wb[args.sheet] if args.sheet else wb.active
+
+    if args.list_tables:
+        print(json.dumps({"ok": True, "sheet": ws.title,
+                          "tables": {t.displayName: {
+                              "ref": t.ref,
+                              "style": t.tableStyleInfo.name
+                              if t.tableStyleInfo else None}
+                              for t in ws.tables.values()}},
+                         ensure_ascii=False))
+        return 0
+
+    for arg in args.insert_rows:
+        idx, n = parse_idx(arg)
+        ws.insert_rows(idx, n)
+        changes.append(f"insert_rows {idx}x{n}")
+    for arg in args.delete_rows:
+        idx, n = parse_idx(arg)
+        ws.delete_rows(idx, n)
+        changes.append(f"delete_rows {idx}x{n}")
+    for arg in args.insert_cols:
+        idx, n = parse_idx(arg)
+        ws.insert_cols(idx, n)
+        changes.append(f"insert_cols {idx}x{n}")
+    for arg in args.delete_cols:
+        idx, n = parse_idx(arg)
+        ws.delete_cols(idx, n)
+        changes.append(f"delete_cols {idx}x{n}")
+
+    for assignment in args.set:
+        coord, raw = assignment.split("=", 1)
+        ws[coord] = infer(raw)
+        changes.append(f"set {coord}")
+    for row_json in args.append:
+        ws.append(json.loads(row_json))
+        changes.append(f"append row {ws.max_row}")
+
+    for spec in args.add_table:
+        add_table(ws, spec)
+        changes.append(f"add_table {spec.split(':')[0]}")
+    for spec in args.table_append:
+        name, row_json = spec.split("=", 1)
+        table_append(ws, name, json.loads(row_json))
+        changes.append(f"table_append {name} -> {ws.tables[name].ref}")
+
+    for spec in args.define_name:
+        name, ref = spec.split("=", 1)
+        wb.defined_names[name] = DefinedName(name, attr_text=ref)
+        changes.append(f"define_name {name}")
+    for name in args.delete_name:
+        del wb.defined_names[name]
+        changes.append(f"delete_name {name}")
+
+    for spec in args.hyperlink:
+        coord, rest = spec.split("=", 1)
+        url, _, text = rest.partition("|")
+        cell = ws[coord]
+        cell.hyperlink = url
+        cell.value = text or (cell.value if cell.value is not None else url)
+        cell.style = "Hyperlink"
+        changes.append(f"hyperlink {coord}")
+    for spec in args.note:
+        coord, rest = spec.split("=", 1)
+        text, _, author = rest.partition("|")
+        ws[coord].comment = Comment(text, author or "xlsx-skill")
+        changes.append(f"note {coord}")
+    for coord in args.clear_note:
+        ws[coord].comment = None
+        changes.append(f"clear_note {coord}")
+
+    if args.protect is not None:
+        for rng in args.unlock:
+            for row in ws[rng]:
+                for cell in row:
+                    cell.protection = Protection(locked=False)
+        if args.protect:
+            ws.protection.password = args.protect
+        ws.protection.sheet = True
+        changes.append(f"protect {ws.title}"
+                       + (f" (unlocked {len(args.unlock)} ranges)"
+                          if args.unlock else ""))
+
+    if args.recalc:
+        wb.calculation.fullCalcOnLoad = True
+        changes.append("fullCalcOnLoad")
+
+    out = args.out or args.file
+    wb.save(out)
+    print(json.dumps({"ok": True, "output": out, "sheet": ws.title,
+                      "changes": changes}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:
+        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+        sys.exit(1)