@prismer/runtime 2.2.55 → 2.2.64

package/built-in-skills/office-artifacts/references/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
+    if len(row_values) != max_col - min_col + 1:
+        raise ValueError('row length must match table width')
+    if any(ws.cell(new_row, col).value is not None for col in range(min_col, max_col + 1)):
+        raise ValueError('table append would overwrite existing cells')
+    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}")
+    if table.autoFilter:
+        table.autoFilter.ref = table.ref
+
+
+def main(argv=None):
+    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:  # noqa: BLE001
+        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+        sys.exit(1)

package/built-in-skills/office-artifacts/references/xlsx/scripts/xlsx_read.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Read an .xlsx workbook: inventory, JSON/CSV dumps, formula listing.
+
+Modes (pick one):
+  --sheets     JSON inventory: sheet names, dimensions, row/col counts
+  --json       dump one sheet's rows as a JSON array of arrays
+  --csv        dump one sheet as CSV to stdout or --out
+  --formulas   JSON list of formula cells {"cell", "formula", "cached"}
+  --notes      JSON list of cell notes/comments across sheets
+  --names      JSON map of workbook defined names
+
+Options:
+  --sheet NAME     sheet to dump (default: active sheet)
+  --data-only      load cached formula RESULTS instead of formula strings.
+                   Caveat: openpyxl never computes formulas; cached values
+                   exist only if the file was last saved by Excel/LibreOffice.
+  --encoding ENC   encoding for --csv --out files (default utf-8)
+  --out PATH       write --csv output to a file instead of stdout
+
+Usage:
+  xlsx_read.py book.xlsx --sheets
+  xlsx_read.py book.xlsx --json --sheet Data
+  xlsx_read.py book.xlsx --csv --sheet Data --out data.csv
+  xlsx_read.py book.xlsx --formulas
+  xlsx_read.py book.xlsx --notes
+  xlsx_read.py book.xlsx --names
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from datetime import date, datetime, time
+
+from openpyxl import load_workbook
+
+
+def jsonable(value):
+    if isinstance(value, (datetime, date, time)):
+        return value.isoformat()
+    return value
+
+
+def sheet_rows(ws):
+    return [[jsonable(c) for c in row] for row in ws.iter_rows(values_only=True)]
+
+
+def cmd_sheets(wb):
+    info = []
+    for ws in wb.worksheets:
+        info.append({
+            "name": ws.title,
+            "dimensions": ws.dimensions,
+            "max_row": ws.max_row,
+            "max_col": ws.max_column,
+            "merged": [str(r) for r in ws.merged_cells.ranges],
+            "charts": len(getattr(ws, "_charts", [])),
+            "freeze_panes": ws.freeze_panes,
+            "autofilter": ws.auto_filter.ref,
+            "tables": {t.displayName: t.ref for t in ws.tables.values()},
+            "protected": bool(ws.protection.sheet),
+        })
+    names = {name: dn.attr_text for name, dn in wb.defined_names.items()}
+    print(json.dumps({"sheets": info, "defined_names": names},
+                     ensure_ascii=False, indent=2))
+
+
+def cmd_notes(wb, sheet):
+    out = []
+    sheets = [sheet] if sheet else wb.sheetnames
+    for name in sheets:
+        for row in wb[name].iter_rows():
+            for cell in row:
+                if cell.comment is not None:
+                    out.append({"sheet": name, "cell": cell.coordinate,
+                                "text": cell.comment.text,
+                                "author": cell.comment.author})
+    print(json.dumps({"notes": out}, ensure_ascii=False, indent=2))
+
+
+def cmd_names(wb):
+    names = {name: dn.attr_text for name, dn in wb.defined_names.items()}
+    print(json.dumps({"defined_names": names}, ensure_ascii=False, indent=2))
+
+
+def cmd_formulas(path, sheet):
+    wb_f = load_workbook(path, data_only=False)
+    wb_v = load_workbook(path, data_only=True)
+    out = []
+    sheets = [sheet] if sheet else wb_f.sheetnames
+    for name in sheets:
+        ws_f, ws_v = wb_f[name], wb_v[name]
+        for row in ws_f.iter_rows():
+            for cell in row:
+                if isinstance(cell.value, str) and cell.value.startswith("="):
+                    out.append({
+                        "sheet": name,
+                        "cell": cell.coordinate,
+                        "formula": cell.value,
+                        "cached": jsonable(ws_v[cell.coordinate].value),
+                    })
+    print(json.dumps({"formulas": out}, ensure_ascii=False, indent=2))
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Read/inspect an .xlsx workbook.")
+    ap.add_argument("file", help="path to .xlsx file")
+    mode = ap.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--sheets", action="store_true")
+    mode.add_argument("--json", action="store_true")
+    mode.add_argument("--csv", action="store_true")
+    mode.add_argument("--formulas", action="store_true")
+    mode.add_argument("--notes", action="store_true")
+    mode.add_argument("--names", action="store_true")
+    ap.add_argument("--sheet", help="sheet name (default: active)")
+    ap.add_argument("--data-only", action="store_true",
+                    help="return cached formula results (see module docstring)")
+    ap.add_argument("--encoding", default="utf-8")
+    ap.add_argument("--out", help="output file for --csv")
+    args = ap.parse_args(argv)
+
+    if args.formulas:
+        cmd_formulas(args.file, args.sheet)
+        return 0
+
+    wb = load_workbook(args.file, data_only=args.data_only)
+    if args.sheets:
+        cmd_sheets(wb)
+        return 0
+    if args.notes:
+        cmd_notes(wb, args.sheet)
+        return 0
+    if args.names:
+        cmd_names(wb)
+        return 0
+
+    ws = wb[args.sheet] if args.sheet else wb.active
+    rows = sheet_rows(ws)
+    if args.json:
+        print(json.dumps({"sheet": ws.title, "rows": rows}, ensure_ascii=False))
+    else:  # --csv
+        if args.out:
+            with open(args.out, "w", newline="", encoding=args.encoding) as fh:
+                csv.writer(fh).writerows(
+                    [["" if v is None else v for v in r] for r in rows])
+            print(json.dumps({"ok": True, "out": args.out, "rows": len(rows)}))
+        else:
+            w = csv.writer(sys.stdout)
+            for r in rows:
+                w.writerow(["" if v is None else v for v in r])
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # noqa: BLE001
+        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+        sys.exit(1)

package/built-in-skills/office-artifacts/references/xlsx/scripts/xlsx_recalc.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Recalculate a workbook's formulas headlessly with LibreOffice.
+
+openpyxl never computes formulas. This script shells out to `soffice`
+(LibreOffice) to open the workbook, recalculate, and re-save it, so
+cached formula results become available to `xlsx_read.py --data-only`
+and `--formulas`.
+
+Behavior:
+  * soffice on PATH: converts the file to .xlsx in a temp dir (which
+    recalculates all formulas) and replaces the original (or writes
+    --out). Prints {"recalculated": true, ...} and exits 0.
+  * soffice absent: prints {"recalculated": false, "reason": ...} with
+    installation guidance and STILL exits 0 — callers can branch on the
+    JSON instead of the exit code.
+
+Note: LibreOffice recalculates .xlsx on load per its default
+calculation settings; conversion re-saves with fresh cached values.
+
+Usage:
+  xlsx_recalc.py book.xlsx
+  xlsx_recalc.py book.xlsx --out recalced.xlsx
+  xlsx_recalc.py book.xlsx --timeout 120
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def count_cached(path):
+    """Number of formula cells with a cached value present."""
+    from openpyxl import load_workbook
+    wb_f = load_workbook(path, data_only=False)
+    wb_v = load_workbook(path, data_only=True)
+    formulas = cached = 0
+    for name in wb_f.sheetnames:
+        ws_f, ws_v = wb_f[name], wb_v[name]
+        for row in ws_f.iter_rows():
+            for cell in row:
+                if isinstance(cell.value, str) and cell.value.startswith("="):
+                    formulas += 1
+                    if ws_v[cell.coordinate].value is not None:
+                        cached += 1
+    return formulas, cached
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Recalculate .xlsx formulas headlessly via LibreOffice.")
+    ap.add_argument("file", help="path to .xlsx file")
+    ap.add_argument("--out", help="output path (default: replace input)")
+    ap.add_argument("--timeout", type=int, default=180,
+                    help="seconds to wait for soffice (default 180)")
+    args = ap.parse_args(argv)
+
+    src = Path(args.file).resolve()
+    if not src.exists():
+        print(json.dumps({"ok": False, "error": f"no such file: {src}"}),
+              file=sys.stderr)
+        return 1
+
+    soffice = shutil.which("soffice")
+    if not soffice:
+        print(json.dumps({
+            "ok": True, "recalculated": False,
+            "reason": "LibreOffice (soffice) not found on PATH",
+            "guidance": "Install LibreOffice (e.g. `apt install "
+                        "libreoffice-calc` or `brew install --cask "
+                        "libreoffice`), or open the file in Excel/"
+                        "LibreOffice once and re-save it.",
+        }, ensure_ascii=False))
+        return 0
+
+    with tempfile.TemporaryDirectory() as tmp:
+        proc = subprocess.run(
+            [soffice, "--headless", "--calc", "--convert-to", "xlsx:Calc "
+             "MS Excel 2007 XML", "--outdir", tmp, str(src)],
+            capture_output=True, text=True, encoding="utf-8",
+            timeout=args.timeout,
+            env={"HOME": tmp, "PATH": Path(soffice).parent.as_posix()
+                 + ":/usr/bin:/bin"})
+        produced = Path(tmp) / (src.stem + ".xlsx")
+        if proc.returncode != 0 or not produced.exists():
+            print(json.dumps({"ok": False,
+                              "error": "soffice conversion failed",
+                              "stderr": proc.stderr.strip()[-500:]}),
+                  file=sys.stderr)
+            return 1
+        formulas, cached = count_cached(produced)
+        dest = Path(args.out).resolve() if args.out else src
+        shutil.copyfile(produced, dest)
+
+    print(json.dumps({
+        "ok": True, "recalculated": True, "output": str(dest),
+        "formula_cells": formulas, "with_cached_values": cached,
+    }, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # noqa: BLE001
+        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+        sys.exit(1)