J621/extras/powershell_greeting/README.md

# 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, `iterm` (aspect-preserving box) 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`. The default uses the `iterm` logo type with
  `preserveAspectRatio`, which never stretches. If something looks off, try
  `J621_LOGO_TYPE=kitty-direct`, `kitty`, or `sixel` (note: through ConPTY,
  plain `kitty` falls back to ASCII and `kitty-direct` stretches tall images).
- **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).