diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 686e5e7..aa9ab0e 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -1,10 +1,132 @@ -# Microsoft Open Source Code of Conduct +# Contributor Covenant Code of Conduct -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +## Our Pledge -Resources: +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. -- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) -- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) -- Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns -- Employees can reach out at [aka.ms/opensource/moderation-support](https://aka.ms/opensource/moderation-support) +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of + any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, + without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +**tig@kindel.com**. All complaints will be reviewed and investigated promptly +and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][mozilla coc]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][faq]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[mozilla coc]: https://github.com/mozilla/diversity +[faq]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/.github/SECURITY.md b/.github/SECURITY.md index f941d30..0b8b1cd 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -1,41 +1,40 @@ - +# Security Policy -## Security +The tui-cs community takes the security of PSTui seriously. Thank you for helping +keep PSTui and its users safe. -Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin) and [PowerShell](https://github.com/PowerShell). +## Supported versions -If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/security.md/definition), please report it to us as described below. +Security fixes are made against the latest published release of PSTui on the +[PowerShell Gallery](https://www.powershellgallery.com/packages/PSTui). Please +make sure you can reproduce an issue on the latest version before reporting it. -## Reporting Security Issues +## Reporting a vulnerability -**Please do not report security vulnerabilities through public GitHub issues.** +**Please do not report security vulnerabilities through public GitHub issues, +discussions, or pull requests.** -Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report). +Instead, report them privately using GitHub's +[private vulnerability reporting](https://github.com/tui-cs/PSTui/security/advisories/new) +(the **Security → Report a vulnerability** button on the repository). If you are +unable to use that, email the maintainer at **tig@kindel.com** with `PSTui +security` in the subject line. -If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/security.md/msrc/pgp). +Please include as much of the following as you can, to help us triage quickly: -You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). +- The type of issue and its impact (what an attacker could do). +- The affected version(s), and the file(s) / location in the source. +- Step-by-step instructions to reproduce, plus any required configuration. +- Proof-of-concept or exploit code, if you have it. -Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: +## What to expect - * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) - * Full paths of source file(s) related to the manifestation of the issue - * The location of the affected source code (tag/branch/commit or direct URL) - * Any special configuration required to reproduce the issue - * Step-by-step instructions to reproduce the issue - * Proof-of-concept or exploit code (if possible) - * Impact of the issue, including how an attacker might exploit the issue +- We aim to acknowledge new reports within a few days. +- We will keep you informed as we investigate and work on a fix. +- Once a fix is released, we are happy to credit you in the release notes unless + you prefer to remain anonymous. -This information will help us triage your report more quickly. - -If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/security.md/msrc/bounty) page for more details about our active programs. - -## Preferred Languages - -We prefer all communications to be in English. - -## Policy - -Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/security.md/cvd). - - +We follow the principle of +[Coordinated Vulnerability Disclosure](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure): +please give us a reasonable opportunity to release a fix before any public +disclosure. diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 173a813..349acf6 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -14,8 +14,9 @@ Gallery** (rather than a NativeAOT CLI shipped to NuGet/Homebrew/WinGet). ## Workflows ### `ci-test.yml` — Continuous Integration -Builds and tests on every push / PR to `main` (and merge queue) across -Windows, macOS, and Linux via `Invoke-Build Build, Test, Package`. +Builds and tests on every push / PR to `develop` and `main` (and merge queue) +across Windows, macOS, and Linux via `Invoke-Build Build, Test`. Packaging and +publishing are release-only activities and live in `release.yml`. ### `release.yml` — Build, Test, Version, Publish Triggered by: @@ -56,7 +57,6 @@ To move between phases, change these and merge to `main`: ## Status -This pipeline is **new and not yet exercised end-to-end** (see issue #5). Before -the first real release: add the `PSGALLERY_API_KEY` secret, reserve the `PSTui` -package id on the Gallery (issue #6), and confirm a `workflow_dispatch` dry run -is green. +The pipeline is **live and exercised end-to-end** (issues #5 and #6 closed). The +`PSGALLERY_API_KEY` secret is configured and PSTui is published to the PowerShell +Gallery — merging `develop` → `main` ships the next version automatically. diff --git a/PLAN.md b/PLAN.md deleted file mode 100644 index b4e668d..0000000 --- a/PLAN.md +++ /dev/null @@ -1,118 +0,0 @@ -# PSTui — Rebranding & Re-release Plan - -Re-releasing the PowerShell Console GUI tools — **`Out-ConsoleGridView` (`ocgv`)** -and **`Show-ObjectTree` (`shot`)** — under the **tui-cs** organization as -**PSTui** (*PowerShell TUI tools*), following Microsoft's decision to archive -`Microsoft.PowerShell.ConsoleGuiTools`. - -## 1. Background - -- **[ConsoleGuiTools#275](https://github.com/PowerShell/ConsoleGuiTools/issues/275)** — - Microsoft declared `Microsoft.PowerShell.ConsoleGuiTools` feature-complete at - **0.7.7** (its final release) and will **archive the repo**. The PowerShell - team committed to **pointing users at a community fork** if @tig stands one up. -- **[ConsoleGuiTools#267](https://github.com/PowerShell/ConsoleGuiTools/pull/267)** - ("Updates OCGV and SHOT to Terminal.Gui v2") — the modernization was *already - done and approved by @andyleejordan*, but never merged because MS sunset the - project. **This work is now landed on this branch** (originally - `tig/GraphicalTools:terminal_gui_v2`, mirrored as `tui-cs/pstui:tig-terminal_gui_v2`). - It includes: - - Terminal.Gui **v1 (1.17.1) → v2 (2.1.0)** rewrite of both cmdlets. - - **.NET 8 → .NET 10**; centralized package management (`Directory.Packages.props`). - - `ocgv` rebuilt on v2 `TableView` (streaming pipeline, regex filter, native - sortable headers); new params `-Driver`, `-FullScreen`, `-Search`, `-Focus`, - `-AllProperties`; removed `-UseNetDriver`. Default render is now **inline** - (use `-FullScreen` for the old alt-buffer behavior). - - `shot` rebuilt on v2 `TreeView` with `RegexTreeViewTextFilter`. - - The old `Out-ConsoleTableView` (octv) was **folded into `ocgv`**. - - **xUnit test suite**; removed dead/dangerous `Serializers.cs` - (`TypeNameHandling.All`); bumped to **1.0.0**. - -**Implication:** This is *not* a "rebrand on v1 now, migrate to v2 later" effort. -The v2 work exists and is review-clean. The job is to **rebrand on top of it.** - -## 2. Ecosystem alignment (tui-cs) - -- **Terminal.Gui** is at **v2** — instance-based `IRunnable` app model, no more - `Nstack`/`ustring` (uses `Rune`/`string`). -- **clet** — *"One binary. Every prompt. JSON out. Go home."* Verb-noun - commands, consistent JSON envelopes (`{"schemaVersion":1,"status":"ok",...}`), - Unix exit codes (0/1/2/130), NativeAOT, **for humans *and* AI agents**. -- **cli** — the tui-cs library for scriptable commands with agent - discoverability (`--opencli` manifest). - -PSTui should feel like a first-class member of this family. - -## 3. Decisions - -| Topic | Decision | -|-------|----------| -| Project / module / PSGallery id | **`PSTui`** (Microsoft retains the `Microsoft.PowerShell.ConsoleGuiTools` gallery id; we need a fresh one regardless) | -| Brand / tagline | *"PowerShell TUI tools, built on Terminal.Gui."* Retire **"Console GUI"** terminology from prose. | -| Code baseline | **PR #267** (Terminal.Gui v2, tests, 1.0.0) — already landed on this branch | -| Cmdlet names | **No renames.** Keep `Out-ConsoleGridView`/`ocgv` and `Show-ObjectTree`/`shot` exactly as in #267 — protects existing users' muscle memory and scripts | -| Licensing | MIT retained; rewrite `NOTICE.txt`, copyright → tui-cs / Tig Kindel | - -> The cmdlet *names* (`ocgv`, `shot`) are the stable contract for existing users -> and stay put. "Removing old-school terminology" applies to **branding and -> prose** ("Console GUI" → "TUI"), the **module name**, and **namespaces** — -> not to the cmdlets. - -## 4. Workstreams - -### A. v2 foundation — DONE -- PR #267 landed on `claude/powershell-tui-rebranding-543gas` - (Terminal.Gui 2.1.0, new window classes, test suite, module 1.0.0). -- [x] Confirm the test suite builds & passes in CI (needs .NET 10 SDK). - (tui-cs/PSTui#1 — CI green on windows/macos/ubuntu, 78 xUnit tests pass on .NET 10.) - -### B. De-Microsoft rebrand -- Rename module `Microsoft.PowerShell.ConsoleGuiTools` → **`PSTui`**: - `.psd1` (new **GUID**, `Author`/`CompanyName`/`Copyright`, `ProjectUri` → - `tui-cs/pstui`, `LicenseUri`; tags drop `gui.cs`, add `TUI`/`Terminal.Gui`). - `CmdletsToExport`/`AliasesToExport` stay `Out-ConsoleGridView`/`ocgv` and - `Show-ObjectTree`/`shot`. -- Rename namespaces/assemblies/projects: - `Microsoft.PowerShell.ConsoleGuiTools` → `PSTui`, - `Microsoft.PowerShell.OutGridView.Models` → `PSTui.Models` - (sheds the deprecated WinForms `Out-GridView` association). -- `*.props`: `Company`, `Copyright`, `RepositoryUrl`, `PackageLicenseUrl`. -- Rewrite **README** around "PowerShell TUI tools"; add a prominent - **"Migrating from Microsoft.PowerShell.ConsoleGuiTools"** section. -- Replace residual "Console GUI" terminology in docs with "TUI". - -### C. Packaging, CI & release -- New PSGallery package **`PSTui`** (decouple from the Microsoft OneBranch - pipeline; tui-cs GitHub Actions release flow). -- Decide signing/publishing path (PSGallery API key under tui-cs). -- First release **v1.0.0** (matches #267; signals the modern v2 base). - -### D. Transition & comms -- Coordinate with @andyleejordan so the archived ConsoleGuiTools repo's README - points at `tui-cs/pstui`. -- Add PSTui to the tui-cs org README ecosystem list. -- Migration note: `Install-Module PSTui`; `ocgv` and `shot` are unchanged. - -### E. Future (post-1.0, north star) -- Expose grid/tree pickers through the **cli** agent-discoverability layer so - `ocgv`/`shot` gain clet-style JSON-out + clean exit-code modes usable by AI - agents — same envelope contract as clet. - -## 5. Open items to confirm - -- **Target framework:** ✅ **Decided — `net10.0`** (PowerShell **7.6+**, set as - `PowerShellVersion` in the manifest). A binary module loads in-process, so the - TFM must match the host runtime. -- **JSON stack:** ✅ **Done — migrated to `System.Text.Json`** (`Newtonsoft.Json` - dropped; the lone `[JsonIgnore]` now from `System.Text.Json.Serialization`). _(issue #3)_ - -## 6. Sequenced checklist - -1. [x] Land PR #267 (v2 foundation) on the rebrand branch. -2. [x] Confirm tests build & pass (.NET 10). _(issue #1)_ -3. [x] De-Microsoft rebrand → module/namespaces/props/README (`PSTui`), - targeting `net10.0`/PS 7.6+; `ocgv` and `shot` names unchanged. _(issue #4)_ -4. [x] tui-cs CI/release pipeline; JSON-stack done _(issue #3)_, pipeline _(issue #5)_. -5. [x] Publish **PSTui 1.0.0** to PSGallery. _(issue #6 — live, `Install-Module PSTui`)_ -6. [ ] Coordinate archive pointer with @andyleejordan; update tui-cs org README. -7. [ ] (Post-1.0) clet/cli agent-discoverability alignment. diff --git a/README.md b/README.md index 870ae09..4f0f024 100644 --- a/README.md +++ b/README.md @@ -85,13 +85,13 @@ Install-Module PSTui old alternate-buffer behavior. * Objects **stream** into the table as they arrive from the pipeline. * Pressing Enter with no explicit selection returns the **focused** row. -* New parameters: `-Driver`, `-FullScreen`, `-Search`, `-Focus`, `-AllProperties`. +* New parameters: `-Driver`, `-FullScreen`, `-Search`, `-Focus`. * Removed: `-UseNetDriver` (replaced by `-Driver`). ## Features * [`Out-ConsoleGridView`](docs/PSTui/Out-ConsoleGridView.md) - Send objects to an interactive table view with column headers, horizontal scrolling, streaming, sorting, and native multi-selection. -* [`Show-ObjectTree`](docs/PSTui/Show-ObjectTree.md) - Send objects to a tree view window for interactive filtering and sorting. +* [`Show-ObjectTree`](docs/PSTui/Show-ObjectTree.md) - Send objects to a tree view window for interactive exploration and filtering. * [Graphical command history](#command-history-f7--shiftf7) - `F7`/`Shift+F7` browse and re-run command history (the [F7History](https://github.com/tui-cs/F7History) module, built in). * Cross-platform - Works on any platform that supports PowerShell 7.6+. @@ -188,7 +188,7 @@ killp note This example shows defining a function named `killp` that shows a grid view of all running processes and allows the user to select one to kill it. -The example uses the `-Filter` paramter to filter for all proceses with a name that includes `note` (thus highlighting `Notepad` if it were running. Selecting an item in the grid view and pressing `ENTER` will kill that process. +The example uses the `-Filter` parameter to filter for all processes with a name that includes `note` (thus highlighting `Notepad` if it were running). Selecting an item in the grid view and pressing `ENTER` will kill that process. ### Example 7: Output processes to a tree view diff --git a/demo.ps1 b/demo.ps1 index 9b17fd5..beea7ba 100644 --- a/demo.ps1 +++ b/demo.ps1 @@ -10,11 +10,11 @@ Get-Process | Select-Object -Property Name, WorkingSet, PeakWorkingSet | Sort-Ob function killp { Get-Process | Out-ConsoleGridView -OutputMode Single -Filter $args[0] | Stop-Process -Id {$_.Id} } killp # .Silent cls -# Example 3b: 'killp note' fitlers for "note" (e.g. notepad.exe) +# Example 3b: 'killp note' filters for "note" (e.g. notepad.exe) killp note # .Silent cls # Example 4: Navigate PowerShell command history (built in: just press F7 / Shift+F7) -Get-History | Sort-Object -Descending -Property Id -Unique | Select-Object CommandLine -ExpandProperty CommandLine | Out-ConsoleGridView -OutputMode Single -Filter $line -Title "Command Line History" +Get-History | Sort-Object -Descending -Property Id -Unique | Select-Object CommandLine -ExpandProperty CommandLine | Out-ConsoleGridView -OutputMode Single -Title "Command Line History" # .Silent cls -# Example 4: Use Show-ObjectTree to output processes to a tree view +# Example 5: Use Show-ObjectTree to output processes to a tree view Get-Process | Show-ObjectTree diff --git a/docs/PSTui/Disable-PSTuiHistoryKeyHandler.md b/docs/PSTui/Disable-PSTuiHistoryKeyHandler.md new file mode 100644 index 0000000..fa6ece8 --- /dev/null +++ b/docs/PSTui/Disable-PSTuiHistoryKeyHandler.md @@ -0,0 +1,59 @@ +--- +external help file: PSTui.dll-Help.xml +keywords: powershell,cmdlet +locale: en-us +Module Name: PSTui +ms.date: 06/27/2026 +schema: 2.0.0 +title: Disable-PSTuiHistoryKeyHandler +--- + +# Disable-PSTuiHistoryKeyHandler + +## SYNOPSIS + +Removes PSTui's `F7` / `Shift+F7` command-history key bindings. + +## SYNTAX + +```PowerShell +Disable-PSTuiHistoryKeyHandler [] +``` + +## DESCRIPTION + +Removes the `F7` and `Shift+F7` PSReadLine key handlers that PSTui registers on import. Use [Enable-PSTuiHistoryKeyHandler](Enable-PSTuiHistoryKeyHandler.md) to re-add them. If PSReadLine is not available, the command is a no-op. + +## EXAMPLES + +### Example 1: Remove the bindings for this session + +```PowerShell +Disable-PSTuiHistoryKeyHandler +``` + +Unbinds `F7` and `Shift+F7` for the current session. + +## PARAMETERS + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### None + +## NOTES + +* To opt out permanently, set `$PSTuiDisableHistoryKeyHandler = $true` or `$env:PSTUI_DISABLE_HISTORY_KEYS = 1` **before** importing PSTui, rather than calling this at runtime. + +## RELATED LINKS + +[Enable-PSTuiHistoryKeyHandler](Enable-PSTuiHistoryKeyHandler.md) + +[Show-PSTuiHistory](Show-PSTuiHistory.md) diff --git a/docs/PSTui/Enable-PSTuiHistoryKeyHandler.md b/docs/PSTui/Enable-PSTuiHistoryKeyHandler.md new file mode 100644 index 0000000..591b53e --- /dev/null +++ b/docs/PSTui/Enable-PSTuiHistoryKeyHandler.md @@ -0,0 +1,63 @@ +--- +external help file: PSTui.dll-Help.xml +keywords: powershell,cmdlet +locale: en-us +Module Name: PSTui +ms.date: 06/27/2026 +schema: 2.0.0 +title: Enable-PSTuiHistoryKeyHandler +--- + +# Enable-PSTuiHistoryKeyHandler + +## SYNOPSIS + +Binds `F7` / `Shift+F7` to PSTui's graphical command history. + +## SYNTAX + +```PowerShell +Enable-PSTuiHistoryKeyHandler [] +``` + +## DESCRIPTION + +`F7` shows the current session's history; `Shift+F7` shows global PSReadLine history. This command is called automatically when PSTui is imported (unless opted out), and is safe to call again to re-bind after [Disable-PSTuiHistoryKeyHandler](Disable-PSTuiHistoryKeyHandler.md). + +If PSReadLine is not available (for example, a non-interactive host), the command is a no-op and writes a verbose message. + +To opt out of the automatic binding on import, set either `$PSTuiDisableHistoryKeyHandler = $true` (a PowerShell variable) or `$env:PSTUI_DISABLE_HISTORY_KEYS = 1` (an environment variable) **before** importing PSTui. + +## EXAMPLES + +### Example 1: Re-enable the bindings + +```PowerShell +Enable-PSTuiHistoryKeyHandler +``` + +Re-binds `F7` and `Shift+F7` after they were removed with [Disable-PSTuiHistoryKeyHandler](Disable-PSTuiHistoryKeyHandler.md). + +## PARAMETERS + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### None + +## NOTES + +* The bindings only register on `Import-Module PSTui` — `Install-Module` alone does not bind the keys. Add `Import-Module PSTui` to your `$PROFILE` to get them in every session. + +## RELATED LINKS + +[Disable-PSTuiHistoryKeyHandler](Disable-PSTuiHistoryKeyHandler.md) + +[Show-PSTuiHistory](Show-PSTuiHistory.md) diff --git a/docs/PSTui/Out-ConsoleGridView.md b/docs/PSTui/Out-ConsoleGridView.md index b99f24a..a34925b 100644 --- a/docs/PSTui/Out-ConsoleGridView.md +++ b/docs/PSTui/Out-ConsoleGridView.md @@ -123,17 +123,20 @@ The processes that you select are passed to the **Export-Csv** command and writt By default, `-OutputMode` is `Multiple`, which lets you send multiple items down the pipeline. -### Example 8: Use F7 as "Show Command History" +### Example 8: Browse command history with F7 / Shift+F7 -Save See [this gist](https://gist.github.com/tig/cbbeab7f53efd73e329afd6d4b838191) as `F7History.ps1` and run `F7History.ps1` in your `$profile`. +PSTui binds `F7` and `Shift+F7` to a graphical command-history picker +automatically when the module is imported (the [F7History](https://github.com/tui-cs/F7History) +module, folded in). No setup beyond `Import-Module PSTui` is required — add that +line to your `$PROFILE` to get the bindings in every session. -Press `F7` to see the history for the current PowerShell instance +Press `F7` to see the history for the current PowerShell session, or `Shift+F7` +for history across all sessions (PSReadLine). Whatever you'd already typed at the +prompt is used as the initial filter, and the entry you select is inserted at the +prompt. -Press `Shift-F7` to see the history for all PowerShell instances. - -Whatever you select within `Out-ConsoleGridView` will be inserted on your command line. - -Whatever was typed on the command line prior to hitting `F7` or `Shift-F7` will be used as a filter. +The picker is also exposed as the `Show-PSTuiHistory` command (add `-Global` for +all-sessions history), so you can call it directly or bind it to a different key. ### Example 9: Search for a row without filtering diff --git a/docs/PSTui/Show-ObjectTree.md b/docs/PSTui/Show-ObjectTree.md index e0f0dfe..a5682e5 100644 --- a/docs/PSTui/Show-ObjectTree.md +++ b/docs/PSTui/Show-ObjectTree.md @@ -3,7 +3,7 @@ external help file: PSTui.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: PSTui -ms.date: 07/20/2023 +ms.date: 06/27/2026 schema: 2.0.0 title: Show-ObjectTree --- @@ -17,7 +17,7 @@ Sends output to an interactive tree in the same console window. ## SYNTAX ```PowerShell -Show-ObjectTree [-InputObject ] [-Title ] [-Filter ] [-MinUi] [-Driver ] [-FullScreen] [] +Show-ObjectTree [-InputObject ] [-Title ] [-Filter ] [-MinUI] [-Driver ] [-FullScreen] [] ``` ## DESCRIPTION @@ -26,7 +26,7 @@ The **Show-ObjectTree** cmdlet sends the output from a command to a tree view wi Use the Filter box at the top of the window to search the text in the tree including literals or multiple words. Use the `-Filter` parameter to pre-populate the Filter box. The filter uses regular expressions. -For instructions for using these features, type `Get-Help Show-ObjectTree -Full` and see How to Use the Tree View Window Features in the Notes section. +Navigate the tree with the arrow keys: Right expands a node (rows marked with `+`), Left collapses it. Press Esc to close the window. ## EXAMPLES @@ -108,7 +108,7 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -MinUi +### -MinUI If specified no title or status bar will be displayed in the **Show-ObjectTree** window. The filter will only be displayed if `-Filter` is specified. ```yaml @@ -176,8 +176,4 @@ You can send any object to this cmdlet. ## RELATED LINKS -[Out-File](Out-File.md) - -[Out-Printer](Out-Printer.md) - -[Out-String](Out-String.md) +[Out-ConsoleGridView](Out-ConsoleGridView.md) diff --git a/docs/PSTui/Show-PSTuiHistory.md b/docs/PSTui/Show-PSTuiHistory.md new file mode 100644 index 0000000..817e321 --- /dev/null +++ b/docs/PSTui/Show-PSTuiHistory.md @@ -0,0 +1,89 @@ +--- +external help file: PSTui.dll-Help.xml +keywords: powershell,cmdlet +locale: en-us +Module Name: PSTui +ms.date: 06/27/2026 +schema: 2.0.0 +title: Show-PSTuiHistory +--- + +# Show-PSTuiHistory + +## SYNOPSIS + +Shows PowerShell command history in `Out-ConsoleGridView` and inserts the selected command at the prompt. + +## SYNTAX + +```PowerShell +Show-PSTuiHistory [-Global] [] +``` + +## DESCRIPTION + +Backs the `F7` / `Shift+F7` command-history key handlers, and can be called or bound to other keys directly. The current prompt text is used as the initial filter; the selected command is inserted at the prompt. + +This command is exported (rather than module-private) so the PSReadLine key handlers, which run in the global session state, can resolve it. + +## EXAMPLES + +### Example 1: Show this session's history + +```PowerShell +Show-PSTuiHistory +``` + +Opens the current session's command history in `Out-ConsoleGridView`. Selecting an entry and pressing `ENTER` inserts it at the prompt. + +### Example 2: Bind it to a different key + +```PowerShell +Set-PSReadLineKeyHandler -Chord 'Ctrl+r' -ScriptBlock { Show-PSTuiHistory -Global } +``` + +Binds Ctrl+R to the all-sessions history picker. + +## PARAMETERS + +### -Global + +Show history from all PowerShell sessions (PSReadLine), de-duplicated, instead of only the current session. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### None + +This command updates the PSReadLine prompt buffer directly; it does not write to the pipeline. + +## NOTES + +* The bindings register on `Import-Module PSTui`. See [Enable-PSTuiHistoryKeyHandler](Enable-PSTuiHistoryKeyHandler.md) / [Disable-PSTuiHistoryKeyHandler](Disable-PSTuiHistoryKeyHandler.md) to toggle them at runtime. + +## RELATED LINKS + +[Enable-PSTuiHistoryKeyHandler](Enable-PSTuiHistoryKeyHandler.md) + +[Disable-PSTuiHistoryKeyHandler](Disable-PSTuiHistoryKeyHandler.md) + +[Out-ConsoleGridView](Out-ConsoleGridView.md)