plsqlwks 0.1.9.0__tar.gz → 0.2.0__tar.gz

{plsqlwks-0.1.9.0 → plsqlwks-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plsqlwks
-Version: 0.1.9.0
+Version: 0.2.0
 Summary: An ncurses SQL and PL/SQL workspace for Oracle databases.
 Author: unu2000
 License-Expression: LicenseRef-plsqlwks-Donationware
@@ -488,6 +488,149 @@ 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.
 
+## Windows PuTTY keyboard setup
+
+For Windows PuTTY 0.83 and 0.85, use a saved session with these settings before
+starting plsqlwks on the Linux/Unix host:
+
+| PuTTY panel | Setting |
+| --- | --- |
+| Connection → Data | Terminal-type string: `xterm-256color` |
+| Window → Translation | Remote character set: `UTF-8` |
+| Terminal → Keyboard | Backspace: `Control-? (127)`; Home/End: `Standard` |
+| Terminal → Keyboard | Function keys and keypad: `Xterm 216+` |
+| Terminal → Keyboard | Shifted arrow keys: `xterm-style bitmap` |
+| Terminal → Keyboard | Keep **Control-Alt is different from AltGr** enabled |
+| Terminal → Features | Enable **Disable application cursor keys mode** and **Disable application keypad mode** |
+| Terminal → Features | Leave **Disable bracketed paste mode** unchecked |
+| Terminal | Local echo and local line editing: `Force off` |
+
+Save the session and use a UTF-8 locale on the host. Disabling application cursor
+keys is necessary because curses enables that mode, and PuTTY otherwise drops
+arrow modifiers even when bitmap mode is selected.
+
+### Exact Ctrl shortcuts with the Windows helper
+
+Stock Windows PuTTY does not send Ctrl-Home/End, Ctrl-Shift-Home/End, or
+Ctrl-Delete at all, and consumes modified PageUp/PageDown for scrollback.
+Use the optional [Windows helper](tools/putty_keys.ps1) to make the original
+shortcuts work. Run it on the **Windows computer running PuTTY**; from a checkout:
+
+```powershell
+powershell.exe -NoProfile -File .\tools\putty_keys.ps1
+```
+
+Focus the PuTTY window running plsqlwks, then press **Ctrl-Alt-F12** to enable
+remapping for that window. The helper console confirms activation. It remaps
+one selected PuTTY window while the helper is running. Press Ctrl-Alt-F12 again
+to disable it before using another program in that terminal, or press Ctrl-C
+in the helper console to stop it. Enabling a different PuTTY window switches
+the selection to that window.
+
+With the helper enabled, `Ctrl-Home` / `Ctrl-End` move to the beginning/end of
+the editor buffer or the first/last result row. `Ctrl-Shift-Home` /
+`Ctrl-Shift-End` select to buffer boundaries. The helper also restores
+`Ctrl-Delete`, `Ctrl-Backspace`, `Ctrl-Enter`, `Ctrl-PageUp` / `Ctrl-PageDown`,
+`Shift-PageUp` / `Shift-PageDown`, and `Ctrl+=`. Plain Enter and Backspace keep
+their normal meaning. The helper requires only Windows PowerShell and its
+included .NET runtime; it requires no administrator rights or installation.
+Run the same command with `-SelfTest` to check its mappings without enabling it.
+
+### Alternatives without the helper
+
+Some physical combinations cannot reach plsqlwks distinctly in stock Windows
+PuTTY. Use the following alternatives; they also work in terminals that send
+these sequences, and the original bindings remain available elsewhere:
+
+| Existing shortcut | PuTTY alternative | Action |
+| --- | --- | --- |
+| `Ctrl-Home` / `Ctrl-End` | `Alt-Home` / `Alt-End` | Editor buffer start/end; first/last result row |
+| `Ctrl-Shift-Home` / `Ctrl-Shift-End` | `Alt-Shift-Home` / `Alt-Shift-End` | Select to editor buffer boundaries |
+| `Ctrl-Delete` | `Alt-Delete` | Delete next word |
+| `Ctrl-Enter` | `F5` or `Alt-X` | Execute selection/current statement |
+| `Ctrl-PageUp` / `Ctrl-PageDown` | `Alt-PageUp` / `Alt-PageDown` | Page focused results; otherwise switch file tabs |
+| `Shift-PageUp` / `Shift-PageDown` | `Ctrl-Shift-Up` / `Ctrl-Shift-Down` | Extend editor selection by page |
+| `Ctrl-Backspace` | `Alt-Backspace` | Delete previous word |
+| `Ctrl+=` | `Alt-O` → **Database** → **Reconnect** | Reconnect |
+
+PuTTY sends the same carriage return for Enter and Ctrl-Enter, and the same
+DEL byte for Backspace and Ctrl-Backspace. plsqlwks preserves newline and
+single-character deletion for those bytes. PuTTY consumes Ctrl/Shift-PageUp
+and PageDown for its own scrollback; changing the function-key setting does
+not free them. See the [PuTTY keyboard settings](https://the.earth.li/~sgtatham/putty/0.85/htmldoc/Chapter4.html#config-keyboard)
+and [scrollback shortcuts](https://the.earth.li/~sgtatham/putty/0.85/htmldoc/Chapter3.html#using-scrollback).
+
+Use left Alt for application shortcuts; AltGr remains available for characters
+on international keyboards. Shortcut digits and symbols refer to the character
+on the active Windows layout: for example, Czech top-row digits need Shift,
+so Alt-1 is typed with Alt-Shift-1. Use the layout's `+` or `=` character for
+autocomplete refresh. `Ctrl-C`, `Ctrl-X`, and `Ctrl-V` operate on the
+application/host clipboard with the existing internal fallback. SSH does not
+make that the Windows clipboard. Use PuTTY's native paste (`Shift-Insert` or
+right-click) to insert Windows clipboard text as bracketed paste, and PuTTY
+mouse selection to copy to Windows. Leave plsqlwks' Ctrl-letter shortcuts
+available to the server when customizing PuTTY clipboard settings.
+
+For troubleshooting, run `python3 rchar.py` from the checkout in the same PuTTY
+session to capture a key's actual bytes. Verify the session settings above
+before reporting a shortcut failure.
+
+## Windows Command Prompt keyboard setup
+
+Use plsqlwks through `ssh.exe` or WSL inside **Command Prompt (`cmd.exe`)**.
+The helper supports both the classic Windows console and Command Prompt hosted
+by Windows Terminal. plsqlwks itself runs on the Linux/Unix host or inside WSL,
+where Python provides curses.
+
+In one Command Prompt window, connect to the host or start WSL:
+
+```bat
+ssh user@host
+```
+
+or:
+
+```bat
+wsl.exe
+```
+
+Then run the installed application in that Linux/Unix shell:
+
+```sh
+TERM=xterm-256color plsqlwks
+```
+
+In a **second Command Prompt window**, start the Windows helper from the checkout:
+
+```bat
+tools\windows_keys.cmd
+```
+
+Keep that helper window open. Focus the terminal running plsqlwks and press
+**Ctrl-Alt-F12**; the helper confirms activation. The original shortcuts now
+reach the application, including **Ctrl-Home/End**, **Ctrl-Shift-Home/End**,
+modified arrows, word deletion, execution, paging, and `Ctrl+=`. `F11` executes
+the script instead of switching Windows Terminal to fullscreen.
+
+Use a dedicated terminal window for plsqlwks. The helper selects a window, so
+disable it with Ctrl-Alt-F12 before switching that window to another tab, pane,
+or program. Press Ctrl-C in the helper window to stop it. Left Alt is used for
+shortcuts; AltGr remains available for typing. Leave the classic console's
+**Use legacy console** option off. Use a UTF-8 locale on the Linux/Unix host.
+
+For Windows Terminal, set `"altGrAliasing": false` in the Command Prompt
+profile in its JSON settings. This keeps left Ctrl-Alt-C/R available for
+commit/rollback on international keyboards while preserving the real AltGr
+key. See Microsoft's [AltGr aliasing setting](https://learn.microsoft.com/en-us/windows/terminal/customize-settings/profile-advanced#altgr-aliasing).
+
+The `.cmd` launcher uses the included Windows PowerShell runtime and applies
+its script execution policy only to that helper process. No administrator
+rights, installation, or permanent policy change is needed. Keep
+`windows_keys.cmd` and `putty_keys.ps1` together when copying them elsewhere.
+Run `tools\windows_keys.cmd -SelfTest` to check the helper without enabling it.
+The original `powershell.exe -NoProfile -File .\tools\putty_keys.ps1` command
+also works from Command Prompt and continues to support PuTTY.
+
 ## Keys
 
 ### Global
@@ -716,6 +859,19 @@ current Thin driver.
 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.
+To copy DBMS_OUTPUT, show it with **F6** and focus it with **Tab**. Use
+**Shift+navigation** to select text and **Ctrl+C** to copy; **Ctrl+A** selects
+all output. **Alt-O -> Results -> Copy all DBMS_OUTPUT** also copies the whole
+buffer while another pane is focused. Tab/Esc returns to the editor. Home/End
+move within a displayed line; Ctrl+Home/End move to the output boundaries.
+
+Copying preserves the stored text, whitespace, blank lines, and statement
+headings, without screen wrapping or padding. The existing system clipboard
+providers are used when available, with the internal clipboard as a fallback
+(including remote PuTTY sessions). Ctrl+C still cancels a running operation
+before performing a copy. Selection belongs to its file tab, survives appended
+output and resizing, and resets when execution replaces the output.
+
 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
@@ -980,6 +1136,27 @@ lifecycle change requires a restart. See the
 [managed-package guide](https://gitlab.com/unununu/plsqlwks/-/blob/main/doc/PLUGINS.md#managed-plugin-packages)
 for the exact manifest, source layout, validation, replacement, and trust rules.
 
+### Dependencies walker
+
+Install the optional dependency browser and restart PLSQLWKS:
+
+```bash
+plsqlwks plugin install plugins/packages/dependencies-walker-0.1.0.plwgn
+```
+
+Choose **Alt-O -> Database -> Dependencies walker** and enter an object name,
+optionally qualified by schema. Expand with Enter/Right, collapse with Left,
+and use **D** (Depends on) or **U** (Used by) to follow the selected object in
+either direction. Backspace restores the previous tree; **R** refreshes and
+Esc closes. Packages combine specification/body relationships with labels.
+
+The walker reads only visible Oracle-recorded dependencies, loads branches
+on demand, marks cycles, and leaves database-link references unexpanded.
+Dynamic SQL and foreign-key graphs are outside this view. See the
+[plugin catalog](https://gitlab.com/unununu/plsqlwks/-/blob/main/doc/PLUGIN_CATALOG.md#dependencies-walker)
+for all controls and installation details. No additional runtime dependency is
+required.
+
 ### Maintained csv2oratab integration
 
 The maintained `csv2oratab-0.1.0.plwgn` catalog package adds **Alt-O -> Data ->

{plsqlwks-0.1.9.0 → plsqlwks-0.2.0}/README.md

@@ -454,6 +454,149 @@ 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.
 
+## Windows PuTTY keyboard setup
+
+For Windows PuTTY 0.83 and 0.85, use a saved session with these settings before
+starting plsqlwks on the Linux/Unix host:
+
+| PuTTY panel | Setting |
+| --- | --- |
+| Connection → Data | Terminal-type string: `xterm-256color` |
+| Window → Translation | Remote character set: `UTF-8` |
+| Terminal → Keyboard | Backspace: `Control-? (127)`; Home/End: `Standard` |
+| Terminal → Keyboard | Function keys and keypad: `Xterm 216+` |
+| Terminal → Keyboard | Shifted arrow keys: `xterm-style bitmap` |
+| Terminal → Keyboard | Keep **Control-Alt is different from AltGr** enabled |
+| Terminal → Features | Enable **Disable application cursor keys mode** and **Disable application keypad mode** |
+| Terminal → Features | Leave **Disable bracketed paste mode** unchecked |
+| Terminal | Local echo and local line editing: `Force off` |
+
+Save the session and use a UTF-8 locale on the host. Disabling application cursor
+keys is necessary because curses enables that mode, and PuTTY otherwise drops
+arrow modifiers even when bitmap mode is selected.
+
+### Exact Ctrl shortcuts with the Windows helper
+
+Stock Windows PuTTY does not send Ctrl-Home/End, Ctrl-Shift-Home/End, or
+Ctrl-Delete at all, and consumes modified PageUp/PageDown for scrollback.
+Use the optional [Windows helper](tools/putty_keys.ps1) to make the original
+shortcuts work. Run it on the **Windows computer running PuTTY**; from a checkout:
+
+```powershell
+powershell.exe -NoProfile -File .\tools\putty_keys.ps1
+```
+
+Focus the PuTTY window running plsqlwks, then press **Ctrl-Alt-F12** to enable
+remapping for that window. The helper console confirms activation. It remaps
+one selected PuTTY window while the helper is running. Press Ctrl-Alt-F12 again
+to disable it before using another program in that terminal, or press Ctrl-C
+in the helper console to stop it. Enabling a different PuTTY window switches
+the selection to that window.
+
+With the helper enabled, `Ctrl-Home` / `Ctrl-End` move to the beginning/end of
+the editor buffer or the first/last result row. `Ctrl-Shift-Home` /
+`Ctrl-Shift-End` select to buffer boundaries. The helper also restores
+`Ctrl-Delete`, `Ctrl-Backspace`, `Ctrl-Enter`, `Ctrl-PageUp` / `Ctrl-PageDown`,
+`Shift-PageUp` / `Shift-PageDown`, and `Ctrl+=`. Plain Enter and Backspace keep
+their normal meaning. The helper requires only Windows PowerShell and its
+included .NET runtime; it requires no administrator rights or installation.
+Run the same command with `-SelfTest` to check its mappings without enabling it.
+
+### Alternatives without the helper
+
+Some physical combinations cannot reach plsqlwks distinctly in stock Windows
+PuTTY. Use the following alternatives; they also work in terminals that send
+these sequences, and the original bindings remain available elsewhere:
+
+| Existing shortcut | PuTTY alternative | Action |
+| --- | --- | --- |
+| `Ctrl-Home` / `Ctrl-End` | `Alt-Home` / `Alt-End` | Editor buffer start/end; first/last result row |
+| `Ctrl-Shift-Home` / `Ctrl-Shift-End` | `Alt-Shift-Home` / `Alt-Shift-End` | Select to editor buffer boundaries |
+| `Ctrl-Delete` | `Alt-Delete` | Delete next word |
+| `Ctrl-Enter` | `F5` or `Alt-X` | Execute selection/current statement |
+| `Ctrl-PageUp` / `Ctrl-PageDown` | `Alt-PageUp` / `Alt-PageDown` | Page focused results; otherwise switch file tabs |
+| `Shift-PageUp` / `Shift-PageDown` | `Ctrl-Shift-Up` / `Ctrl-Shift-Down` | Extend editor selection by page |
+| `Ctrl-Backspace` | `Alt-Backspace` | Delete previous word |
+| `Ctrl+=` | `Alt-O` → **Database** → **Reconnect** | Reconnect |
+
+PuTTY sends the same carriage return for Enter and Ctrl-Enter, and the same
+DEL byte for Backspace and Ctrl-Backspace. plsqlwks preserves newline and
+single-character deletion for those bytes. PuTTY consumes Ctrl/Shift-PageUp
+and PageDown for its own scrollback; changing the function-key setting does
+not free them. See the [PuTTY keyboard settings](https://the.earth.li/~sgtatham/putty/0.85/htmldoc/Chapter4.html#config-keyboard)
+and [scrollback shortcuts](https://the.earth.li/~sgtatham/putty/0.85/htmldoc/Chapter3.html#using-scrollback).
+
+Use left Alt for application shortcuts; AltGr remains available for characters
+on international keyboards. Shortcut digits and symbols refer to the character
+on the active Windows layout: for example, Czech top-row digits need Shift,
+so Alt-1 is typed with Alt-Shift-1. Use the layout's `+` or `=` character for
+autocomplete refresh. `Ctrl-C`, `Ctrl-X`, and `Ctrl-V` operate on the
+application/host clipboard with the existing internal fallback. SSH does not
+make that the Windows clipboard. Use PuTTY's native paste (`Shift-Insert` or
+right-click) to insert Windows clipboard text as bracketed paste, and PuTTY
+mouse selection to copy to Windows. Leave plsqlwks' Ctrl-letter shortcuts
+available to the server when customizing PuTTY clipboard settings.
+
+For troubleshooting, run `python3 rchar.py` from the checkout in the same PuTTY
+session to capture a key's actual bytes. Verify the session settings above
+before reporting a shortcut failure.
+
+## Windows Command Prompt keyboard setup
+
+Use plsqlwks through `ssh.exe` or WSL inside **Command Prompt (`cmd.exe`)**.
+The helper supports both the classic Windows console and Command Prompt hosted
+by Windows Terminal. plsqlwks itself runs on the Linux/Unix host or inside WSL,
+where Python provides curses.
+
+In one Command Prompt window, connect to the host or start WSL:
+
+```bat
+ssh user@host
+```
+
+or:
+
+```bat
+wsl.exe
+```
+
+Then run the installed application in that Linux/Unix shell:
+
+```sh
+TERM=xterm-256color plsqlwks
+```
+
+In a **second Command Prompt window**, start the Windows helper from the checkout:
+
+```bat
+tools\windows_keys.cmd
+```
+
+Keep that helper window open. Focus the terminal running plsqlwks and press
+**Ctrl-Alt-F12**; the helper confirms activation. The original shortcuts now
+reach the application, including **Ctrl-Home/End**, **Ctrl-Shift-Home/End**,
+modified arrows, word deletion, execution, paging, and `Ctrl+=`. `F11` executes
+the script instead of switching Windows Terminal to fullscreen.
+
+Use a dedicated terminal window for plsqlwks. The helper selects a window, so
+disable it with Ctrl-Alt-F12 before switching that window to another tab, pane,
+or program. Press Ctrl-C in the helper window to stop it. Left Alt is used for
+shortcuts; AltGr remains available for typing. Leave the classic console's
+**Use legacy console** option off. Use a UTF-8 locale on the Linux/Unix host.
+
+For Windows Terminal, set `"altGrAliasing": false` in the Command Prompt
+profile in its JSON settings. This keeps left Ctrl-Alt-C/R available for
+commit/rollback on international keyboards while preserving the real AltGr
+key. See Microsoft's [AltGr aliasing setting](https://learn.microsoft.com/en-us/windows/terminal/customize-settings/profile-advanced#altgr-aliasing).
+
+The `.cmd` launcher uses the included Windows PowerShell runtime and applies
+its script execution policy only to that helper process. No administrator
+rights, installation, or permanent policy change is needed. Keep
+`windows_keys.cmd` and `putty_keys.ps1` together when copying them elsewhere.
+Run `tools\windows_keys.cmd -SelfTest` to check the helper without enabling it.
+The original `powershell.exe -NoProfile -File .\tools\putty_keys.ps1` command
+also works from Command Prompt and continues to support PuTTY.
+
 ## Keys
 
 ### Global
@@ -682,6 +825,19 @@ current Thin driver.
 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.
+To copy DBMS_OUTPUT, show it with **F6** and focus it with **Tab**. Use
+**Shift+navigation** to select text and **Ctrl+C** to copy; **Ctrl+A** selects
+all output. **Alt-O -> Results -> Copy all DBMS_OUTPUT** also copies the whole
+buffer while another pane is focused. Tab/Esc returns to the editor. Home/End
+move within a displayed line; Ctrl+Home/End move to the output boundaries.
+
+Copying preserves the stored text, whitespace, blank lines, and statement
+headings, without screen wrapping or padding. The existing system clipboard
+providers are used when available, with the internal clipboard as a fallback
+(including remote PuTTY sessions). Ctrl+C still cancels a running operation
+before performing a copy. Selection belongs to its file tab, survives appended
+output and resizing, and resets when execution replaces the output.
+
 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
@@ -946,6 +1102,27 @@ lifecycle change requires a restart. See the
 [managed-package guide](https://gitlab.com/unununu/plsqlwks/-/blob/main/doc/PLUGINS.md#managed-plugin-packages)
 for the exact manifest, source layout, validation, replacement, and trust rules.
 
+### Dependencies walker
+
+Install the optional dependency browser and restart PLSQLWKS:
+
+```bash
+plsqlwks plugin install plugins/packages/dependencies-walker-0.1.0.plwgn
+```
+
+Choose **Alt-O -> Database -> Dependencies walker** and enter an object name,
+optionally qualified by schema. Expand with Enter/Right, collapse with Left,
+and use **D** (Depends on) or **U** (Used by) to follow the selected object in
+either direction. Backspace restores the previous tree; **R** refreshes and
+Esc closes. Packages combine specification/body relationships with labels.
+
+The walker reads only visible Oracle-recorded dependencies, loads branches
+on demand, marks cycles, and leaves database-link references unexpanded.
+Dynamic SQL and foreign-key graphs are outside this view. See the
+[plugin catalog](https://gitlab.com/unununu/plsqlwks/-/blob/main/doc/PLUGIN_CATALOG.md#dependencies-walker)
+for all controls and installation details. No additional runtime dependency is
+required.
+
 ### Maintained csv2oratab integration
 
 The maintained `csv2oratab-0.1.0.plwgn` catalog package adds **Alt-O -> Data ->

{plsqlwks-0.1.9.0 → plsqlwks-0.2.0}/doc/API.md

@@ -189,6 +189,8 @@ class PluginContext(Protocol):
     def get_suggested_table(self) -> str: ...
     def start_result_export(self, request: ResultExportRequest) -> None: ...
     def start_code_generation(self, request: CodeGenerationRequest) -> None: ...
+    def start_dependency_walk(self) -> None: ...
+    def start_sqlplus(self, executable: str = "sqlplus") -> None: ...
 ```
 
 - `results_dir` is the configured result-file directory.
@@ -216,6 +218,12 @@ class PluginContext(Protocol):
   default and must still be validated through a host-managed request.
 - `start_result_export()` and `start_code_generation()` transfer work to the
   workflows below.
+- `start_dependency_walk()` opens the host-managed dependency walker described
+  below. It takes no database objects or callbacks and returns immediately after
+  the initial object prompt, before asynchronous metadata work completes.
+- `start_sqlplus(executable="sqlplus")` runs the host-managed interactive
+  SQL*Plus launcher described below. It returns after SQL*Plus exits and the
+  user presses a key to return to PLSQLWKS.
 
 Context properties and synchronous UI methods belong to the handler/UI thread.
 Do not call a saved context from an export writer or another plugin-created
@@ -524,6 +532,27 @@ def generate_select(context: PluginContext) -> None:
 ordinary exceptions are also reported through the plugin error UI. The exact
 wording of either presentation is not part of the API.
 
+## Dependency walking
+
+`PluginContext.start_dependency_walk()` is an additive API v1 capability. The
+host prompts for `OBJECT` or `SCHEMA.OBJECT`, suggests the selected schema-browser
+object when available, resolves quoted identifiers and ambiguous types, then
+opens a keyboard-driven dependency tree. Metadata reads use the initiating
+tab's session and its normal worker/cancellation mechanism. Closing the walker
+preserves the editor, result table, and output; no transaction is committed or
+rolled back by the walker.
+
+The tree follows visible `ALL_DEPENDENCIES` relationships in either direction.
+Package specifications and bodies share a node with labeled edges. Expansion
+loads one page at a time; cycles and remote references are leaves. The host
+does not expose SQL, cursors, or a general-purpose job or UI interface to the
+plugin. See the [catalog guide](PLUGIN_CATALOG.md#dependencies-walker) for keys,
+visibility limits, and installation.
+
+A plugin using this added public method may check whether it is callable and
+report an upgrade requirement on older hosts. Existing API v1 plugins need no
+changes.
+
 ## Managed packages and lifecycle
 
 Managed packages provide offline distribution for the same API-v1 factories.
@@ -619,17 +648,52 @@ access process data, perform I/O, and otherwise act with the user's authority.
 Review source and verify provenance before installing, and keep secrets out of
 plugin settings when code from another publisher can run in the same process.
 
+## SQL*Plus launching
+
+`PluginContext.start_sqlplus(executable="sqlplus")` is an additive API v1
+capability. The host requires a connected active session and no database
+operation running in any tab. It reads the loaded configuration's username,
+DSN, and password file, then launches the selected executable directly, without
+a shell, in the workspace directory. An executable name is resolved through
+`PATH`; a path selects a particular client. Credentials never enter the plugin
+context or process arguments. A private temporary symlink gives SQL*Plus access
+to a startup script through an inherited pipe; no password-bearing regular
+file is created.
+
+The host suspends curses and keyboard reporting, leaves SQL*Plus in control of
+the terminal, and handles Ctrl+C without closing PLSQLWKS. After SQL*Plus exits,
+including on login failure, its output remains visible until a fresh keypress
+(no Enter needed). Terminal modes and the workspace display are restored on
+exit and failure. Pre-launch errors use the normal host UI.
+
+The child has an independent database session. Host transactions, results,
+and editor state are preserved; host read-only, autocommit, and other session
+settings are not applied to SQL*Plus. Launching is allowed in read-only mode.
+The password file is reread each time, preserving spaces and removing only
+final CR/LF, as with normal host connection setup. This is not a transfer of
+the existing Oracle connection or its session state.
+
+This capability requires a POSIX terminal, `/dev/fd`, and an installed SQL*Plus
+client. Connection fields must be nonempty, contain no control characters or
+embedded double quotes, and produce a CONNECT line of at most 2400 UTF-8
+bytes (also subject to the platform pipe limit). Explicitly quoted usernames
+are supported. Unsupported values are rejected without displaying credentials.
+Older hosts can be detected with `getattr(context, "start_sqlplus", None)`;
+the maintained plugin reports an upgrade requirement when unavailable.
+
 ## Compatibility boundary
 
 API v1 supports command registration, immutable loaded-result snapshots,
 plugin-scoped string settings, host-managed export, and metadata-only current-
-schema code generation. It does not promise internal module names, status
+schema code generation, host-managed dependency walking, and SQL*Plus launching.
+It does not promise internal module names, status
 wording, curses layout, database/session objects, mutable grid state, event
 hooks, lifecycle callbacks, arbitrary shortcuts, arbitrary queries or jobs,
 workspace-local Python-file discovery, or hot reload.
 
-Authors should use feature checks only for their own optional dependencies and
-must not probe host internals to extend this surface. A future incompatible
+Authors may check their own optional dependencies and explicitly documented
+additive public capabilities; they must not probe host internals to extend this
+surface. A future incompatible
 contract requires a different `PLUGIN_API_VERSION`; factories and managed
 manifests with a nonmatching version are rejected instead of being loaded
 partially.