@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/office-artifacts/references/xlsx/GUIDE.md

@@ -0,0 +1,196 @@
+---
+name: xlsx
+description: Create, read, edit Excel .xlsx workbooks and CSVs.
+version: 1.1.0
+author: Nous Research
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [excel, spreadsheet, xlsx, csv, openpyxl, productivity]
+    category: productivity
+    related_skills: [docx, pdf, powerpoint]
+---
+
+# Xlsx Skill
+
+Work with Excel .xlsx workbooks using Python and openpyxl: build styled
+multi-sheet workbooks with formulas and charts, inspect or dump existing
+files, edit cells and structure, and convert to/from CSV. All helper
+scripts are argparse CLIs that print JSON and use explicit UTF-8 I/O.
+
+## When to Use
+
+- Creating .xlsx reports: multiple sheets, number formats, styling,
+  merged cells, freeze panes, autofilter, conditional formatting,
+  charts, data-validation dropdowns, native Excel tables, defined
+  names, hyperlinks, cell notes, sheet protection.
+- Reading a workbook: sheet inventory, dumping data as JSON or CSV,
+  listing formulas vs cached values, notes, defined names, tables.
+- Editing existing files: set cells, append rows, insert/delete
+  rows/columns (reference-aware via `xlsx_restructure.py`),
+  copy/rename sheets, tables, names, notes, protection.
+- Recalculating formulas headlessly via LibreOffice
+  (`xlsx_recalc.py`).
+- CSV interop with type inference and non-UTF-8 encodings.
+- Not for the legacy .xls binary format (use LibreOffice to convert
+  first: `soffice --headless --convert-to xlsx old.xls`).
+
+## Prerequisites
+
+- Python 3.10+ with `openpyxl` (`pip install openpyxl`). No other
+  third-party packages are needed; everything else is stdlib.
+- Optional: LibreOffice (`soffice`) for headless recalculation or
+  format conversion.
+
+## How to Run
+
+Run the helper scripts with the `terminal` tool from this skill's
+`scripts/` directory (every script supports `--help`):
+
+```bash
+python scripts/xlsx_create.py spec.json report.xlsx   # build from JSON spec
+python scripts/xlsx_read.py report.xlsx --sheets      # inventory
+python scripts/xlsx_read.py report.xlsx --json --sheet Data
+python scripts/xlsx_read.py report.xlsx --formulas
+python scripts/xlsx_edit.py report.xlsx --sheet Data --set B2=42 --recalc
+python scripts/xlsx_restructure.py report.xlsx --sheet Data --insert-rows 3:2
+python scripts/xlsx_recalc.py report.xlsx
+python scripts/csv_to_xlsx.py data.csv out.xlsx --encoding utf-8
+python scripts/xlsx_to_csv.py report.xlsx out.csv --sheet Data
+```
+
+Author the JSON spec with `write_file`, inspect script JSON output with
+`read_file` or directly from stdout.
+
+## Quick Reference
+
+| Task | Command |
+|---|---|
+| Create workbook from spec | `xlsx_create.py spec.json out.xlsx` |
+| Sheet names + dimensions | `xlsx_read.py f.xlsx --sheets` |
+| Dump sheet as JSON | `xlsx_read.py f.xlsx --json --sheet S` |
+| Dump sheet as CSV | `xlsx_read.py f.xlsx --csv --out d.csv` |
+| List formulas + cached values | `xlsx_read.py f.xlsx --formulas` |
+| Set a cell / formula | `xlsx_edit.py f.xlsx --set "A1==SUM(B:B)"` |
+| Append a row | `xlsx_edit.py f.xlsx --append '[1,"x",true]'` |
+| Insert 2 rows, refs NOT shifted | `xlsx_edit.py f.xlsx --insert-rows 3:2` |
+| Insert 2 rows, refs shifted | `xlsx_restructure.py f.xlsx --insert-rows 3:2` |
+| Delete a column, refs shifted | `xlsx_restructure.py f.xlsx --delete-cols B` |
+| Create a native table | `xlsx_edit.py f.xlsx --add-table Sales:A1:C9` |
+| Append inside a table | `--table-append 'Sales=["West",5]'` |
+| List tables | `xlsx_edit.py f.xlsx --list-tables` |
+| Defined names | `--define-name "Rates='Data'!$B$2:$B$9"` / `--delete-name Rates` / `xlsx_read.py f.xlsx --names` |
+| Hyperlink | `--hyperlink "A1=https://example.com|Docs"` |
+| Cell note | `--note "B2=Check this|Reviewer"`; read via `xlsx_read.py f.xlsx --notes` |
+| Protect sheet (see Pitfalls) | `--protect your-password --unlock B2:B9` |
+| Recalculate via LibreOffice | `xlsx_recalc.py f.xlsx` |
+| Copy / rename sheet | `--copy-sheet Src:New --rename-sheet Old:New` |
+| Force recalc on open | `xlsx_edit.py f.xlsx --recalc` |
+| CSV -> styled xlsx | `csv_to_xlsx.py in.csv out.xlsx` |
+| xlsx -> CSV | `xlsx_to_csv.py f.xlsx out.csv --encoding utf-8` |
+
+## Procedure
+
+1. **Create**: write a JSON spec (schema documented in
+   `xlsx_create.py --help` and its docstring). Each sheet supports
+   `rows` (scalars or styled cell objects), sparse `cells` overrides,
+   `column_widths`, `row_heights`, `merges`, `freeze_panes`,
+   `autofilter`, `conditional_formats` (cell_is rules and color
+   scales), `charts` (bar/line/pie from cell ranges),
+   `validations` (list dropdowns), `tables` (native Excel tables with
+   a style name), and `protection`. Workbook-level `defined_names`
+   maps names to refs. Cell objects also take `hyperlink` and `note`.
+   Typed values: JSON numbers/bools
+   pass through; dates use `{"value": "2026-01-31", "type": "date"}`.
+   Number formats are Excel format strings: currency `"$#,##0.00"`,
+   percent `"0.0%"`, date `"yyyy-mm-dd"`.
+2. **Formulas**: set with `"formula": "SUM(B2:B9)"` in the spec or
+   `--set "C1==SUM(A:A)"` in the editor. When writing formulas, add
+   `"full_calc_on_load": true` (spec) or `--recalc` (editor); this sets
+   the workbook's `fullCalcOnLoad` flag so Excel/LibreOffice recompute
+   everything on open. openpyxl itself NEVER evaluates formulas.
+3. **Read**: `--sheets` for inventory (names, dimensions, merged
+   ranges, chart count, tables, protection, defined names),
+   `--json`/`--csv` for data, `--formulas` to
+   pair each formula string with its cached result, `--notes` for
+   cell comments, `--names` for defined names. Cached results
+   exist only if the file was last saved by a real spreadsheet app;
+   files fresh from openpyxl return `null` there. To materialize
+   results headlessly run `xlsx_recalc.py file.xlsx` (uses
+   LibreOffice; prints `{"recalculated": false, ...}` and exits 0
+   when `soffice` is absent), then reload with `--data-only`.
+4. **Edit**: `xlsx_edit.py` applies renames/copies first, then
+   structural row/column changes, then `--set`/`--append`. It edits in
+   place unless `--out` is given — copy the file first if you need the
+   original.
+5. **Restructure**: for insert/delete on sheets that have formulas,
+   merges, tables, or filters, use `xlsx_restructure.py` instead of
+   `xlsx_edit.py`. It rewrites formula references on ALL sheets
+   (absolute `$` refs, ranges, cross-sheet refs), shifts merges,
+   autofilter, freeze panes, validation and conditional-format
+   ranges, table refs, defined names, and row/column dimensions, then
+   prints a JSON report including a `not_shifted` list. Rules and
+   limits: `references/restructuring.md`.
+6. **CSV interop**: `csv_to_xlsx.py` infers int/float/bool/ISO-date
+   per cell and styles the header row; `xlsx_to_csv.py` writes ISO
+   dates and blank strings for empty cells. Both default to UTF-8 and
+   accept `--encoding` (e.g. `utf-8-sig` for Excel-friendly BOM,
+   `cp1252` for legacy Windows exports).
+
+## Converting to PDF
+
+LibreOffice converts headlessly (also works for CSV export of a single
+sheet):
+
+```bash
+soffice --headless --convert-to pdf report.xlsx --outdir out/
+soffice --headless --convert-to csv report.xlsx --outdir out/  # 1st sheet only
+```
+
+Only the first sheet lands in a CSV; for other sheets use
+`xlsx_to_csv.py --sheet NAME`. If `soffice` is missing, install
+LibreOffice or hand the file to the user unconverted.
+
+## Pitfalls
+
+- **openpyxl does not calculate.** Formula results are available only
+  via `load_workbook(path, data_only=True)` and only when the file was
+  previously saved by Excel/LibreOffice. Otherwise you get `None`.
+- **`xlsx_edit.py` insert/delete does not shift references** (raw
+  openpyxl behavior). Use `xlsx_restructure.py`, which does — but even
+  it cannot move chart anchors, images, or conditional-format RULE
+  formulas; read its JSON report's `not_shifted` list and
+  `references/restructuring.md`.
+- **Sheet protection is NOT security.** `--protect` sets the standard
+  xlsx sheet-protection hash: it signals "don't edit this" to
+  well-behaved apps and nothing more. Anyone can strip it by editing
+  the zip's XML or unchecking it in LibreOffice. Never rely on it for
+  confidentiality or integrity; it does not encrypt anything.
+- **`data_only=True` then save** silently discards all formulas
+  (cached values replace them). Never save a workbook loaded that way
+  unless that is the goal.
+- **Loading strips charts/images**: openpyxl does not round-trip
+  charts, so editing a charted workbook and saving drops the charts.
+  Re-add charts after editing, or avoid re-saving charted files.
+- **CSV locale traps**: always pass explicit encodings (the scripts
+  already do) and remember European CSVs often use `;` delimiters and
+  decimal commas — use `--delimiter ';'` and expect strings like
+  `"12,5"` to stay strings.
+- **Dates are datetimes**: Excel stores dates as serial numbers;
+  openpyxl returns `datetime`/`date` objects. Dumps here emit ISO
+  strings.
+- Sheet names are capped at 31 chars and reject `[ ] : * ? / \`.
+
+## Verification
+
+- After creating: `xlsx_read.py out.xlsx --sheets` and confirm sheet
+  names, dimensions, merged ranges, and chart counts match intent.
+- Dump data with `--json` and compare against the source values.
+- After edits: re-dump the touched range; if formulas were written,
+  confirm `--formulas` lists them and that `--recalc` was applied.
+- After `xlsx_restructure.py`: read its JSON report, then re-run
+  `--formulas` and `--sheets` to confirm references and ranges landed
+  where expected.
+- For a full visual check, open in LibreOffice:
+  `soffice --headless --convert-to pdf out.xlsx` and inspect the PDF.

package/built-in-skills/office-artifacts/references/xlsx/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+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.

package/built-in-skills/office-artifacts/references/xlsx/NOTICE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+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.

package/built-in-skills/office-artifacts/references/xlsx/references/restructuring.md

@@ -0,0 +1,74 @@
+# Reference-aware restructuring (xlsx_restructure.py)
+
+`scripts/xlsx_restructure.py` performs one row/column insert or delete
+and rewrites supported references to the moved cells. This document
+gives the exact rewrite rules and honest limits.
+
+## What gets rewritten
+
+| Artifact | Scope | Behavior |
+|---|---|---|
+| Formula references | ALL sheets | A1 refs into the edited sheet are shifted; refs into a fully deleted region become `#REF!` |
+| Merged-cell ranges | edited sheet | shifted; expanded when they span the insertion point; dropped (reported `to: null`) when fully deleted |
+| Autofilter ref | edited sheet | shifted/expanded like a range |
+| Freeze panes | edited sheet | anchor cell shifted (never below row/col of the pane's own minimum) |
+| Data validations | edited sheet | each range in the sqref shifted; deleted ranges removed |
+| Conditional formats | edited sheet | applied range (sqref) shifted |
+| Native tables | edited sheet | ref/filter synchronized; column insertion adds matching tableColumns/header names; partial column deletion and header-only deletion refused before save |
+| Defined names | workbook and sheet scope | supported `attr_text` refs into the edited sheet rewritten |
+| Row heights / column widths | edited sheet | dimension keys re-indexed |
+
+## Reference grammar handled
+
+- Relative and absolute coordinates in any mix: `B2`, `$B2`, `B$2`,
+  `$B$2` — the `$` flags are preserved through the shift.
+- Ranges `B2:D9`, including partial-absolute endpoints.
+- Cross-sheet refs: `Data!B2`, `'My Sheet'!$A$1:$C$9` (quoted names may
+  contain doubled quotes `''`). Only refs whose sheet qualifier matches
+  the edited sheet are touched; unqualified refs are interpreted
+  relative to the formula's own sheet.
+- String literals inside formulas (`"See B2"`) are never rewritten.
+- Function names that look like cells (`LOG10(...)`) are not touched
+  (a reference is never followed by `(`).
+- Whole-row/column refs (`B:B`, `2:2`) shift with the edited axis, preserving
+  absolute flags. External-workbook and structured references are not rewritten.
+  Three-dimensional sheet spans fail before save instead of being guessed.
+
+## Shift semantics
+
+Insert of N at index i: every coordinate >= i moves +N; range endpoints
+move independently, so a range spanning i grows by N.
+
+Delete of N at index i: coordinates before i are unchanged; coordinates
+past the deleted block move -N; a single cell inside the block becomes
+`#REF!`; a RANGE partially covering the block is clamped (Excel does the
+same); a range entirely inside the block becomes `#REF!` (formulas) or
+is removed (merges/validations).
+
+## What it CANNOT shift (honest limits)
+
+- **Chart anchors and plotted ranges** — openpyxl chart objects are not
+  reliably round-tripped; anchors stay where they were. Re-create
+  charts after restructuring if their data moved.
+- **Images / drawings** — same reason.
+- **Conditional-format RULE formulas** — the applied range (sqref) is
+  shifted, but formulas inside `cell_is`/`expression` rules (e.g.
+  `$B1>100`) are left as-is. Review them if they reference moved cells.
+- **Validation formulas and table calculated-column formulas** require manual
+  review or explicit reconstruction; their ranges alone are updated.
+- **Sheet-local defined names** and names using R1C1 or union/
+  intersection operators are rewritten only if they parse as plain A1
+  refs; anything else passes through untouched.
+- **Structured table references** in formulas (`Table1[Sales]`) don't
+  need shifting (they follow the table), and are left alone.
+
+Every run prints a JSON report listing exactly which formulas, merges,
+tables, names, and ranges were changed, plus a fixed `not_shifted` list
+of the above limits — inspect it after any structural edit.
+
+## One op per invocation
+
+The CLI takes exactly one of `--insert-rows/--delete-rows/
+--insert-cols/--delete-cols` (as `IDX[:N]`; columns accept letters).
+For multiple operations run it repeatedly — ordering compound shifts in
+one pass is where spreadsheet tools historically corrupt references.

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Convert a CSV file to a styled .xlsx workbook with type inference.
+
+Type inference per cell (disable with --no-infer):
+  int, float, bool ("true"/"false", case-insensitive), ISO date
+  (YYYY-MM-DD) and ISO datetime; everything else stays a string.
+
+Styling applied by default (disable with --plain):
+  bold header row with a light fill, frozen top row, autofilter over the
+  data range, and column widths sized to the longest cell (capped at 60).
+
+Usage:
+  csv_to_xlsx.py data.csv out.xlsx
+  csv_to_xlsx.py data.csv out.xlsx --sheet-name Import --encoding cp1252
+  csv_to_xlsx.py data.csv out.xlsx --delimiter ';' --no-infer
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from datetime import date, datetime
+
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill
+from openpyxl.utils import get_column_letter
+
+MAX_COL_WIDTH = 60
+COL_PADDING = 2
+DEFAULT_COL_WIDTH = 8
+
+
+def infer(text):
+    if text == "":
+        return None
+    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 main(argv=None):
+    ap = argparse.ArgumentParser(description="CSV -> styled .xlsx converter.")
+    ap.add_argument("csv_file", help="input CSV path")
+    ap.add_argument("output", help="output .xlsx path")
+    ap.add_argument("--sheet-name", default="Sheet1")
+    ap.add_argument("--encoding", default="utf-8",
+                    help="CSV file encoding (default utf-8)")
+    ap.add_argument("--delimiter", default=",")
+    ap.add_argument("--no-infer", action="store_true",
+                    help="keep every cell as a string")
+    ap.add_argument("--plain", action="store_true",
+                    help="skip header styling / freeze / autofilter")
+    args = ap.parse_args(argv)
+
+    with open(args.csv_file, newline="", encoding=args.encoding) as fh:
+        rows = list(csv.reader(fh, delimiter=args.delimiter))
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = args.sheet_name
+    for i, row in enumerate(rows):
+        if args.no_infer or i == 0:
+            ws.append(row)
+        else:
+            ws.append([infer(cell) for cell in row])
+        # CSV is data, never executable formula input, including header cells.
+        for cell in ws[i + 1]:
+            if cell.data_type == 'f':
+                cell.data_type = 's'
+
+    if rows and not args.plain:
+        header_font = Font(bold=True)
+        header_fill = PatternFill("solid", fgColor="DDEBF7")
+        for cell in ws[1]:
+            cell.font = header_font
+            cell.fill = header_fill
+        ws.freeze_panes = "A2"
+        ws.auto_filter.ref = ws.dimensions
+        for col_idx in range(1, ws.max_column + 1):
+            longest = max((len(str(r[col_idx - 1])) for r in rows
+                           if len(r) >= col_idx), default=DEFAULT_COL_WIDTH)
+            ws.column_dimensions[get_column_letter(col_idx)].width = \
+                min(longest + COL_PADDING, MAX_COL_WIDTH)
+
+    wb.save(args.output)
+    print(json.dumps({"ok": True, "output": args.output,
+                      "rows": len(rows)}, 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_create.py

@@ -0,0 +1,259 @@
+#!/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):
+    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:  # noqa: BLE001
+        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+        sys.exit(1)