plsqlwks 0.1.9.3__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plsqlwks
-Version: 0.1.9.3
+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.3 → 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.3 → 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.

{plsqlwks-0.1.9.3 → plsqlwks-0.2.0}/doc/COMPATIBILITY.md

@@ -57,22 +57,42 @@ zone of `TIMESTAMP WITH TIME ZONE` and `TIMESTAMP WITH LOCAL TIME ZONE` values,
 and it truncates precision beyond Python microseconds. Returning the resulting
 naive datetime would falsely imply a lossless value.
 
-For that reason, non-null zoned timestamp cells are read-only and use these
-fail-safe display and export values:
+For ordinary `SELECT` and `WITH` queries, PLSQLWKS describes the result without
+executing it and formats zoned columns on Oracle before fetching them. The grid,
+cell viewer, clipboard, and exports receive the same readable strings:
+
+- `2026-01-17 10:11:12.123456789 GMT+05:45`
+- `2026-07-17 10:11:12 GMT+02:00 [EUROPE/PRAGUE]`
+
+Significant fractional digits are preserved through nanosecond precision;
+trailing zeroes are omitted. `TIMESTAMP WITH TIME ZONE` retains its stored
+numeric offset or named region, including the offset at that date.
+`TIMESTAMP WITH LOCAL TIME ZONE` follows `SESSIONTIMEZONE` captured when the
+query starts, including when later pages are fetched after a session-zone change.
+Original headings, bind values, ordering, row limits, and timestamp metadata
+are preserved. Zoned cells remain read-only; neighboring editable columns are
+unaffected. Plain `DATE` and `TIMESTAMP` behavior is unchanged.
+
+The projection is parsed before executing the user query, which executes once.
+Special forms such as `SELECT FOR UPDATE`, inline `WITH FUNCTION/PROCEDURE`, and
+results containing LONG, REF CURSOR, or object columns use the existing native
+fetch path. If Oracle cannot describe a bound expression without its values,
+or rejects the projection's syntax or types, the original query runs instead.
+Non-null zoned cells on this fallback path retain a warning
+and these fail-safe display/export values:
 
 - `<TIMESTAMP WITH TIME ZONE: lossless Thin-mode fetch unavailable; use TO_CHAR>`
 - `<TIMESTAMP WITH LOCAL TIME ZONE: lossless Thin-mode fetch unavailable; use TO_CHAR>`
 
-The result also carries a warning. Select a lossless companion string explicitly
-when exact data is required, for example:
+Named-zone values on that native fallback path can still raise Thin-mode
+`DPY-3022`. Select a lossless companion string explicitly for these query forms:
 
 ```sql
-to_char(zoned_timestamp, 'YYYY-MM-DD"T"HH24:MI:SS.FF9 TZH:TZM')
+to_char(zoned_timestamp, 'YYYY-MM-DD"T"HH24:MI:SS.FF9 TZH:TZM TZR')
 ```
 
 For a local-time-zone column, first cast it at the required precision to
 `TIMESTAMP(9) WITH TIME ZONE`; its rendered value follows `SESSIONTIMEZONE`.
-Named-zone timestamp fetches remain an explicit Thin-mode limitation.
 
 ### Experimental connection matrices
 
@@ -94,11 +114,10 @@ compulsory on protected pipelines and independently meeting the same ten-run,
 30-day evidence rule.
 
 The schema browser and metadata completion deliberately enumerate the current
-login schema. Qualified cross-schema SQL is covered by the DML-only and
-read-only profiles, but it does not add cross-schema objects to the browser.
-ROWID-backed grid editing and insertion also remain limited to one base table
-in the current schema. Exact quoted and Unicode table/column names are covered;
-qualified cross-schema results are viewable but not grid-editable.
+login schema. The mandatory matrix does not claim DML-only, read-only, or
+cross-schema UI behavior. ROWID-backed grid editing and insertion remain
+limited to one base table in the current schema. Exact quoted and Unicode
+table/column names are covered.
 
 ## Fail-closed safety gate
 
@@ -122,7 +141,7 @@ preflight performs all of these checks:
   assigned to each distinct account below; restricted schemas own no objects,
   every grant option is `NO`, and DBA,
   user-administration, `ANY`, unlimited-tablespace, and public mutation paths
-  are rejected;
+  on non-Oracle-maintained schemas are rejected;
 - on 26ai, both effective and directly received schema privileges are empty.
 - the developer's effective `CONNECT_TIME` and `IDLE_TIME` profile limits are
   both `UNLIMITED`, so they cannot terminate and roll back the guard session.
@@ -160,8 +179,8 @@ what rejects DML and DDL.
 
 When profile names share an Oracle account, the harness validates that account
 against the strongest assigned contract (`developer`, then DML-only, then
-read-only). Tests that require a weaker database privilege boundary are skipped
-for that aliased profile because one Oracle session user cannot simultaneously
+read-only). The live suite does not attempt a weaker database privilege boundary
+for an aliased profile because one Oracle session user cannot simultaneously
 have and lack the same privilege. Endpoint, identity, version, direct-grant,
 guard-token, and guard-lock checks remain active. A one-account run therefore
 provides functional compatibility coverage, but it does not claim independent
@@ -202,8 +221,7 @@ For an account assigned to multiple profiles, provision the strongest of its
 contracts in this order: developer, DML-only, read-only. In the common
 single-license setup, all three variables name `<DEV_USER>`, all three password
 file variables may name the same private file, and only the developer contract
-is provisioned. The restricted-profile enforcement tests are then reported as
-skipped rather than misrepresented as tested.
+is provisioned. The run does not claim restricted-profile enforcement coverage.
 
 The effective rows from `SESSION_PRIVS` must be exactly:
 
@@ -225,7 +243,9 @@ by distinct restricted accounts; no grant is made to the owner itself, and a
 shared DML/read-only account receives the stronger DML grant set once. The
 developer must have no outgoing column grants, no grant on the guard table, and
 no grant to `PUBLIC`. The preflight also rejects any effective public
-table/column mutation privilege visible to a profile.
+table/column mutation privilege visible to a profile on a non-Oracle-maintained
+schema. Oracle-supplied grants on owners reported by `ALL_USERS` with
+`ORACLE_MAINTAINED = 'Y'` are treated as part of the database baseline.
 
 Assign the developer a dedicated profile whose `CONNECT_TIME` and `IDLE_TIME`
 are both `UNLIMITED`; the preflight verifies the effective values through
@@ -264,6 +284,15 @@ grant select on sys.v_$sql_plan_statistics_all to <DEV_USER>;
 grant select on sys.v_$session to <DEV_USER>;
 ```
 
+Oracle grants `INHERIT PRIVILEGES` on a newly created user to `PUBLIC` by
+default. The matrix outgoing-grant contract intentionally rejects that path.
+As the provisioning DBA, run the following once for each distinct developer,
+DML-only, and read-only account (only once when profiles share an account):
+
+```sql
+revoke inherit privileges on user <PROFILE_USER> from public;
+```
+
 These are exact allowlists, not minimums. An additional direct system or object
 grant, an admin/grant option, or any received role makes preflight fail.
 

{plsqlwks-0.1.9.3 → plsqlwks-0.2.0}/doc/PLUGINS.md

@@ -159,6 +159,24 @@ 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.
 
+## SQL*Plus launcher package
+
+`sqlplus-0.1.0.plwgn` adds **Database -> Open SQL*Plus** through the public
+`PluginContext.start_sqlplus()` capability. The host supplies the connection
+credentials, suspends the terminal UI, and waits for a fresh keypress after
+SQL*Plus exits before restoring PLSQLWKS. SQL*Plus has its own session and
+transaction settings, including when launched from a read-only host. Install
+and configuration instructions are in the [catalog](PLUGIN_CATALOG.md#sqlplus-launcher).
+
+## Dependencies walker package
+
+`dependencies-walker-0.1.0.plwgn` adds **Database -> Dependencies walker** through
+the public `PluginContext.start_dependency_walk()` capability. The host owns
+the lazy forward/reverse tree, metadata queries, cancellation, and keyboard UI.
+The plugin does not receive a connection or import private UI/database modules.
+It needs no dependency extra. See the [catalog instructions](PLUGIN_CATALOG.md#dependencies-walker)
+for installation, controls, package grouping, and visibility limits.
+
 ## Maintained csv2oratab package
 
 The catalog's `csv2oratab-0.1.0.plwgn` package registers **Alt-O -> Data ->