winTerm v0.3 Shell Experience

.github/actions/spelling/allow/allow.txt

@@ -12,12 +12,14 @@ commandlines
 consvc
 copyable
 dcs
+diskpart
 deselection
 diffing
 Dimidium
 downsides
 Emacspeak
 Fitt
+FNF
 flac
 FTCS
 gantt
@@ -45,6 +47,7 @@ notwrapped
 NTMTo
 overlined
 perlw
+PNF
 postmodern
 Powerline
 ptys

.github/workflows/winterm-full-build.yml

@@ -32,6 +32,10 @@ jobs:
         shell: pwsh
         run: .\scripts\winterm\test.ps1 -Suite Smoke -Configuration ${{ matrix.configuration }} -Platform x64
 
+      - name: Test Shell Experience assets
+        shell: pwsh
+        run: .\scripts\winterm\test-shell-integration.ps1 -Shell All
+
       - name: Build x64
         shell: pwsh
         run: .\scripts\winterm\build.ps1 -Configuration ${{ matrix.configuration }} -Platform x64 -IncludeTests

.github/workflows/winterm-validation.yml

@@ -29,3 +29,13 @@ jobs:
       - name: Verify winTerm identity, scripts, and profile foundations
         shell: powershell
         run: .\scripts\winterm\test.ps1 -Suite Smoke
+
+      - name: Validate Shell Experience assets and safety boundaries
+        shell: powershell
+        run: |
+          .\scripts\winterm\package-shell-assets.ps1
+          .\scripts\winterm\test-paste-protection.ps1
+
+      - name: Test PowerShell and Command Prompt integration
+        shell: powershell
+        run: .\scripts\winterm\test-shell-integration.ps1 -Shell All

README.md

@@ -1,16 +1,21 @@
 # winTerm
 
+[![CI](https://github.com/HelloThisWorld/winTerm/actions/workflows/winterm-validation.yml/badge.svg)](https://github.com/HelloThisWorld/winTerm/actions/workflows/winterm-validation.yml)
+[![License](https://img.shields.io/github/license/HelloThisWorld/winTerm)](LICENSE)
+
 winTerm is an independent open-source terminal application based on Microsoft Windows Terminal.
 
 winTerm is not affiliated with or endorsed by Microsoft.
 
-winTerm v0.1 is a foundation release. It keeps the mature Microsoft Terminal engine and adds an independent package identity, application-data boundary, user-visible branding, original placeholder artwork, reproducible wrappers, validation, CI, and an upstream synchronization workflow.
+winTerm v0.3 is a development release for Shell Experience foundations. It keeps the mature Microsoft Terminal engine and adds an independent package identity, application-data boundary, user-visible branding, original placeholder artwork, reproducible wrappers, validation, CI, an upstream synchronization workflow, Appearance source foundations, and packaged PowerShell/CMD shell-integration assets.
 
-## v0.1 scope
+## Current development scope
 
 The foundation preserves upstream tabs, panes, multiple windows, command palette, settings UI, keyboard shortcuts, clipboard, search, scrollback, ANSI color, Unicode, CJK, emoji fallback, and font-dependent Powerline rendering. It uses the upstream profile generators for PowerShell 7, Windows PowerShell 5.1, Command Prompt, and installed WSL distributions.
 
-It does not add command translation, completion engines, bundled shells, themes or fonts, renderer changes, extended session restoration, workspaces, docking, AI features, or remote process persistence.
+v0.3 adds a conservative local-shell integration layer: a PowerShell 7/Windows PowerShell 5.1 module, CMD initialization assets, OSC 9;9 and OSC 133 marks reused from upstream, Safe `ll`, `la`, `which`, `touch`, and `open` mappings, a Windows API helper for CMD, diagnostics, and a non-persisting paste-risk analyser.
+
+It does not add a full GNU compatibility layer, bundled GNU utilities or Clink, global PowerShell profile changes, CMD AutoRun changes, renderer changes, extended session restoration, workspaces, docking, AI features, cloud history, remote persistence, or command/clipboard telemetry.
 
 ## Prerequisites
 
@@ -29,6 +34,7 @@ Run these commands from a PowerShell 7 prompt:
 ```powershell
 .\scripts\winterm\build.ps1 -Configuration Debug -Platform x64
 .\scripts\winterm\test.ps1 -Suite Relevant -Configuration Debug -Platform x64
+.\scripts\winterm\test-shell-integration.ps1 -Shell All
 .\scripts\winterm\build.ps1 -Configuration Release -Platform x64
 .\scripts\winterm\package.ps1 -Platform x64
 ```
@@ -53,19 +59,32 @@ winTerm does not bundle PowerShell, WSL, or a Linux distribution.
 ## Current limitations
 
 - This checkout has passed source-level smoke validation, but the local environment used for the v0.1 work did not contain PowerShell 7, Visual Studio/MSBuild, or Windows SDK 10.0.22621.0. No local binary or MSIX was produced here.
+- The current local environment has Windows PowerShell 5.1 and CMD, but not PowerShell 7, Visual Studio/MSBuild, or the required SDK. Its execution policy also blocks script execution, so runtime module, build, package, launch, UI, clipboard, and rendering acceptance remain open.
+- v0.2 Appearance remains source-level only: compilation, package payload, launch, Settings UI, Theme Gallery, font loading, and manual rendering have not been verified. Those facts are not treated as v0.3 passes.
+- v0.3 packages the shell module, CMD assets, and helper source/project, but automatic profile launcher injection, Shell Experience settings UI, right-click behavior, paste confirmation UI, and built-app validation remain tracked acceptance work.
 - Installation, launch, shell execution, tabs, panes, input, and rendering still require manual verification on a correctly provisioned Windows 11 x64 machine.
 - The manifest publisher `CN=winTerm Development` is a development placeholder and must be replaced together with the signing certificate for a public release.
 - `winterm.exe` is the packaged execution alias. A `winterm:` URI protocol is intentionally not registered in v0.1 because the upstream application has no matching URI activation handler to reuse safely.
 - ARM64 is reserved by the wrappers but has not been validated for v0.1.
 
 The evidence and outstanding checks are tracked in [v0.1 acceptance](docs/v0.1-acceptance.md).
 
+The current baseline and v0.3 evidence are tracked in [v0.2 acceptance](docs/v0.2-acceptance.md) and [v0.3 acceptance](docs/v0.3-acceptance.md).
+
 ## Architecture and maintenance
 
 - [Architecture and ownership](docs/architecture.md)
 - [Brand and package identity](docs/branding.md)
 - [Upstream synchronization](docs/upstream-sync.md)
 - [Release process](docs/release-process.md)
+- [Shell Experience architecture](docs/shell-experience-architecture.md)
+- [Shell protocol](docs/shell-protocol.md)
+- [PowerShell integration](docs/powershell-integration.md)
+- [Command Prompt integration](docs/cmd-integration.md)
+- [Linux command compatibility](docs/linux-compatibility.md)
+- [Completion](docs/completion.md)
+- [Clipboard and paste protection](docs/clipboard-and-paste-protection.md)
+- [Shell diagnostics](docs/shell-diagnostics.md)
 
 The source baseline is Microsoft Terminal `release-1.25` at commit `1cea42d433253d95c4487a3037db48197b5e72f4`. The `upstream` remote points to `https://github.com/microsoft/terminal.git`.
 

docs/branding.md

@@ -10,7 +10,7 @@
 | Execution alias | `winterm.exe` |
 | Forbidden alias | `wt.exe` |
 | Development publisher | `CN=winTerm Development` |
-| Package version | `0.2.0.0` |
+| Package version | `0.3.0.0` |
 | Release status | `0.2.0-dev` until v0.2 acceptance is complete |
 | Package description | `Independent open-source terminal based on Microsoft Windows Terminal` |
 

docs/clipboard-and-paste-protection.md

@@ -0,0 +1,9 @@
+# Clipboard and paste protection
+
+The v0.3 source foundation contains a pure `PasteRiskAnalyzer`. It examines only the paste candidate in memory and returns decision data: line count, character count, final newline, unexpected control characters, command separators, and a small set of suspicious patterns. It does not modify text, save it, send it over the network, or execute it.
+
+The intended default confirmation triggers are multiple non-empty lines, a final newline, configured large text, unexpected control characters, multiple command separators, and suspicious destructive patterns. Detection is advisory: it can have false positives and false negatives and must never claim to recognize every harmful command.
+
+The pending terminal-control UI will offer Paste, Paste without final newline, Copy to editor or clipboard, and Cancel. A preview must be truncated safely and must not expose a complete large or secret-containing paste. Cancel must send no input.
+
+Right-click behavior remains an application integration acceptance item: selected text should copy and clear selection, no selection should paste, Shift+right-click should open the context menu, and terminal mouse-reporting mode must take precedence for full-screen programs. The analyser is designed to be invoked before bracketed-paste wrapping so the exact clipboard text stays unchanged.

docs/cmd-integration.md

@@ -0,0 +1,15 @@
+# Command Prompt integration
+
+The package contains `ShellAssets\cmd\winterm-init.cmd`. A profile may explicitly launch it with:
+
+```cmd
+cmd.exe /K "call \"<package-path>\ShellAssets\cmd\winterm-init.cmd\""
+```
+
+Initialization is process-local and idempotent. It sets `WINTERM_SESSION_ID`, `WINTERM_INTEGRATION_VERSION`, and a Safe compatibility default when those variables are absent. It does not require elevation, modify the AutoRun registry value, or write a global setting.
+
+The script wraps the existing `PROMPT` template with inherited OSC 9;9 and OSC 133 marks. CMD has no safe pre-execution hook, so it relies on the inherited `autoMarkPrompts` behavior for the command-executed transition and cannot claim PowerShell-equivalent exit-code reporting or completion.
+
+`winterm-doskey.cmd` adds `ll`, `la`, `clear`, `pwd`, `which`, `cat`, `ls`, `touch`, and `open` only when no same-named DOSKEY macro and no same-named `.exe` already exists. It does not overwrite user macros. `touch` and `open` use `winterm-shim.exe`, which accepts Unicode arguments and uses Windows APIs rather than calling PowerShell or composing `cmd /c` strings.
+
+The helper supports `touch <path...>`, `open <target>`, `version`, and `doctor`. It returns `0` on success, `1` on a general error, `2` for invalid arguments, `3` for a missing target, `4` for access denied, and `5` for an unsupported operation.

docs/completion.md

@@ -0,0 +1,7 @@
+# Shell completion
+
+PowerShell retains its native command, parameter, and path completion. The Safe `ll`, `touch`, and `open` functions use normal path parameters, so they receive the same relative-path, quoted-path, directory, and path-with-space completion behavior as other PowerShell commands. `which` registers a command-name completer only when winTerm owns the function.
+
+If PSReadLine is loaded, diagnostics reports it as available. winTerm does not set PSReadLine key bindings, edit mode, prediction source, history behavior, or any global option. If PSReadLine is unavailable, the module still loads and basic compatibility commands remain usable.
+
+CMD keeps its native Tab path completion. DOSKEY does not provide a PowerShell-class completion protocol, and winTerm does not bundle or inject Clink. `winterm-shim.exe` supplies normal command-line help for its supported operations.

docs/linux-compatibility.md

@@ -0,0 +1,17 @@
+# Linux and macOS command compatibility
+
+winTerm v0.3 is not a Bash translator or GNU utility bundle. It offers a small, shell-aware Safe mode for local PowerShell and CMD sessions only. WSL, Git Bash, SSH, and other Unix-like profiles should default to `Off`, because those shells already provide their own command semantics.
+
+| Command | PowerShell Safe mode | CMD Safe mode | Notes |
+| --- | --- | --- | --- |
+| `ll`, `la` | `Get-ChildItem -Force` | `dir /a` | `-a` and `--all` accepted in PowerShell. Other GNU flags fail clearly. |
+| `which name` | Friendly `Get-Command` result | `where` | Reports name, command type, and source/path in PowerShell. |
+| `touch path...` | Create or update `LastWriteTime` | `winterm-shim.exe touch` | Does not create missing parent directories or truncate content. |
+| `open target` | `Invoke-Item` for existing files or HTTP(S) URLs | `winterm-shim.exe open` | Uses Windows file/URL associations; no download occurs. |
+| `clear`, `cls`, `pwd`, `ls`, `cat`, `history` | Native behavior retained | Safe DOSKEY mapping where appropriate | No PowerShell native alias is overwritten. |
+
+The precedence rule is: an explicit user command, a native shell command or real executable, then a winTerm mapping, then normal command-not-found behavior. CMD checks existing DOSKEY macros and `.exe` files before adding a mapping. PowerShell does not export a mapping when a command already exists and also defers to a real application found later.
+
+The following are intentionally not translated: `rm`, `rm -rf`, `sudo`, `chmod`, `chown`, `grep`, `sed`, `awk`, `find`, `xargs`, arbitrary `tar` flags, shell redirection, command substitution, Bash variables, loops, and conditionals. A missing command keeps the normal shell error; winTerm does not generate a destructive alternative.
+
+`Off` disables winTerm mappings. `Safe` is the default. `Extended` is an experimental label for future explicitly-reviewed additions; it currently behaves like Safe and does not promise broader compatibility.

docs/powershell-integration.md

@@ -0,0 +1,29 @@
+# PowerShell integration
+
+The packaged module is `ShellAssets\powershell\winTerm.Shell\winTerm.Shell.psd1`, version `0.3.0`. It supports PowerShell 7 and Windows PowerShell 5.1 with the same syntax.
+
+An explicit winTerm profile launcher must set these process-local variables before importing the module:
+
+```powershell
+$env:WINTERM_SESSION_ID = '<opaque-session-id>'
+$env:WINTERM_INTEGRATION_VERSION = '1'
+Import-Module '<package-path>\ShellAssets\powershell\winTerm.Shell\winTerm.Shell.psd1'
+```
+
+The module does not add this block to `$PROFILE`. A launcher must preserve normal PowerShell execution policy; the module neither uses nor recommends `-ExecutionPolicy Bypass`. If policy prevents importing a module, PowerShell must still launch and diagnostics should report the failure and recommend a user-reviewed policy or installation remedy.
+
+## Prompt and marks
+
+On an eligible session, the module captures the current `prompt` function, sends prompt/CWD marks around its output, and calls the original script block. A second import detects its own wrapper instead of nesting it. Removing `winTerm.Shell` restores the captured prompt when the wrapper is still active. This preserves common profile customizations, including prompt frameworks loaded before the module.
+
+The module emits `OSC 133;A`, `OSC 9;9`, `OSC 133;B`, and then `OSC 133;D;<exit>` on the next prompt. The inherited `autoMarkPrompts` behavior supplies the command-executed transition. Command duration is intentionally not guessed from prompt idle time.
+
+## Compatibility and completion
+
+Compatibility mode resolves in this order: session override, `WINTERM_PROFILE_COMPATIBILITY_MODE`, `WINTERM_COMPATIBILITY_MODE`, then `Safe`. `Off` disables winTerm compatibility functions; `Extended` is labelled experimental and currently provides only the Safe command set.
+
+The module never exports a compatibility function over an existing user command. Each function additionally defers to a real application with the same name. Native PowerShell commands and aliases such as `cls`, `pwd`, `ls`, `cat`, `clear`, and `history` are not replaced.
+
+Path parameters use PowerShell's native completion. `which` adds a command completer only when winTerm owns that function. PSReadLine is detected but its key bindings, edit mode, prediction source, and option values are not modified.
+
+`Get-WinTermShellDiagnostics` reports the shell version, activation state, protocol, marker status, prompt wrapper, completion provider, PSReadLine status, compatibility mode, and a redacted failure category. It does not expose a full current path, command history, environment, or terminal output.

docs/release-process.md

@@ -15,7 +15,7 @@ Run source validation first:
 
 ## 2. Set release identity
 
-For a local development package, the v0.2 manifest uses version `0.2.0.0` and publisher `CN=winTerm Development`.
+For a local development package, the v0.3 manifest uses version `0.3.0.0` and publisher `CN=winTerm Development`.
 
 For a public release:
 

docs/shell-diagnostics.md

@@ -0,0 +1,15 @@
+# Shell integration diagnostics
+
+PowerShell exposes `Get-WinTermShellDiagnostics` and `Test-WinTermShellIntegration`. They report:
+
+- shell type and version;
+- integration and protocol versions;
+- session marker and prompt wrapper state;
+- current-directory and command-mark providers;
+- PSReadLine and completion availability;
+- current compatibility mode; and
+- a concise last integration failure category.
+
+Diagnostics intentionally omit command history, command text, arguments, clipboard data, terminal output, environment dumps, tokens, passwords, and full user paths. CMD diagnostics are limited to its process markers, available helper, prompt configuration, and DOSKEY conflicts.
+
+An integration failure must leave the shell usable. The usual resolution is to verify that the package shell assets exist, launch an explicit profile that sets the session marker, and import the installed module under the user's existing execution policy. Diagnostics must not write a profile or registry entry to repair an installation.

docs/shell-experience-architecture.md

@@ -0,0 +1,20 @@
+# Shell Experience architecture
+
+winTerm keeps command interpretation at the shell boundary. It does not inspect keystrokes to replace text, infer a prompt from rendered cells, or translate input inside SSH, WSL, Vim, Python, or other interactive applications.
+
+```text
+winTerm profile with explicit session marker
+    -> PowerShell module or CMD initialization asset
+        -> inherited OSC 9;9 and OSC 133 handling
+            -> upstream command marks, navigation, and working-directory state
+```
+
+The PowerShell module activates its prompt integration only when `WINTERM_SESSION_ID` is present and the host is an interactive ConsoleHost with unredirected input and output. It stores a captured prompt script block only for the current process and restores it when removed. No `$PROFILE`, registry AutoRun value, or execution policy is changed.
+
+`ShellSessionMetadata` is an in-memory, per-session model with a session ID, profile ID, shell type, capabilities, current-directory kind, command state, last exit code, duration, and health. It deliberately excludes command history, terminal output, environment dumps, clipboard data, passwords, and tokens. Remote and WSL directories are tagged separately from trusted local paths.
+
+The paste analyser is also pure and in-memory. It reports reasons such as multiline text, a final newline, text size, control characters, command separators, and suspicious patterns. It never changes text, records clipboard content, blocks all text containing a word, or executes a command. UI confirmation and terminal-control wiring remain acceptance items until a built application can be exercised.
+
+## Upstream boundaries
+
+The v0.3 foundation reuses the inherited TerminalCore parser and command-mark navigation. It does not modify ConPTY, the VT parser, text buffer, renderer core, Unicode width engine, input protocol parser, or OpenConsole internals. The new source under `src/winterm` is limited to diagnostic/session models and paste-risk analysis.