extras: add PowerShell greeting port, Rust gm-switch and Windows installers

- powershell_greeting: PowerShell port of fish_greeting (fastfetch random logo, sixel/kitty-direct per terminal, logs, modes) - win-gm-switch: Rust port of gm-switch.cpp (cross-platform mode file, --status, Start Menu shortcuts installer) - install-windows.ps1 umbrella installer; README pointers
2026-09-30 09:34:01 -05:00
parent 9b431eb982
commit d2f857d3ee
12 changed files with 976 additions and 3 deletions
@@ -0,0 +1,121 @@
+# PowerShell greeting (J621 Windows port)
+
+Shows a random J621 library image as your shell greeting, using fastfetch.
+This is the Windows/PowerShell port of [`../fish_greeting/`](../fish_greeting/) -
+same API, same modes, same logs, adapted to PowerShell 5.1+ and Windows
+terminals.
+
+## What changed from the fish version
+
+| | fish | PowerShell (this port) |
+| --- | --- | --- |
+| Entry point | `fish_greeting` function | `Show-J621Greeting` (loaded from your profile) |
+| Endpoint | `GET /api/random/?fastfetch=1&rating=X` | same |
+| Config | `~/.config/j621Greeting/config.fish` | `%APPDATA%\j621Greeting\config.ps1` |
+| Mode file | `~/.config/fish/greeting_mode` | `%APPDATA%\j621Greeting\greeting_mode` (the file `gm-switch.exe` writes) |
+| JSON parsing | `jq` / `python3` / grep | `ConvertFrom-Json` (built-in) |
+| MIME detection | `file --mime-type` | PNG/JPEG/GIF magic bytes |
+| GIFs | `gifsicle` + `kitten icat` | none: static first frame in Windows Terminal, animated in WezTerm (its `kitty-direct` plays the GIF) |
+| fastfetch logo | `--logo-type kitty --logo ... --logo-width 35` | `sixel` in Windows Terminal, `kitty-direct` in WezTerm, no image elsewhere |
+| Logs | `~/.config/j621Logos/logs.log` | `%APPDATA%\j621Logos\logs.log` |
+
+## Install
+
+```powershell
+cd extras\powershell_greeting
+.\install.ps1
+```
+
+The installer copies `J621Greeting.ps1` into `%APPDATA%\j621Greeting\`, asks
+for your API origin (and an optional scoped token), writes
+`%APPDATA%\j621Greeting\config.ps1`, wires a marker block into your
+PowerShell profile (it replaces the previous plain-`fastfetch` hook), checks
+the tools it needs and probes the backend (`/health` plus a random roll). It
+exits non-zero when the backend cannot be reached.
+
+Non-interactive / re-install:
+
+```powershell
+.\install.ps1 -Url https://j621.example.ts.net -Token <api-token>
+.\install.ps1 -NoPrompt          # defaults, never asks
+.\install.ps1 -Force             # rewrite an existing config
+.\install.ps1 -NoProfilePatch    # do not touch your PowerShell profile
+.\install.ps1 -Uninstall         # remove the profile block + installed script
+```
+
+Test it manually any time with:
+
+```powershell
+Show-J621Greeting
+```
+
+Requirements: `fastfetch` and `curl.exe` (ships with Windows 10 1803+).
+Image logos need Windows Terminal 1.22+ (sixel) or WezTerm with kitty
+graphics enabled; other terminals fall back to a plain fastfetch.
+
+## No token? That is fine
+
+The greeting is meant to run **without** a token: it then behaves like a
+guest of your instance - unsigned image links and only items that are
+visible to guests. Adding a token to the config unlocks signed links and
+items that are hidden from guests. The recommended value is a **scoped
+greeting token**: open the app, go to *Account -> Shell tokens* (or `/tokens`),
+create one and copy the `j621r_...` key - it only works with `/api/random/`,
+so it is safe to keep in the config file.
+
+## Configuration
+
+`%APPDATA%\j621Greeting\config.ps1` is read on every run (environment
+variables already set in your session win over it):
+
+```powershell
+if (-not $env:J621_BASE) { $env:J621_BASE = 'https://j621.rainbow-herring.ts.net' }  # API origin
+if (-not $env:J621_WEB)  { $env:J621_WEB  = 'https://j621.example.ts.net' }          # link origin (split deploys)
+if (-not $env:J621_TOKEN) { $env:J621_TOKEN = '<api token>' }                        # signed URLs + hidden items
+if (-not $env:J621_FASTFETCH_CONFIG) { $env:J621_FASTFETCH_CONFIG = 'jake' }         # fastfetch config name
+```
+
+Extra escapes (all optional):
+
+- `J621_LOGO_TYPE` - force a fastfetch logo type (`sixel`, `kitty-direct`, ...)
+- `J621_ALWAYS_FETCH=1` - fetch even in terminals without image support (prints the link, ASCII logo)
+- `J621_LOGO_WIDTH` - logo width in columns (default 35)
+- `J621_MODE_FILE` - mode file override (shared with `gm-switch`)
+
+## Rating filters
+
+| `greeting_mode` | Rating requested | Label |
+| --- | --- | --- |
+| `0` | `e` | NSFW |
+| `1` | `s` | SFW |
+| `2` (default) | `q` | Questionable |
+
+The mode file is `%APPDATA%\j621Greeting\greeting_mode`. Use
+[`../win-gm-switch/`](../win-gm-switch/) (or its Start Menu shortcuts) to
+switch, or just edit the file.
+
+## Troubleshooting
+
+- **No image logo in Windows Terminal**: WT 1.22+ is required for sixel;
+  update with `winget upgrade Microsoft.WindowsTerminal`.
+- **WezTerm**: kitty graphics must be on - `config.enable_kitty_graphics = true`
+  in `~/.wezterm.lua`. If the default looks wrong, try
+  `J621_LOGO_TYPE=kitty`, `sixel`, or `iterm`.
+- **VS Code / other terminals**: no image protocol, so the greeting prints a
+  plain fastfetch on purpose (no fetch delay). `J621_ALWAYS_FETCH=1` still
+  fetches and prints the link.
+- `No logo (No image matches those filters.)` - the library has no images
+  for that rating; try another mode or add files.
+- `No logo (API error)` - check `J621_BASE` and that the deployment is up
+  (`https://<host>/health`).
+- `No logo (download failed)` - the signed URL expired (they last 24 h) or
+  the item was deleted between the two requests; just run it again.
+- **The greeting is slow** - the API and image fetch have `--max-time`
+  guards; a slow tailnet link is usually the cause.
+- Log file: `%APPDATA%\j621Logos\logs.log` (only the last 1000 lines are kept).
+
+## gm-switch
+
+The Rust [`../win-gm-switch/`](../win-gm-switch/) tool writes the same mode
+file, and on Linux it can replace the old C++ `gm-switch` (it writes
+`~/.config/fish/greeting_mode` there, the same file the fish greeting reads).