v0.7.1

v0.7.1 Release Notes

This patch release publishes the CLI and package import startup optimization work
completed under issues #107, #108, and #109.

Highlights

• The extraction CLI now always shows --auto-page-breaks-dir in help output
  and validates support only when the option is actually used at runtime.
• Lightweight CLI paths now avoid unnecessary heavy imports:
  • exstruct --help
  • extraction-style argv that do not route to edit commands
  • exstruct ops list
• Public package imports are lighter:
  • import exstruct
  • import exstruct.engine
  • exported names from exstruct and exstruct.edit remain compatible while
    loading implementation modules lazily
• Regression coverage now locks the startup boundary and validates that
  lightweight import paths do not eagerly load extraction, edit, MCP, render,
  or pydantic dependencies.

Startup impact

Compared with v0.7.0, local median startup timings on the same Python
environment improved by approximately:

• python -m exstruct.cli.main --help: 2195 ms -> 64 ms (34.4x faster)
• import exstruct: 1039 ms -> 55 ms (19.0x faster)
• python -m exstruct.cli.main ops list: 1143 ms -> 207 ms (5.5x faster)
• import exstruct.engine: 1005 ms -> 223 ms (4.5x faster)

These measurements were taken locally against v0.7.0 and the current
v0.7.1 code using the same virtual environment and direct source imports, so
exact numbers will vary by machine and startup conditions.

Notes

• No new CLI commands were added in v0.7.1.
• MCP tool names and payload shapes remain compatible in v0.7.1.
• Backend selection policy remains auto / com / openpyxl.
• The edit CLI validate subcommand once again propagates RuntimeError
  instead of converting it into handled CLI error output.

v0.7.0

v0.7.0 Release Notes

This release publishes the workbook editing work completed under issue #99,
including the new exstruct.edit API surface, the editing CLI, compatibility
follow-ups, and maintainer-facing documentation needed to keep the layering
clear for future changes.

Next steps

Currently, the CLI startup is slow due to issues with the initial implementation,
so we plan to release an update in the near future to improve its performance.

Highlights

• Added a first-class workbook editing API under exstruct.edit, including:
  • public patch_workbook() / make_workbook() entrypoints
  • public request/result models
  • shared patch-op schema discovery helpers
• Added public editing CLI commands under exstruct:
  • patch
  • make
  • ops
  • validate
• Clarified the editing architecture split so exstruct.edit is the canonical
  core and MCP remains the host-managed integration / compatibility layer.
• Updated public docs to explain canonical usage across Python, CLI, and MCP,
  including the recommended dry_run -> inspect -> apply workflow and the
  backend="auto" caveat for same-engine comparisons.
• Added maintainer-facing documentation coverage for editing architecture,
  specs, ADR alignment, and agent workflow expectations used during the issue
  #99 closeout.
• Fixed release-significant review follow-ups, including:
  • top-level sheet fallback while preserving op.sheet precedence
  • legacy monkeypatch compatibility across compatibility shims
  • rename-reservation cleanup on openpyxl failure paths
  • dry-run / backend / CLI failure wording drift in docs

Notes

• The legacy extraction CLI invocation (exstruct INPUT.xlsx ...) is unchanged.
• MCP tool names and payload shapes remain compatible in v0.7.0.
• Patch backend policy remains auto / com / openpyxl; this release does
  not change backend selection semantics.

v0.6.1

v0.6.1 Release Notes

This patch release hardens Windows LibreOffice smoke coverage and runtime
resolution for the libreoffice extraction path.

Highlights

• Added a dedicated Windows GitHub Actions LibreOffice smoke job:
  • runs on windows-2025
  • installs libreoffice-fresh
  • discovers EXSTRUCT_LIBREOFFICE_PATH and bundled LibreOffice Python
  • runs tests/core/test_libreoffice_smoke.py -m libreoffice with
    RUN_LIBREOFFICE_SMOKE=1
• Improved Windows runtime discovery:
  • soffice.com is now preferred over soffice.exe when available
  • bundled LibreOffice Python detection now covers python-core-* layouts
• Hardened LibreOffice bridge subprocess startup on Windows:
  • bridge probe, handshake, and extraction now run from the runtime Python
    directory
  • the runtime directory is prepended to PATH for UNO import and DLL
    resolution
• Reduced smoke-gate false negatives:
  • slow soffice --version probes are retried with a longer timeout
  • if version probing still times out, the smoke gate falls back to a
    short-lived LibreOffice session probe before marking the runtime
    unavailable
• Added regression tests for Windows runtime normalization, bundled Python
  discovery, bridge subprocess environment handling, and timeout fallback.

Notes

• This is a reliability-focused patch release for Windows LibreOffice CI and
  runtime detection.
• No public API or output schema changes were introduced in this release.

v0.6.0

v0.6.0 Release Notes

This release adds a new best-effort libreoffice extraction mode for
non-COM environments and extends shape/chart metadata with provenance fields.

Highlights

• Added mode="libreoffice" across the Python API, CLI, and MCP server.
• Added early validation for .xls + mode="libreoffice" with a clear error.
• Added extraction-only validation for mode="libreoffice":
  • rejects PDF/PNG rendering
  • rejects auto page-break export
• Added FallbackReason.LIBREOFFICE_UNAVAILABLE and
  FallbackReason.LIBREOFFICE_PIPELINE_FAILED.
• Added backend metadata to shapes/charts:
  • provenance
  • approximation_level
  • confidence
  • serialized output now keeps these fields opt-in via include_backend_metadata
• Added OOXML-based best-effort reconstruction for:
  • shapes
  • connectors
  • charts
• Added a LibreOffice runtime helper so server/Linux/macOS environments can
  opt into rich extraction without Excel COM.
• Added bundled bridge compatibility probing for LibreOffice Python runtime
  selection, including fail-fast handling for incompatible
  EXSTRUCT_LIBREOFFICE_PYTHON_PATH overrides.
• Added a required Linux GitHub Actions smoke job that installs LibreOffice
  • python3-uno and runs the pytest.mark.libreoffice sample smoke test.

Notes

• libreoffice is available for .xlsx/.xlsm only.
• libreoffice is best-effort and not a strict subset of COM output.
• v1 does not add LibreOffice PDF/PNG rendering or auto page-break extraction.

v0.5.3

v0.5.3 Release Notes

This patch release improves capture_sheet_images subprocess reliability and
observability, and updates MCP guidance for safe production rollout.

Highlights

• Added dedicated subprocess worker entrypoint:
  • python -m exstruct.render.subprocess_worker is now used for
    capture_sheet_images subprocess mode.
  • worker bootstrap is decoupled from parent __main__ restoration.
• Updated default runtime behavior:
  • MCP now defaults EXSTRUCT_RENDER_SUBPROCESS=1 based on profile-comparison
    runs showing stable behavior in both modes.
  • EXSTRUCT_RENDER_SUBPROCESS=0 remains available to force in-process mode.
• Improved timeout and failure diagnostics:
  • wait ordering now prioritizes result receipt before join wait to reduce
    false timeout failures after successful worker output.
  • stage-aware error reporting (startup / join / result / worker) now
    includes actionable context and stderr snippets when available.
• Documentation updates:
  • MCP exstruct_capture_sheet_images is marked Experimental.
  • README/MCP docs now include subprocess timeout tuning guidance, including
    EXSTRUCT_RENDER_SUBPROCESS_STARTUP_TIMEOUT_SEC.

Notes

• No new patch operations were added in this release.
• MCP tools include the experimental exstruct_capture_sheet_images path updated in this release.
• This is a reliability-focused patch release for image-capture execution paths.

v0.5.2

v0.5.2 Release Notes

This patch release restores mixed chart/table patch workflows on COM-backed
execution and clarifies error behavior for non-COM environments.

Highlights

• Restored mixed-op support:
  • create_chart and apply_table_style can be executed in one request when
    the backend resolves to COM (backend="com" or COM-available
    backend="auto").
• Improved error behavior:
  • when COM is unavailable, mixed create_chart + apply_table_style
    requests now return a clear COM-required error.
• Added and updated regression coverage:
  • mixed request succeeds on COM
  • mixed request fails clearly when COM is unavailable
  • backend="openpyxl" continues to reject create_chart requests

Notes

• This release does not add new MCP tools or patch operations.
• Documentation (README and MCP guide) has been aligned with the restored
  mixed-op behavior.

v0.5.1

v0.5.1 Release Notes

This patch release tightens MCP patch operation constraints and updates
documentation for backend behavior clarity.

Highlights

• Added a service-level guard for backend-only op mixing:
  • create_chart and apply_table_style can no longer be combined in a
    single request.
• Updated MCP docs and README pages for create_chart constraints:
  • COM-only behavior
  • supported chart types: line, column, bar, area, pie,
    doughnut, scatter, radar
  • chart type aliases: column_clustered -> column, bar_clustered ->
    bar, xy_scatter -> scatter, donut -> doughnut
  • related flag limitations
  • incompatibility with apply_table_style in one request

Notes

• This is a compatibility and correctness-focused patch release with no new
  public tool surface added.

v0.5.0

v0.5.0 Release Notes

This release expands MCP editing from MVP scope to practical workbook design
flows, and adds new MCP tools for workbook creation, op discovery, and runtime
diagnostics.

Highlights

• Added exstruct_make for one-call workbook creation and initial ops apply.
  • out_path is required, ops is optional.
  • Supports .xlsx, .xlsm, and .xls (with COM constraints on .xls).
• Expanded exstruct_patch design editing operations:
  • draw_grid_border, set_bold, set_font_size, set_font_color,
    set_fill_color, set_dimensions, auto_fit_columns, merge_cells,
    unmerge_cells, set_alignment, set_style, apply_table_style
  • Internal inverse op: restore_design_snapshot
• Added MCP operation schema discovery tools:
  • exstruct_list_ops
  • exstruct_describe_op
• Added MCP runtime diagnostics tool:
  • exstruct_get_runtime_info
• Improved patch UX and output controls:
  • Top-level sheet fallback for non-add_sheet ops (op.sheet has higher
    priority when both are present)
  • Artifact mirroring via mirror_artifact and server --artifact-bridge-dir
  • Backend controls for patch/make: backend input and engine output

Notes

• backend="auto" now prefers COM when available, with controlled fallback to
  openpyxl for compatible cases.
• apply_table_style requested with backend="com" falls back to openpyxl
  with a warning.
• MCP docs and README pages were updated to reflect the new make/patch flows
  and operation schema guidance.

v0.4.4

v0.4.4 Release Notes

This release delivers an MVP for Excel editing on the MCP server, plus new
direct-read tools to make agent workflows faster and more precise.

Highlights

• Added Excel edit MVP via exstruct_patch with atomic apply semantics:
  • Core operations: set_value, set_formula, add_sheet
  • Extended operations: set_range_values, fill_formula,
    set_value_if, set_formula_if
  • Safety and review options: dry_run, return_inverse_ops,
    preflight_formula_check, auto_formula
  • Better output handling: output directory creation, structured errors, and
    default conflict policy set to overwrite
  • Compatibility improvement: ops now accepts both object lists
    (recommended) and JSON object strings
• Added direct A1-oriented read tools for extracted JSON:
  • exstruct_read_range
  • exstruct_read_cells
  • exstruct_read_formulas
• Improved MCP extraction/read consistency:
  • Added alpha_col support (Excel-style column keys like A, B, ...)
    across CLI/MCP extraction paths
  • Added merged_ranges output for alpha_col mode
  • Clarified MCP mode/chunk guidance and improved chunk-reader error messages
• Expanded MCP documentation, tool schemas, and tests for patch/read flows.

Notes

• In MCP, options.alpha_col now defaults to true. Set
  options.alpha_col=false if you need legacy numeric string column keys.
• exstruct_patch follows server-level --on-conflict unless overridden in
  the tool call.

v0.4.0

v0.4.0 Release Notes

This release introduces MCP server support for ExStruct, enabling agent tool
integration with a stdio server, plus new extraction utilities, policies, and
expanded tests and documentation.

Please read the official documentation for detailed setup instructions.
MCP Server

Highlights

• Added MCP stdio server (exstruct-mcp) with tools:
  • exstruct_extract
  • exstruct_read_json_chunk (cursor + filters for large outputs)
  • exstruct_validate_input (pre-checks for files and COM availability)
• Introduced MCP path policy (allowlist + deny globs), output conflict handling
  (--on-conflict), and optional warmup for latency reduction.
• Added typed extraction options for MCP runs (pretty/indent and side outputs),
  and clarified file validation errors.
• Improved openpyxl border scanning (deferred column shrink) for late-table
  detection; added backend selection for border clustering.
• Documentation updates for MCP setup and agent configuration (site nav and
  README updates), plus expanded tests and CI dependency installation.

Notes

• MCP dependencies are optional: install with pip install exstruct[mcp].
• read_json_chunk enforces file paths and chunk size limits; use sheet/
  filter when outputs are large.