plsqlwks 0.1.4__tar.gz → 0.1.6__tar.gz

plsqlwks-0.1.6/MANIFEST.in

@@ -0,0 +1,8 @@
+include pytest.ini
+include PLUGINS.md
+include rchar.py
+include requirements.txt
+recursive-include plugin-requirements requirements.txt
+include tests/conftest.py
+include tests/fixtures/config_exports.txt
+include tests/fixtures/ui_exports.txt

{plsqlwks-0.1.4 → plsqlwks-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plsqlwks
-Version: 0.1.4
+Version: 0.1.6
 Summary: An ncurses SQL and PL/SQL workspace for Oracle databases.
 License-Expression: LicenseRef-plsqlwks-Donationware
 Project-URL: Repository, https://gitlab.com/unununu/plsqlwks
@@ -13,6 +13,8 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: license.txt
 Requires-Dist: oracledb>=2.0
+Provides-Extra: xlsx
+Requires-Dist: openpyxl>=3.1; extra == "xlsx"
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
@@ -74,9 +76,6 @@ python3 -m pip install -e '.[dev]'
 
 `oracledb` is the only runtime dependency. Supporting functionality uses the Python standard library.
 
-See the [release checklist](https://gitlab.com/unununu/plsqlwks/-/blob/main/RELEASING.md)
-for the quality, packaging, and GitLab release process.
-
 For a regular local install, use:
 
 ```bash
@@ -90,11 +89,32 @@ python3 -m pytest -q
 python3 -m ruff check .
 ```
 
+Plugin API and built-in plugin tests are optional and are not part of the
+default core test run. Run them with either opt-in form:
+
+```bash
+PLSQLWKS_TEST_PLUGINS=1 python3 -m pytest -q
+python3 -m pytest -q -m plugin
+```
+
+The CSV and HTML export plugins have no additional dependencies. XLSX export
+uses the optional `openpyxl` package, kept out of the base PLSQLWKS runtime.
+Install a distribution with XLSX support through the standard extra:
+
+```bash
+python3 -m pip install 'plsqlwks[xlsx]'
+```
+
+For an editable development checkout, install the development and XLSX extras
+together with `python3 -m pip install -e '.[dev,xlsx]'`. The repository also
+retains `plugin-requirements/xlsx-export/requirements.txt` as a compatible
+fallback for existing checkout automation.
+
 Oracle integration tests require the connection environment variables shown
 above and an accessible password file. Enable every test group with:
 
 ```bash
-PLSQLWKS_TEST_ORACLE=1 PLSQLWKS_TEST_PTY=1 PLSQLWKS_TEST_SLOW=1 \
+PLSQLWKS_TEST_ORACLE=1 PLSQLWKS_TEST_PLUGINS=1 PLSQLWKS_TEST_PTY=1 PLSQLWKS_TEST_SLOW=1 \
   python3 -m pytest -q -rs
 ```
 
@@ -172,9 +192,9 @@ After a successful quit, plsqlwks records the open file-backed tabs, active tab,
 | `F8` | Toggle result grid / row-detail output |
 | `F9` | Show/focus/hide schema browser |
 | `F12` | Choose autocommit or manual transaction mode |
-| `Ctrl-Up` / `Ctrl-Down` | Scroll the focused pane or visible DBMS_OUTPUT |
+| `Ctrl-Up` / `Ctrl-Down` | Scroll the focused pane or visible DBMS_OUTPUT by one line |
 | `Ctrl-W` | Close current file tab |
-| `Ctrl-PageUp` / `Ctrl-PageDown` | Switch file tabs |
+| `Ctrl-PageUp` / `Ctrl-PageDown` | Scroll focused results by one page; otherwise switch file tabs |
 | `Alt-1`..`Alt-9` | Jump to visible file tab |
 | `Ctrl-Q` | Quit |
 | `Ctrl-C` while running | Interrupt the active database operation |
@@ -200,7 +220,7 @@ After a successful quit, plsqlwks records the open file-backed tabs, active tab,
 | `Delete` | Delete at the cursor |
 | `Ctrl-Backspace` / `Ctrl-Delete` | Delete the previous/next word |
 | `Enter` | Insert a new line |
-| `Tab` | Focus the result table |
+| `Tab` | Focus the results or DBMS_OUTPUT pane |
 | `Shift-Tab` | Autocomplete keywords, schema objects, and columns |
 | `F2` / `Ctrl-S` | Save buffer |
 | `F3` / `Ctrl-O` | Open file |
@@ -302,6 +322,152 @@ bytes and include a truncation marker with the full size. Truncated LOB cells
 cannot be edited safely. Schema-browser DDL is always read in full.
 `F7` cycles a grid fullscreen view that starts with the table header on the first terminal line and uses the last line for data, an editor-only fullscreen view, and a split layout with 2/3 editor and 1/3 data grid.
 
+To export the active table, use one of these command paths:
+
+- `Alt-O -> Results -> Export loaded rows to CSV`
+- `Alt-O -> Results -> Export loaded rows to HTML`
+- `Alt-O -> Results -> Export loaded rows to XLSX`
+
+All three built-in Plugin API commands write the columns and exactly the rows
+currently loaded in the grid; they never fetch additional result pages.
+Relative names and the timestamped default name are resolved under the active
+workspace's `results/` directory; absolute paths are also accepted, and an
+existing file requires confirmation before replacement. Commit or cancel an
+active insert draft before exporting so its temporary row cannot be included.
+Each enabled export remains available in read-only mode because it does not
+execute SQL or change a transaction.
+
+The bundled exporters can be enabled independently in the active `config.ini`:
+
+```ini
+[plugin.csv-export]
+enabled = yes
+
+[plugin.html-export]
+enabled = yes
+
+[plugin.xlsx-export]
+enabled = yes
+```
+
+Set an exporter's `enabled` value to `no` to omit its command from the
+**Results** menu. A missing or malformed value defaults to enabled so existing
+configurations keep all three commands. These switches affect only the bundled
+exporters, not installed entry-point plugins, and take effect after restarting
+PLSQLWKS.
+
+The HTML command writes a standalone UTF-8 HTML5 document with column headings
+and table rows, followed by the loaded-row count and any additional-row notice.
+The result title is used only as browser-tab document metadata, not as a visible
+heading. Document titles, column headers, and cell values are escaped as
+untrusted text. The document contains a static embedded stylesheet, no
+JavaScript, and no external resources. It reports when more rows are available
+in PLSQLWKS but does not fetch them, and it does not open a browser after export.
+
+The XLSX command writes one `Query result` worksheet with a header row and the
+currently loaded display rows. The header row is frozen by default so it stays
+visible while scrolling. Genuine source numbers become native Excel
+numeric cells when they fit Excel's range and 15-significant-digit precision;
+fixed-point scale such as `10.50` is preserved. Numeric-looking character data
+and unsafe-precision numbers remain exact text and can still receive Excel's
+number-as-text warning. Headers and other values, including text beginning with
+`=`, `+`, `-`, or `@`, remain literal strings and are never interpreted as
+spreadsheet formulas. The workbook contains no macros, external links, or
+fetched continuation rows and is not opened after export. XLSX support is
+optional and obtains `openpyxl>=3.1` from the standard `plsqlwks[xlsx]` extra;
+the repository plugin requirements file remains a source-checkout fallback.
+Each column uses the larger of its bold column name or widest data value,
+estimated with Calibri 11-compatible proportional glyph widths, clamped from 3
+through 60 units, and given a 17-pixel fit margin. Wrapping remains based on
+logical visual length: values over 60 visual units or containing explicit line
+breaks are wrapped.
+
+The HTML plugin accepts three plugin-owned environment settings. They are
+captured when PLSQLWKS loads the plugin:
+
+```bash
+PLSQLWKS_HTML_EXPORT_NULL_VALUE="(null)"
+PLSQLWKS_HTML_EXPORT_THEME="dark"
+PLSQLWKS_HTML_EXPORT_DATE_FORMAT="%d.%m.%Y"
+```
+
+`PLSQLWKS_HTML_EXPORT_NULL_VALUE` replaces the exact `<NULL>` grid display
+token and defaults to empty; set it to `<NULL>` or another marker to keep NULL
+values visible. `PLSQLWKS_HTML_EXPORT_THEME` is `bright` (the default) or
+`dark`; both select only bundled static CSS, and printing uses a readable
+bright palette. `PLSQLWKS_HTML_EXPORT_DATE_FORMAT` is empty by default and
+otherwise uses Python `strftime` syntax with the same conservative ISO-display
+matching described for CSV below. These settings affect only generated HTML
+and do not expand Plugin API v1.
+
+The XLSX plugin has equivalent plugin-owned environment settings, captured when
+PLSQLWKS loads it:
+
+```bash
+PLSQLWKS_XLSX_EXPORT_NULL_VALUE="(null)"
+PLSQLWKS_XLSX_EXPORT_THEME="dark"
+PLSQLWKS_XLSX_EXPORT_DATE_FORMAT="%d.%m.%Y"
+PLSQLWKS_XLSX_EXPORT_AUTO_FILTER="no"
+PLSQLWKS_XLSX_EXPORT_AUTO_WIDTH="no"
+PLSQLWKS_XLSX_EXPORT_FREEZE_TOP_ROW="no"
+```
+
+`PLSQLWKS_XLSX_EXPORT_NULL_VALUE` replaces the exact `<NULL>` display token and
+defaults to empty; set it to `<NULL>` or another marker to keep NULL values
+visible. `PLSQLWKS_XLSX_EXPORT_THEME` selects the bundled `bright` (default) or
+`dark` cell styles. `PLSQLWKS_XLSX_EXPORT_DATE_FORMAT` is empty by default and
+otherwise applies Python `strftime` directives to the same strict ISO-shaped
+display strings as CSV and HTML. Formatted date and text values remain literal
+spreadsheet strings rather than formulas or typed Excel dates. The
+`PLSQLWKS_XLSX_EXPORT_AUTO_FILTER` setting enables Excel's column filter
+controls by default. It accepts case-insensitive, whitespace-tolerant `1`,
+`yes`, `true`, or `on` to enable them and `0`, `no`, `false`, or `off` to
+disable them; an unset or malformed value falls back to enabled. When enabled,
+the filter range spans exactly the header and currently loaded rows, without
+applying filter criteria or initially hiding any rows.
+`PLSQLWKS_XLSX_EXPORT_AUTO_WIDTH` controls proportional sizing from the widest
+header or loaded data value and uses the same boolean syntax. When filtering is
+enabled, the header candidate includes three extra character units for the filter
+dropdown. Auto-width defaults to enabled; disabling it leaves Excel's default
+column widths while preserving the existing multiline and over-60-unit cell
+wrapping. `PLSQLWKS_XLSX_EXPORT_FREEZE_TOP_ROW` uses the same boolean syntax,
+defaults to enabled, and keeps row 1 visible while scrolling; disabling it
+leaves the worksheet unfrozen. Freezing is independent of filtering and
+automatic widths. These settings belong to the built-in XLSX plugin and do not
+expand Plugin API v1.
+
+The built-in CSV export formatting can also be customized in the active
+`config.ini`:
+
+```ini
+[plugin.csv-export]
+separator = ,
+null_value =
+date_format =
+protect_formulas = no
+```
+
+`separator` must be one character and defaults to a comma. `null_value`
+defaults to empty, replacing the exact `<NULL>` display value with an empty CSV
+field. Set it to `<NULL>` or another marker to retain a visible value.
+`date_format` defaults to empty, which preserves displayed date values. When
+set, it uses Python `strftime` syntax and formats only calendar-valid,
+full-string ISO display values shaped as `YYYY-MM-DD` or
+`YYYY-MM-DD HH:MM:SS[.digits][+/-HH:MM]`, with one to six fractional digits;
+other text is exported unchanged. This deliberately strict heuristic cannot
+identify non-ISO or otherwise preformatted database date text, while matching
+text-column values are indistinguishable from dates and are formatted too.
+
+`protect_formulas` defaults to `no`, preserving the exact field content and
+existing CSV representation. Set it to `yes` for CSV files intended to be
+opened by people in spreadsheet software. The protected mode quotes every
+field and prefixes formula-triggering values with a tab, including risky ASCII
+and full-width prefixes and leading control characters. This also makes
+legitimate leading signed values such as `-42` text and leaves the tab in data
+seen by programmatic CSV readers. OWASP notes that no CSV neutralization is
+universal across all spreadsheet applications and save/re-open workflows, so
+validate this opt-in mode with the applications in use.
+
 ### Schema Browser
 
 The `F9` schema browser groups tables, views, procedures, functions, packages, triggers, sequences, indexes, and private synonyms from the current schema. Type while the browser is focused to filter object names with a case-insensitive substring match; groups without matches are hidden and matching groups expand automatically without changing their saved expansion state.
@@ -347,8 +513,65 @@ currently be loaded from it.
 workspace/
   sql/       saved SQL files
   plsql/     saved PL/SQL files
-  results/   reserved output directory
+  results/   CSV, HTML, XLSX, and other result output
+```
+
+The first launch creates the workspace folders and starter SQL/PLSQL files.
+
+## Plugin API
+
+Plugin API version 1 is a deliberately small, command-only extension point.
+See [PLUGINS.md](PLUGINS.md) for the focused plugin author and testing guide.
+PLSQLWKS uses that same API for its built-in loaded-row CSV, HTML, and XLSX
+exporters; adding formats requires no direct App integration or public API
+expansion.
+Installed Python packages can add commands to the `Alt-O` menu through the
+standard `plsqlwks.plugins` entry-point group:
+
+```toml
+[project.entry-points."plsqlwks.plugins"]
+example = "example_package.plugin:create_plugin"
+```
+
+A minimal plugin factory is:
+
+```python
+from plsqlwks.plugins import Plugin, PluginCommand, PluginContext
+
+
+def show_loaded_count(context: PluginContext) -> None:
+    result = context.get_active_result()
+    count = len(result.rows) if result is not None else 0
+    context.set_status(f"{count} row(s) are currently loaded")
+
+
+def create_plugin() -> Plugin:
+    return Plugin(
+        id="example",
+        name="Example commands",
+        commands=(
+            PluginCommand(
+                id="show-loaded-count",
+                section="Results",
+                title="Show loaded row count",
+                handler=show_loaded_count,
+            ),
+        ),
+    )
 ```
 
-The first launch creates the workspace folders and starter SQL/PLSQL files. The
-terminal UI does not currently provide a query-export command.
+The entry point must resolve to a zero-argument callable returning `Plugin`.
+Handlers receive only `PluginContext`: it provides an immutable snapshot of the
+active tabular result, the results directory, insert-draft detection, text and
+overwrite prompts, status updates, and UI error reporting. API v1 does not
+provide database execution, mutable results, the application or UI state,
+keyboard registration, drawing, events, lifecycle hooks, background jobs,
+settings schemas, hot reload, or workspace-local executable plugins.
+
+The `[plugin.csv-export]` section and the documented HTML/XLSX environment
+variables configure only their corresponding PLSQLWKS-supplied plugins. Plugin
+API v1 does not provide a generic settings schema or pass these values to
+installed third-party plugins.
+
+Installed plugins are trusted, in-process Python code. They are not sandboxed;
+install plugins only from sources you trust.

plsqlwks-0.1.6/PLUGINS.md

@@ -0,0 +1,320 @@
+# PLSQLWKS plugins
+
+PLSQLWKS Plugin API version 1 is a small, command-only extension point. A plugin
+can add commands to the Alt-O menu and use the limited `PluginContext` passed to
+its command handler. Installed plugins are trusted, in-process Python code. They
+are **not sandboxed** and should be installed only from sources you trust.
+
+## API version 1
+
+Import supported types and constants from `plsqlwks.plugins`:
+
+- `Plugin` describes a plugin and its commands.
+- `PluginCommand` describes one searchable Alt-O menu command.
+- `PluginContext` is the host interface supplied to a command handler.
+- `ResultSnapshot` is an immutable, tuple-based copy of the active table result.
+- `PluginHandler` and `PluginFactory` are the corresponding callable types.
+- `PLUGIN_API_VERSION` and `PLUGIN_ENTRY_POINT_GROUP` identify the contract.
+
+`PluginContext` can read the configured results directory, inspect the active
+result snapshot, detect an active result-grid insert draft, open a text prompt,
+request overwrite confirmation, set status text, and report an error through
+the UI. A snapshot contains exactly the display rows loaded when the command
+starts. Its optional `numeric_values` matrix carries only aligned source
+`Decimal`, `int`, and `float` values; other cells are `None`, and legacy
+snapshots may omit the matrix. No raw rows or Oracle handles cross the plugin
+boundary. `has_more` reports that additional rows exist without exposing a
+continuation or a way to fetch them.
+
+API v1 does not provide database execution, mutable query results, application
+or UI state, curses drawing, arbitrary shortcuts, event or lifecycle hooks,
+background jobs, generic third-party plugin settings, hot reload, or
+workspace-local Python-file loading.
+
+## Registering an installed plugin
+
+Expose a zero-argument factory through the `plsqlwks.plugins` entry-point group:
+
+```toml
+[project.entry-points."plsqlwks.plugins"]
+example = "example_package.plugin:create_plugin"
+```
+
+A minimal `example_package/plugin.py` is:
+
+```python
+from plsqlwks.plugins import Plugin, PluginCommand, PluginContext
+
+
+def show_results_directory(context: PluginContext) -> None:
+    context.set_status(f"Results directory: {context.results_dir}")
+
+
+def create_plugin() -> Plugin:
+    return Plugin(
+        id="example",
+        name="Example commands",
+        commands=(
+            PluginCommand(
+                id="show-results-directory",
+                section="Workspace",
+                title="Show results directory",
+                handler=show_results_directory,
+                keywords="example results directory",
+            ),
+        ),
+    )
+```
+
+Plugin IDs must match the safe pattern `^[a-z][a-z0-9_.-]*$` and are globally
+unique. Command IDs must be nonempty and unique within a plugin. The API version
+must match the host version. Built-in plugins load first, followed by installed
+entry points in deterministic name order. A broken or incompatible installed
+plugin is skipped and reported as a startup warning rather than preventing
+PLSQLWKS from starting. An ordinary exception raised by a command is reported
+through the UI instead of terminating the application.
+
+## Built-in result exports
+
+The bundled CSV, HTML, and XLSX commands are normal built-in `Plugin` objects
+using the same API v1 context available to installed plugins. When enabled,
+they are registered in that order in the **Results** section and have no global
+keyboard shortcuts. None is an App method, and adding export formats requires
+no public API expansion.
+
+### Exporter availability
+
+Each bundled exporter has an independent switch in the active `config.ini`:
+
+```ini
+[plugin.csv-export]
+enabled = yes
+
+[plugin.html-export]
+enabled = yes
+
+[plugin.xlsx-export]
+enabled = yes
+```
+
+Set `enabled = no` to omit that exporter's command from the **Results** menu.
+A missing or malformed value defaults to enabled. These switches control only
+the bundled exporters; installed entry-point plugins are still discovered and
+loaded normally. Restart PLSQLWKS after changing an availability switch.
+
+### CSV export
+
+Choose **Alt-O -> Results -> Export loaded rows to CSV** to export the active
+table snapshot. The command proposes a timestamped name in the workspace
+`results/` directory, accepts relative or absolute paths, and asks before
+replacing an existing file. It writes UTF-8 CSV with a header and exactly the
+currently loaded display rows; it never fetches a continuation page. Export is
+available in read-only mode. An active insert draft must first be committed or
+cancelled so its temporary row cannot be exported.
+
+The shared CSV writer writes a temporary sibling file and atomically replaces
+the destination after a successful close. A failed write therefore does not
+turn an existing destination into an apparently successful partial export.
+
+### HTML export
+
+Choose **Alt-O -> Results -> Export loaded rows to HTML** to write a complete,
+standalone UTF-8 HTML5 document for the active table snapshot. The command
+proposes a timestamped `.html` name in the workspace `results/` directory,
+accepts relative or absolute paths, and asks before replacing an existing file.
+It writes the headers and exactly the currently loaded display rows, followed
+by the loaded-row count and a notice when additional rows remain available; the
+plugin never fetches them. The result title is retained only as browser-tab
+document metadata and is not repeated as a visible heading.
+
+The result-derived document title, column names, and cell values are escaped as
+untrusted text. The document has a small static embedded stylesheet and no
+JavaScript, event handlers, forms, frames, images, remote URLs, or external
+resources. Cell whitespace remains readable, and wide tables scroll
+horizontally. The command does not launch a browser.
+
+Like CSV export, HTML export is available in read-only mode and rejects an
+active insert draft before reading the result or opening a filename prompt. It
+uses the existing context methods for draft detection, immutable snapshot
+access, the results directory, text and overwrite prompts, status updates, and
+error reporting. Atomic replacement keeps a previous destination intact when
+rendering, writing, or replacement fails.
+
+### HTML export configuration
+
+The built-in HTML plugin captures these optional environment variables when
+PLSQLWKS loads it:
+
+```bash
+PLSQLWKS_HTML_EXPORT_NULL_VALUE="(null)"
+PLSQLWKS_HTML_EXPORT_THEME="dark"
+PLSQLWKS_HTML_EXPORT_DATE_FORMAT="%d.%m.%Y"
+```
+
+- `PLSQLWKS_HTML_EXPORT_NULL_VALUE` replaces values exactly equal to the grid's
+  `<NULL>` display token. It defaults to empty and may be set to `<NULL>` or
+  another marker.
+- `PLSQLWKS_HTML_EXPORT_THEME` selects the bundled static `bright` or `dark`
+  stylesheet. It defaults to `bright`; print rules remain bright and readable.
+- `PLSQLWKS_HTML_EXPORT_DATE_FORMAT` accepts Python `strftime` directives. It
+  defaults to empty, preserving displayed values.
+
+The HTML date option uses the same strict ISO-display matching documented for
+CSV: snapshots have display strings, not Oracle type metadata, so invalid or
+nonmatching text is preserved and a text value having the recognized shape is
+indistinguishable from a date. These are settings of the bundled plugin, not a
+generic Plugin API v1 configuration facility. Code embedding the built-in
+factory may instead pass an immutable `HtmlExportOptions` instance explicitly;
+installed third-party entry-point factories remain zero-argument callables.
+
+### XLSX export
+
+Choose **Alt-O -> Results -> Export loaded rows to XLSX** to write one `Query
+result` worksheet containing a header and exactly the loaded result snapshot.
+The command proposes a timestamped `.xlsx` name in the workspace `results/`
+directory, accepts relative or absolute paths, and asks before replacing an
+existing file. It does not fetch continuation rows, access the database, start
+a subprocess, or open the resulting workbook. It remains available in
+read-only mode and rejects an active insert draft before reading the snapshot
+or prompting.
+
+Headers and text cells are explicitly stored as strings. Genuine source
+numbers become native Excel numeric cells only when they are finite, within
+Excel's supported range, and contain at most 15 significant digits. Fixed-point
+formats preserve visible scale such as `10.50`; excess-precision values and
+numeric-looking character data remain exact text and may retain Excel's
+number-as-text warning. Values beginning with `=`, `+`, `-`, or `@` remain
+literal result text and are never interpreted as spreadsheet formulas. The
+workbook contains no macros or external links. Its snapshot title is stored
+only as document metadata; result data remains confined to the single
+worksheet. Each column uses the larger of its bold column name or widest data
+value, estimated with Calibri 11-compatible proportional glyph widths and
+clamped from 3 through 60 units. A 17-pixel fit margin prevents spreadsheet
+font rendering from clipping the last characters. Wrapping remains based on
+logical visual length: values over 60 visual units or containing explicit line
+breaks are wrapped.
+
+XLSX generation uses the optional `openpyxl>=3.1` dependency. It is not a base
+PLSQLWKS runtime dependency. Install a distribution with XLSX support through
+the standard extra:
+
+```bash
+python3 -m pip install 'plsqlwks[xlsx]'
+```
+
+For an editable checkout, use `python3 -m pip install -e '.[xlsx]'`. The
+repository keeps `plugin-requirements/xlsx-export/requirements.txt` as a
+compatible fallback for existing source-checkout automation.
+
+If the dependency is unavailable, invoking the command reports a concise XLSX
+export error through the normal Plugin API UI boundary instead of preventing
+PLSQLWKS from starting.
+
+### XLSX export configuration
+
+The built-in XLSX plugin captures these optional environment variables when
+PLSQLWKS loads it:
+
+```bash
+PLSQLWKS_XLSX_EXPORT_NULL_VALUE="(null)"
+PLSQLWKS_XLSX_EXPORT_THEME="dark"
+PLSQLWKS_XLSX_EXPORT_DATE_FORMAT="%d.%m.%Y"
+PLSQLWKS_XLSX_EXPORT_AUTO_FILTER="no"
+PLSQLWKS_XLSX_EXPORT_AUTO_WIDTH="no"
+PLSQLWKS_XLSX_EXPORT_FREEZE_TOP_ROW="no"
+```
+
+- `PLSQLWKS_XLSX_EXPORT_NULL_VALUE` replaces values exactly equal to the grid's
+  `<NULL>` display token. It defaults to empty and may be set to `<NULL>` or
+  another marker.
+- `PLSQLWKS_XLSX_EXPORT_THEME` selects the bundled `bright` or `dark` cell
+  styles and defaults to `bright`.
+- `PLSQLWKS_XLSX_EXPORT_DATE_FORMAT` accepts Python `strftime` directives and
+  defaults to empty, preserving displayed values.
+- `PLSQLWKS_XLSX_EXPORT_AUTO_FILTER` controls Excel's column filter controls.
+  It defaults to enabled and accepts case-insensitive, whitespace-tolerant
+  `1`, `yes`, `true`, or `on` to enable them and `0`, `no`, `false`, or `off`
+  to disable them. An unset or malformed value falls back to enabled.
+- `PLSQLWKS_XLSX_EXPORT_AUTO_WIDTH` controls proportional column sizing from
+  the widest header or loaded data value. With filtering enabled, the header
+  candidate includes three extra character units for the filter dropdown. It
+  accepts the same boolean values, defaults to enabled, and leaves Excel's
+  default column widths when disabled.
+- `PLSQLWKS_XLSX_EXPORT_FREEZE_TOP_ROW` keeps the first-row header visible
+  while scrolling. It accepts the same boolean values, defaults to enabled,
+  and leaves the worksheet unfrozen when disabled.
+
+When enabled, the auto-filter covers exactly the header row and currently
+loaded rows. It applies no filter criteria, so no data rows are initially
+hidden. Disabling automatic widths does not change cell wrapping: multiline
+values and values above the 60-character-unit wrapping threshold still wrap.
+Freezing is independent of the auto-filter and automatic-width settings.
+
+NULL and date transformations follow the same display-string limitations as
+CSV and HTML and remain literal spreadsheet strings. Numeric provenance is
+independent of these settings. These variables configure only the bundled XLSX
+plugin and are not a generic Plugin API v1 settings mechanism. Code embedding
+its factory may pass an immutable `XlsxExportOptions` value; installed
+entry-point factories remain zero-argument callables.
+
+### CSV export configuration
+
+The built-in CSV plugin reads these host-owned formatting settings from the
+active `config.ini`:
+
+```ini
+[plugin.csv-export]
+separator = ,
+null_value =
+date_format =
+protect_formulas = no
+```
+
+- `separator` is one character and defaults to `,`.
+- `null_value` is written for values that exactly equal the result grid's
+  `<NULL>` display token. It defaults to empty and may be set to `<NULL>` or
+  another marker.
+- `date_format` uses Python `strftime` directives. It defaults to empty, which
+  preserves the displayed value.
+- `protect_formulas` accepts normal INI boolean values and defaults to `no`.
+  When enabled, the plugin protects both headers and formatted data fields
+  that begin with spreadsheet formula-triggering ASCII, control, or full-width
+  characters. It prefixes those values with a tab and quotes every field so
+  the tab remains inside its CSV cell. Missing or malformed values fall back
+  to `no`.
+
+Date formatting is deliberately conservative because Plugin API snapshots
+contain display strings rather than Oracle type metadata. It is applied only
+to valid, full-string ISO display values shaped as `YYYY-MM-DD` or
+`YYYY-MM-DD HH:MM:SS[.digits][+/-HH:MM]`, with one to six fractional digits.
+Invalid dates, ISO values using other shapes, and all nonmatching text remain
+unchanged. A character value with the same valid shape is indistinguishable
+from a date and is formatted too. The directives supported by `strftime` can
+vary slightly by platform.
+
+Formula protection is intended for human spreadsheet viewing. It deliberately
+turns leading signed values such as `-42` into text and exposes the added tab
+to programmatic CSV readers. There is no universal neutralization across all
+spreadsheet applications or save/re-open workflows, so use this opt-in mode
+for the target spreadsheet workflow rather than as a lossless round trip.
+
+This section configures only the PLSQLWKS-supplied plugin. Plugin API v1 has no
+generic configuration schema and does not expose these settings to installed
+third-party plugins.
+
+## Optional plugin tests
+
+Plugin-specific tests are excluded from the default core test run. Run them
+explicitly with either:
+
+```bash
+python3 -m pytest -q -m plugin
+PLSQLWKS_TEST_PLUGINS=1 python3 -m pytest -q
+```
+
+Compatibility manifests for repository plugins remain under
+`plugin-requirements/<plugin-id>/requirements.txt`. The built-in `csv-export`
+and `html-export` plugins have no extra dependencies beyond PLSQLWKS and the
+Python standard library. The built-in `xlsx-export` plugin uses the standard
+`xlsx` extra for `openpyxl>=3.1`; its manifest is retained as a synchronized
+source-checkout fallback.