plsqlwks 0.1.5__tar.gz → 0.1.7__tar.gz

plsqlwks-0.1.7/MANIFEST.in

@@ -0,0 +1,91 @@
+# Source distributions are intentionally allowlisted. Keep this list in sync
+# with the exact artifact manifests asserted by tests/test_packaging.py.
+global-exclude *
+
+include MANIFEST.in
+include PLUGINS.md
+include QUICKSTART.md
+include README.md
+include license.txt
+include pyproject.toml
+include pytest.ini
+include rchar.py
+include requirements.txt
+
+include plsqlwks/__init__.py
+include plsqlwks/__main__.py
+include plsqlwks/exporting.py
+include plsqlwks/html_exporting.py
+include plsqlwks/sqlbinds.py
+include plsqlwks/sqlsplit.py
+include plsqlwks/workspace.py
+include plsqlwks/xlsx_exporting.py
+
+include plsqlwks/config/__init__.py
+include plsqlwks/config/loader.py
+include plsqlwks/config/models.py
+include plsqlwks/config/paths.py
+include plsqlwks/config/session.py
+include plsqlwks/config/settings.py
+
+include plsqlwks/db/__init__.py
+include plsqlwks/db/editing.py
+include plsqlwks/db/execution.py
+include plsqlwks/db/explain.py
+include plsqlwks/db/health.py
+include plsqlwks/db/metadata.py
+include plsqlwks/db/models.py
+include plsqlwks/db/session.py
+include plsqlwks/db/sql_analysis.py
+include plsqlwks/db/transactions.py
+
+include plsqlwks/plugins/__init__.py
+include plsqlwks/plugins/_result_export.py
+include plsqlwks/plugins/api.py
+include plsqlwks/plugins/csv_export.py
+include plsqlwks/plugins/html_export.py
+include plsqlwks/plugins/loader.py
+include plsqlwks/plugins/xlsx_export.py
+
+include plsqlwks/ui/__init__.py
+include plsqlwks/ui/app.py
+include plsqlwks/ui/application_controller.py
+include plsqlwks/ui/browser.py
+include plsqlwks/ui/buffer.py
+include plsqlwks/ui/catalog.py
+include plsqlwks/ui/clipboard.py
+include plsqlwks/ui/command_dispatcher.py
+include plsqlwks/ui/commands.py
+include plsqlwks/ui/completion.py
+include plsqlwks/ui/constants.py
+include plsqlwks/ui/db_operations.py
+include plsqlwks/ui/db_session.py
+include plsqlwks/ui/db_worker.py
+include plsqlwks/ui/dialogs.py
+include plsqlwks/ui/display.py
+include plsqlwks/ui/documents.py
+include plsqlwks/ui/editor_controller.py
+include plsqlwks/ui/errors.py
+include plsqlwks/ui/help.py
+include plsqlwks/ui/input_controller.py
+include plsqlwks/ui/key_reader.py
+include plsqlwks/ui/keys.py
+include plsqlwks/ui/menu.py
+include plsqlwks/ui/plugin_host.py
+include plsqlwks/ui/ports.py
+include plsqlwks/ui/query_controller.py
+include plsqlwks/ui/renderer.py
+include plsqlwks/ui/result_controller.py
+include plsqlwks/ui/result_presenter.py
+include plsqlwks/ui/results.py
+include plsqlwks/ui/sql.py
+include plsqlwks/ui/state.py
+include plsqlwks/ui/syntax.py
+include plsqlwks/ui/viewport.py
+
+include plugin-requirements/csv-export/requirements.txt
+include plugin-requirements/html-export/requirements.txt
+include plugin-requirements/xlsx-export/requirements.txt
+include tests/conftest.py
+include tests/fixtures/config_exports.txt
+include tests/fixtures/ui_exports.txt

{plsqlwks-0.1.5 → plsqlwks-0.1.7}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: plsqlwks
-Version: 0.1.5
+Version: 0.1.7
 Summary: An ncurses SQL and PL/SQL workspace for Oracle databases.
+Author: unu2000
 License-Expression: LicenseRef-plsqlwks-Donationware
 Project-URL: Repository, https://gitlab.com/unununu/plsqlwks
 Project-URL: Issues, https://gitlab.com/unununu/plsqlwks/-/issues
 Project-URL: Changelog, https://gitlab.com/unununu/plsqlwks/-/blob/main/CHANGELOG.md
+Project-URL: Ko-fi, https://ko-fi.com/unu2000
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Database
@@ -13,6 +15,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"
@@ -25,8 +29,19 @@ Dynamic: license-file
 
 An ncurses SQL and PL/SQL workspace for Oracle databases.
 
+Author and support: [unu2000 on Ko-fi](https://ko-fi.com/unu2000).
+
+The supported and continuously tested database releases are Oracle Database
+19c and Oracle AI Database 26ai. See the
+[Oracle compatibility matrix](https://gitlab.com/unununu/plsqlwks/-/blob/main/COMPATIBILITY.md) for the tested connection and
+privilege profiles, safety gate, and integration-test setup.
+
 ![PLSQLWKS PREVIEW](https://gitlab.com/unununu/plsqlwks/-/raw/main/img/preview.png)
 
+New here? Follow the [installation-to-first-query quick start](QUICKSTART.md)
+for copy-ready connection setup, screenshots, practical SQL workflows,
+troubleshooting, and a complete installed-plugin example.
+
 ## Connection
 
 The default connection is:
@@ -83,16 +98,52 @@ python3 -m pip install .
 Run the default test and lint checks from a development checkout with:
 
 ```bash
-python3 -m pytest -q
+python3 -m pytest -q --maxfail=1
 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 --maxfail=1
+python3 -m pytest -q --maxfail=1 -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:
+above and a nonempty regular password file. Setting `PLSQLWKS_TEST_ORACLE=1`
+is an explicit opt-in, so invalid or missing credentials fail collection rather
+than silently skipping the live suite. Set `PLSQLWKS_TEST_ORACLE_TARGET` to
+`19c` or `26ai` when the test run must verify that it reached the intended
+server release:
 
 ```bash
-PLSQLWKS_TEST_ORACLE=1 PLSQLWKS_TEST_PTY=1 PLSQLWKS_TEST_SLOW=1 \
-  python3 -m pytest -q -rs
+PLSQLWKS_TEST_ORACLE=1 PLSQLWKS_TEST_ORACLE_TARGET=19c \
+  python3 -m pytest -q -m oracle --maxfail=1
+```
+
+Omit the target for an ad-hoc run against another reachable Oracle database.
+The complete release-gating setup, including the developer, DML-only, and
+read-only profiles, is documented in the
+[Oracle compatibility matrix](https://gitlab.com/unununu/plsqlwks/-/blob/main/COMPATIBILITY.md).
+Enable every optional test group with:
+
+```bash
+PLSQLWKS_TEST_ORACLE=1 PLSQLWKS_TEST_PLUGINS=1 PLSQLWKS_TEST_PTY=1 PLSQLWKS_TEST_SLOW=1 \
+  python3 -m pytest -q -rs --maxfail=1
 ```
 
 ## Run
@@ -113,6 +164,11 @@ The CLI option takes precedence over `PLSQLWKS_WORKSPACE`. For compatibility, a
 source checkout that already contains a configured `workspace/` continues to
 use it and displays a migration notice; files are never moved automatically.
 
+Fresh workspaces start in manual transaction mode and write
+`[database] autocommit = no` to their generated `config.ini`. Existing explicit
+`yes` or `no` settings are preserved; a missing or malformed setting uses the
+safe manual fallback.
+
 Choose the initial transaction mode for one invocation with `--manual` or
 `--autocommit`. These options override `[database] autocommit` from the active
 `config.ini`:
@@ -153,9 +209,21 @@ explicitly, so Oracle rolls its uncommitted work back.
 If the old connection is already dead and reports an error while closing,
 plsqlwks still attempts the replacement connection and reports the close error
 as a warning after a successful reconnect.
+An unexpected connection loss is shown in the header and status bar. Rows that
+were already loaded remain available for viewing, but paging, editing, and
+inserting are disabled until reconnect because their live cursor/session state
+is no longer valid. If manual work may have been pending, the status explicitly
+warns that the transaction outcome is unknown.
 
 After a successful quit, plsqlwks records the open file-backed tabs, active tab, and cursor positions in the managed `[session.tabs]` section of `config.ini`. Fresh platform-default workspaces use the user-config directory; explicitly selected and legacy workspaces keep `config.ini` inside the workspace for compatibility. On the next start the app tries each saved path independently, silently skips files that are missing or unreadable, and leaves the initial empty tab in place when none can be opened. A saved cursor position that no longer exists in its file starts at the beginning instead. Untitled, template, and generated schema tabs are not persisted because they do not have a file to reopen.
 
+Worksheet and configuration saves replace their destination atomically while
+preserving an existing file's POSIX permission bits. A
+file-backed worksheet also detects when its file was changed or deleted outside
+plsqlwks and asks whether to overwrite it, save under another name, or cancel.
+Undo and redo update the unsaved-change marker by comparing the current content
+with the last successful save.
+
 ## Keys
 
 ### Global
@@ -169,9 +237,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 |
@@ -197,14 +265,14 @@ 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 |
 | `F4` | New template |
 | `F5` / `Ctrl-Enter` / `Alt-X` | Execute selected SQL or current statement |
 | `F11` | Execute selected SQL or whole buffer as a script |
-| `Alt-G` | Generate SELECT, INSERT, or UPDATE with table columns |
+| `Alt-G` | Generate SELECT, INSERT, or UPDATE with table or view columns |
 | `Alt-+` | Refresh autocomplete metadata cache |
 | `Alt-R` | Rename current buffer |
 | `Ctrl-T` | New file tab |
@@ -223,7 +291,18 @@ After a successful quit, plsqlwks records the open file-backed tabs, active tab,
 | `Ctrl+=` | Reconnect |
 
 Use `/` on a line by itself after PL/SQL objects or anonymous blocks when running a script.
-Execution and explain errors report the mapped editor line and column, then move the cursor to that location when Oracle provides one.
+Script execution reports statement progress as `n/total` and stops at the first
+failed statement while preserving earlier results. Scripts are sent directly to
+Oracle, not through SQL*Plus or SQLcl: client commands such as `PROMPT`, `SPOOL`,
+and `SET SERVEROUTPUT`, and `&`/`&&` substitution variables, are rejected before
+bind prompts or execution. Oracle SQL statements such as `SET TRANSACTION`
+remain supported.
+Execution and explain errors report mapped editor line and column diagnostics.
+The cursor moves only when the buffer still matches the source that was sent to
+Oracle; if it changed while the operation ran, the result warns about the stale
+source instead. Use `Alt-O -> Editor -> Next execution diagnostic` or
+`Previous execution diagnostic` to visit additional locations from the most
+recent unchanged source.
 When executed or explained SQL contains bind variables such as `:id`, plsqlwks opens a text box for each value and sends the answers as Oracle bind parameters.
 Unquoted bind names are case-insensitive, so `:id` and `:ID` share one prompt and value. Quoted bind names remain case-sensitive.
 Set `[database] remember_bind_values = yes` in the active `config.ini` to prefill future bind prompts with values entered earlier in the same app session.
@@ -270,6 +349,7 @@ Read-only mode is a client-side guardrail that rejects statements which the SQL
 | `Home` / `End` | Move to the first/last result-grid column |
 | `Ctrl-Home` / `Ctrl-End` | Move to the first/last result-grid row |
 | `F8` | Toggle result grid / row-detail output |
+| `Ctrl-C` | Copy the selected result cell to the clipboard |
 | `F10` | View the full selected result cell |
 | `Enter` | Edit the selected ROWID-backed result cell when available |
 | `INS` | Prepare a draft insert row for ROWID-backed results |
@@ -284,7 +364,11 @@ unquoted current-schema table that include `ROWID`, press `Enter` on a directly
 selected unquoted table column to update it by rowid. Press `INS` in the grid to
 prepare a draft row at the top of the grid, edit its cells with `Enter`, use
 `Ctrl-Alt-C` to insert it, or use `Esc` to cancel it.
-Database null values are displayed and entered as `<NULL>` in editable results. Plain `NULL` is stored as literal text.
+While entering a cell, use Left/Right or Home/End to move within the existing
+text and Backspace/Delete to edit around the cursor. DATE and TIMESTAMP cells
+offer a choice between an ISO value and database-side `SYSDATE`.
+Database null values are displayed and entered as `<NULL>` in editable results.
+Plain `NULL` is stored as literal text.
 Grid edits compare the selected cell's originally loaded typed value as well as
 the `ROWID`. If another session changes that cell or deletes the row first, the
 edit is rejected and the query must be refreshed. Changes to other cells in the
@@ -297,8 +381,159 @@ precision above six, are read-only in the grid.
 Displayed CLOB and BLOB values are limited to the first 65,536 characters or
 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.
+DBMS_OUTPUT is collected after each statement and after every fetched result
+page without replacing a real query grid. Output-read or cursor-cleanup failures
+are displayed as warnings while preserving successfully fetched rows. PL/SQL
+compiler warnings are also retained with successful statement results; compiler
+errors remain execution failures with navigable source locations.
 `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.
@@ -344,8 +579,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.