@ai-ecoverse/slicc-capture 1.3.1 → 1.3.3

package/README.md

@@ -31,19 +31,13 @@ On Windows, in PowerShell:
 irm https://get.sliccy.ai/slicc-capture.ps1 | iex
 ```
 
-The installers are `install.sh` and `install.ps1`, attached to every [GitHub release](https://github.com/ai-ecoverse/slicc-capture/releases) with the package tarball (`slicc-capture-<version>.tgz`) and `SHA256SUMS`, which lists the tarball, `install.sh` and `install.ps1`, in the style of [mcpcat's](https://github.com/ai-ecoverse/mcpcat) `install.sh`. `@semantic-release/npm` packs the tarball into `release/` (`tarballDir`), and `@semantic-release/exec` runs `scripts/assets.mjs`, which renames it and writes `SHA256SUMS`. They check the tarball against `SHA256SUMS`, unpack it into a versioned directory (`${XDG_DATA_HOME:-~/.local/share}/slicc-capture/<version>`, or `%LOCALAPPDATA%\slicc-capture\<version>` on Windows), and write a `sccapture` launcher that runs it with that Node. Without get.sliccy.ai, the same installer comes straight from the release:
+Without get.sliccy.ai, the same installer comes straight from the release:
 
 ```sh
 curl -fsSL https://github.com/ai-ecoverse/slicc-capture/releases/latest/download/install.sh | sh
 ```
 
-| `install.sh` | `install.ps1` | |
-| --- | --- | --- |
-| `--version VERSION` | `-Version VERSION` | the release to install (default: the latest) |
-| `--dir DIR` | `-Dir DIR` | where the launcher goes (default: `~/.local/bin`; on Windows `%LOCALAPPDATA%\slicc-capture\bin`, added to the user's `PATH`) |
-| `--help` | `-Help` | print the usage and exit 0 |
-
-Options reach `install.sh` after `sh -s --`, for example `curl -fsSL https://get.sliccy.ai/slicc-capture | sh -s -- --version 1.2.0 --dir ~/bin`, and `install.ps1` through a script block: `& ([scriptblock]::Create((irm https://get.sliccy.ai/slicc-capture.ps1))) -Version 1.2.0`. An unknown option, or `--dir` or `--version` without a value, prints `install.sh: <problem>` and the usage to stderr and exits 2; there are no environment overrides for the options. A failure is `install.sh: <problem>` (`install.ps1: <problem>`) on stderr and exit 1. `SLICC_INSTALL_BASE_URL` replaces the release download directory (by default `https://github.com/ai-ecoverse/slicc-capture/releases/latest/download`, or `…/download/v<version>` with `--version`), and `SLICC_NODE_DIST_BASE` replaces `https://nodejs.org/dist`. The installed command must answer `--version` with the version it was installed as (or the older `sccapture <version>`). On Windows the launcher is `sccapture.ps1`, next to a `sccapture.cmd` for `cmd.exe`; both only start `node.exe` with the entry script and the arguments, and `sccapture` itself never runs `cmd.exe`.
+Options reach `install.sh` after `sh -s --`, for example `curl -fsSL https://get.sliccy.ai/slicc-capture | sh -s -- --version 1.2.0 --dir ~/bin`, and `install.ps1` through a script block: `& ([scriptblock]::Create((irm https://get.sliccy.ai/slicc-capture.ps1))) -Version 1.2.0`. On Windows the launchers are `sccapture.ps1` and `sccapture.cmd`, and the bin directory is added to the user's `PATH`. [The installer](#the-installer) has the details.
 
 The get.sliccy.ai entries for `slicc-capture` and `slicc-capture.ps1` are added once the first release is out.
 
@@ -93,7 +87,7 @@ Errors, on stderr, from slicc 6 where they still apply:
 | `screencapture: interrupted` (`SIGHUP`, `SIGINT` or `SIGTERM` during the request: the command stops the reader, so the page's `signal` aborts with `interrupted`, removes its temporary files and writes no file) | `128 + n` |
 | `screencapture: failed to write file: <file>: <message>` | 1 |
 | `screencapture: failed to create a temporary directory in <dir>` (before the request: `mktemp -d` failed in `$TMPDIR`, else `/tmp`; nothing is sent or written) | 1 |
-| `screencapture: failed to create a temporary file in <dir>` (`-v` without a file, after the capture: `mktemp` failed; the image is dropped and nothing is written) | 1 |
+| `screencapture: failed to create a temporary file in <dir>` (`-v` without a file, after the capture: `mktemp` failed; no file is written and no marker is printed; with `-c`, the clipboard copy has already been made) | 1 |
 | `screencapture: failed to copy to clipboard: this page does not copy images (no clipboard.write)` (`ENOTSUP`: no page answers `clipboard.write`) | 1 |
 | `screencapture: failed to copy to clipboard: <message>` (the page's message, else the errno's text) | 1 |
 | `screencapture: /dev/embedder not available (needs slicc-kernel >= 1.153.0)` (a kernel that runs the commands without the device) | 1 |
@@ -224,6 +218,8 @@ Under Wayland, `grim` needs a compositor with wlr-screencopy (sway, Hyprland and
 
 `sccapture` runs `powershell.exe` (else `pwsh.exe`) with `-NoProfile -NonInteractive -STA -EncodedCommand` and a fixed script; the file name and the option values reach it as data, in `SCCAPTURE_*` environment variables, never as script. (PowerShell reads a script on stdin line by line, as if typed, so a multi-line block in it can stop at the first blank line; `-EncodedCommand` is what slicc-clipboard uses.) The process is made per-monitor DPI-aware first (system DPI-aware before Windows 10 1703), so a scaled display is captured at its real resolution, even when the monitors' scales differ. It copies the virtual screen (every monitor), or the screen `-m`/`-D` names, or the `-R` rectangle of that (its `x,y` from the top left of the virtual screen, or of the screen `-m`/`-D` names), with `Graphics.CopyFromScreen`, draws the cursor for `-C`, and saves with the `-t` format's `ImageFormat`, or `Clipboard.SetImage` for `-c`.
 
+In PowerShell, quote the rectangle: `sccapture -R '0,0,800,600' shot.png`. Unquoted, `0,0,800,600` is an array, which PowerShell passes to any program, `sccapture.ps1` included, as four arguments. In `cmd.exe` no quotes are needed. Run from PowerShell 7, `sccapture` captures through Windows PowerShell with pwsh's `PSModulePath` inherited; CI checks that this works.
+
 ### In SLICC, the SLICC commands win
 
 The package has both `bin` and `slicc.commands`, and both name `sccapture`. As with slicc-clipboard, the kernel ignores a package's `bin` entry when the same package declares that name in `slicc.commands`, and bios removes the `$PNPM_HOME/bin` link pnpm makes for it, so the Node script, which SLICC has no Node to run, never shadows the SLICC command.
@@ -232,12 +228,63 @@ The package has both `bin` and `slicc.commands`, and both name `sccapture`. As w
 
 Every host command takes `--upgrade`. It runs the latest release's installer (`install.sh`, or `install.ps1` on Windows) with `--dir` set to the directory the command is installed in, so the new version replaces the old one in place, then prints `<cmd>: <old> → <new>` (for example `sccapture: 1.2.0 → 1.3.0`), or `<cmd>: already up to date (<version>)`, to stdout and exits 0. If the installer fails, its stderr is passed through and the command exits 1. A command installed with npm prints `npm install -g @ai-ecoverse/slicc-capture@latest` to run instead, and exits 0. In SLICC, `--upgrade` prints `pnpm add -g @ai-ecoverse/slicc-capture@latest` to run, and exits 0; it installs nothing itself. `--upgrade` takes no other arguments.
 
-For slicc-capture, the commands are `sccapture` on a host and `screencapture` and `sccapture` in SLICC.
-
-The launcher the installer writes sets `SCCAPTURE_INSTALL_DIR` to its own directory; that is how `sccapture` knows the installer put it there (it removes the variable before it starts anything else), and without it `sccapture` counts as installed with npm. The installer is downloaded with Node's `fetch` from `https://github.com/ai-ecoverse/slicc-capture/releases/latest/download/` and run as `sh install.sh --dir DIR`, or `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File install.ps1 -Dir DIR` (else `pwsh.exe`); its stderr is passed through, and the line it prints, `sccapture <version> installed to <launcher>`, names the new version. Without `sh` (or PowerShell) it prints `sccapture: no shell found to run install.sh (tried sh)`, and a failed download `sccapture: could not download <url>: <reason>`, and exits 1. `SLICC_INSTALL_BASE_URL`, when set, replaces that release URL for `--upgrade` and for the installers' own downloads.
+For slicc-capture, the commands are `sccapture` on a host and `screencapture` and `sccapture` in SLICC. [How `--upgrade` uses it](#how---upgrade-uses-it) has the details. A download that fails prints `sccapture: could not download <url>: <reason>`, one that takes more than 60 seconds `sccapture: download timed out`, and with no `sh` (or PowerShell) it prints `sccapture: no shell found to run install.sh (tried sh)`; each exits 1.
 
 `--version` prints the version (`0.1.0`) to stdout and exits 0, on a host and in SLICC; the installers run the installed command with it and check it reports the version they installed. It takes no other arguments either.
 
+## The installer
+
+This section is the installer contract that slicc-open, slicc-capture, slicc-audio and slicc-man share ([slicc-open#7](https://github.com/ai-ecoverse/slicc-open/issues/7)). [slicc-open](https://github.com/ai-ecoverse/slicc-open)'s `install.sh`, `install.ps1`, `scripts/assets.mjs` and `host/upgrade.mjs` are the reference implementation, and slicc-capture's are copies of them with the names swapped. The names below are written as placeholders; for slicc-capture:
+
+| placeholder | slicc-capture |
+| --- | --- |
+| `<pkg>` | `slicc-capture` (the npm package is `@ai-ecoverse/<pkg>`, the repo `ai-ecoverse/<pkg>`) |
+| `<cmd>` | `sccapture`, each of the package's host commands (its `bin`) |
+| `<CMD>` | `SCCAPTURE`, `<cmd>` in upper case with `-` as `_` |
+
+### Release assets
+
+semantic-release's `@semantic-release/npm` packs the package into `release/` (`tarballDir`). `@semantic-release/exec` then runs `node scripts/assets.mjs release <version>`, which refuses (exit 1, leaving `release/` as it was, npm's tarball name included) when the tarball's `package.json` has no `bin` or lacks a file a `bin` entry names, and otherwise renames the tarball to `<pkg>-<version>.tgz`, copies `install.sh` and `install.ps1` next to it, and writes `SHA256SUMS`: one `<sha256>  <name>` line each for the tarball, `install.sh` and `install.ps1`, in that order. `@semantic-release/github` attaches all four files to the release. `ci.yml` needs no release step of its own.
+
+### Options and exit codes
+
+| `install.sh` | `install.ps1` | |
+| --- | --- | --- |
+| `--version VERSION` (or `--version=VERSION`; a leading `v` is dropped) | `-Version VERSION` | the release to install (default: the latest) |
+| `--dir DIR` (or `--dir=DIR`) | `-Dir DIR` | where the launchers go (default: `~/.local/bin`; on Windows `%LOCALAPPDATA%\<pkg>\bin`) |
+| `--help` (or `-h`) | `-Help` | print the usage to stdout and exit 0 |
+
+Only the flags select anything: no environment variable stands in for `--version` or `--dir`. `install.sh` handles its options (`--help` and the usage errors included) before it works out any directory, so they work without `HOME`. `HOME` is needed only for the defaults: without it, and without both `--dir` and `XDG_DATA_HOME`, `install.sh` exits 1 with `install.sh: HOME is not set; give --dir and set XDG_DATA_HOME`. `install.sh` exits **0** when it installed, **1** when something failed (a download, a checksum, an archive that doesn't unpack, no Node and no way to get one), with `install.sh: <what>` on stderr, and **2** for an unknown option or a missing value, with the usage on stderr. `install.ps1` exits 0 or 1 the same way when it is run as a file, and its parameters are PowerShell's own, so an unknown one is PowerShell's error. Run through `irm … | iex` or a script block, it prints the error and returns instead of calling `exit`, so it never closes the user's PowerShell. It sets `$PSNativeCommandUseErrorActionPreference = $false` in its own scope, so a caller's `$true` (pwsh 7.4 and later) can't turn the exit code of `node`, `tar` or `npm` into an error that stops the install. It runs `node --version`, `tar` and `npm` with `$ErrorActionPreference = 'Continue'` in a child scope, because Windows PowerShell 5.1 turns each line a native command writes to a redirected stderr into an error, and under `'Stop'` the first one would end the install before its `install.ps1:` message.
+
+### Node
+
+The launchers run the package with Node 24 or later. The installer uses the first `node` on `PATH` when it is new enough, otherwise one it downloaded before, into `<data>/node`. Failing both, it downloads the newest LTS release of 24 or later (or the newest release, when no LTS qualifies) from `index.json`. That download is `node-<version>-<os>-<arch>.tar.gz` (`darwin` or `linux`, `x64` or `arm64`), or `node-<version>-win-<arch>.zip` on Windows, checked against that release's `SHASUMS256.txt`. An archive that doesn't unpack exits 1 with `install.sh: could not unpack node-<version>-<os>-<arch>.tar.gz` (or `install.ps1: could not unpack node-<version>-win-<arch>.zip`), and leaves neither its temporary directory nor a partial `<data>/node` behind. `.tar.gz` is used because `xz` isn't on every minimal Linux. On musl Linux, where nodejs.org has no build, the installer says to install Node with the package manager and exits 1.
+
+### Downloads
+
+| variable | default | |
+| --- | --- | --- |
+| `SLICC_INSTALL_BASE_URL` | `https://github.com/ai-ecoverse/<pkg>/releases/latest/download`, or `…/releases/download/v<version>` with `--version` | the directory holding the release assets (`SHA256SUMS`, `<pkg>-<version>.tgz`, `install.sh`, `install.ps1`) |
+| `SLICC_NODE_DIST_BASE` | `https://nodejs.org/dist` | where `index.json` and `v<version>/SHASUMS256.txt` and the Node archives are |
+
+`install.sh` fetches with `curl`, else `wget` (`curl` also reads the `file://` URLs the tests use), and checks checksums with `sha256sum`, else `shasum -a 256`. `install.ps1` uses `Invoke-WebRequest` and `Get-FileHash`. Without `--version`, the tarball is the `<pkg>-<version>.tgz` named in `SHA256SUMS`, so the version comes from the release itself. A tarball whose checksum doesn't match is refused before anything is unpacked.
+
+### Files
+
+The tarball is unpacked (with `tar`, `%SystemRoot%\System32\tar.exe` on Windows) into a temporary directory next to the versioned data directory `<data>/<version>`. A tarball that doesn't unpack exits 1 with `install.sh: could not unpack <pkg>-<version>.tgz` (or `install.ps1: could not unpack <pkg>-<version>.tgz`) and removes the partial directory. When its `package.json` has a non-empty `dependencies` or `optionalDependencies`, the installer removes `devDependencies` from that copy of `package.json` (npm would still resolve them against the registry, `--omit=dev` or not), then runs `npm install --omit=dev --ignore-scripts --no-audit --no-fund` there. It uses the npm that comes with the Node it picked, run by that Node (`<node dir>/../lib/node_modules/npm`, or `node_modules\npm` next to `node.exe`; `install.sh` falls back to `npm` on `PATH`). npm's output goes to stderr. Without such dependencies the step is skipped, so it needs neither npm nor the network. A failed `npm install`, or a missing npm, exits 1 and removes the partial directory. Only then does the directory replace `<data>/<version>`, so a failed install never leaves a broken version behind. `<data>` is `${XDG_DATA_HOME:-~/.local/share}/<pkg>`, or `%LOCALAPPDATA%\<pkg>` on Windows. Other versions stay where they are, and there is no `current` link. Each launcher names its version's entry script, `<data>/<version>/host/<cmd>.mjs`, and the Node it was installed with, by absolute path.
+
+| platform | launchers in `DIR` | what they do |
+| --- | --- | --- |
+| macOS, Linux | `<cmd>`, a POSIX sh script | sets and exports `<CMD>_INSTALL_DIR='<DIR>'`, exports `NODE_USE_ENV_PROXY=1` unless it is already set, then `exec '<node>' '<entry>' "$@"`; every path is single-quoted, so no path is ever evaluated |
+| Windows | `<cmd>.ps1` (UTF-8 with a BOM) | saves the caller's `$env:<CMD>_INSTALL_DIR` and sets it, sets `$env:NODE_USE_ENV_PROXY = '1'` when it is unset, runs `& '<node.exe>' '<entry>' @sccaptureArgs` in `try`, restores the old `<CMD>_INSTALL_DIR` in `finally` (or removes it when it was unset) and removes a `NODE_USE_ENV_PROXY` it set, then exits with node's exit code. A `.ps1` runs inside the caller's PowerShell session, and this keeps the variable from leaking into that session. `@sccaptureArgs` is `@args` with each array argument (`a,b`) flattened into separate arguments, as PowerShell passes them to a program, and each argument as text. When PowerShell passes arguments to programs the legacy way, which drops empty arguments and doesn't escape `"` (Windows PowerShell 5.1 whatever `$PSNativeCommandArgumentPassing` says, `$PSNativeCommandArgumentPassing = 'Legacy'`, or pwsh before 7.3 without the variable; pwsh 7.3 and later without it pass the standard way), then each `"` becomes `\"` (doubling the backslashes before it), an empty argument becomes `""`, and on Windows PowerShell an argument with whitespace gets its trailing backslashes doubled, so `node.exe` gets the arguments it was given. Since PowerShell reads an unquoted `a,b` as an array, `sccapture -R 0,0,800,600 shot.png` reaches `sccapture` as four arguments, so quote any argument with a comma in it (`sccapture -R '0,0,800,600' shot.png`). It also sets `$PSNativeCommandUseErrorActionPreference = $false` and `$ErrorActionPreference = 'Continue'` in its own scope, so neither a caller's `$true` (pwsh 7.4 and later) nor, on Windows PowerShell 5.1, a caller's `'Stop'` with stderr redirected can turn node's exit code or its stderr into an error |
+| Windows | `<cmd>.cmd` (UTF-8, code page 65001 while it runs) | sets `<CMD>_INSTALL_DIR` and, when it is undefined, `NODE_USE_ENV_PROXY=1` (both local to the `.cmd` through `setlocal`), then runs `"<node.exe>" "<entry>" %* & call :done %%ERRORLEVEL%% & call exit /b %%ERRORLEVEL%%` as one line, so a `)` in an argument can't end anything early, and a launcher that `--upgrade` rewrites mid-run is never read again; `:done` restores the code page and returns node's status, and `call exit /b` exits with it explicitly, because a bare `exit /b` leaves the exit code of `cmd /c` (which PowerShell and every other program uses to run a `.cmd`) at 0. Arguments reach it through cmd's own parsing: `%`, `^`, `&` and `)` are safe inside `"…"`, and a `\"` inside one counts as a quote to cmd, so the quotes in an argument have to pair up |
+
+Both Windows launchers only start `node.exe` with the entry script and the arguments, and `<cmd>` itself never runs `cmd.exe`. `NODE_USE_ENV_PROXY=1` makes Node's `fetch` (and so `--upgrade`) honour `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` the way curl does. On Windows the installer adds `DIR` to the user's `PATH` when it isn't there already, and says so, along with the PowerShell command that removes it again. When `Get-ExecutionPolicy` is `Restricted`, `AllSigned` or `Undefined`, PowerShell won't run `<cmd>.ps1`, so `install.ps1` prints to stderr that `<cmd>` needs `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`, or `<cmd>.cmd` instead; it never changes the policy itself. elsewhere it prints the `export PATH=…` line to add when `DIR` isn't on `PATH`. After writing the launchers, the installer runs each command's `--version` and requires the version it installed, either alone (`1.2.0`) or in the older `<cmd> 1.2.0` form, so that a `--version` naming an older release still installs. Then it prints `<cmd> <version> installed to <launcher>` to stdout for each command.
+
+### How `--upgrade` uses it
+
+`<CMD>_INSTALL_DIR` is how a command knows the installer put it there. When it is set, `--upgrade` uses Node's `fetch` to download `install.sh` (or `install.ps1` on Windows) from `SLICC_INSTALL_BASE_URL`, or the latest release without it, into a temporary directory. The download has 60 seconds (`AbortSignal.timeout`); after that it prints `<cmd>: download timed out` to stderr and exits 1. It runs `sh install.sh --dir <CMD>_INSTALL_DIR`, or `powershell.exe` (else `pwsh.exe`) `-NoProfile -NonInteractive -ExecutionPolicy Bypass -File install.ps1 -Dir <CMD>_INSTALL_DIR` without `PSModulePath` in its environment, with the installer's stderr passed through. (Run from PowerShell 7, the command inherits pwsh's `PSModulePath`, and Windows PowerShell started with it loses `Get-FileHash`.) The new version is the one in the installer's `<cmd> <version> installed to` line. A download that fails (an HTTP error status prints `<cmd>: could not download <url>: HTTP <status>`, and its body is cancelled, not left open), an installer that exits non-zero or doesn't print that line, or a missing `sh` or PowerShell makes `--upgrade` exit 1. Without `<CMD>_INSTALL_DIR`, the command counts as installed with npm. Commands remove `<CMD>_INSTALL_DIR` from the environment of everything they start.
+
 ## Development
 
 ```sh
@@ -249,11 +296,12 @@ npm run test:unit
 
 - `npm install` also installs the git hooks into this worktree's own `node_modules/` through slicc-shared-web's `slicc-install-hooks` and the committed `.githooks/`.
 - `npm run lint`: Biome, the no-comment check and the other [slicc-shared-web](https://github.com/ai-ecoverse/slicc-shared-web) checks, then `shellcheck -s sh` and `dash -n` on `install.sh` and `bin/*`.
-- `npm test`: the integration tests in `test/integration/`. `commands.test.mjs` runs `screencapture` and `sccapture` on `@ai-ecoverse/slicc-kernel/node` (the version `engines.slicc-kernel` names, pinned) with wasm-bash and wasm-coreutils, and a fake `capture.screen` and `clipboard.write` handler (`createNodeKernel({ requests })`): every option's header, the bytes written unchanged, the errnos and their messages, `-c`, `-v`, and slicc-kernel 1.152.2, which has no `/dev/embedder`. `test/integration/repo.test.mjs` checks the workflow, the release config, the pinned devDependencies and what `npm pack` ships. The host tests run `host/` against fake `screencapture`, `grim`, `slurp`, `gnome-screenshot`, `import`, `scrot`, `wl-copy`, `xclip`, `xdg-open`, `powershell.exe` and `pwsh.exe` on a temporary `PATH`, and `--upgrade` against installers served from a local HTTP server, with the platform forced, so each branch is checked on any machine; only CI touches a real screen. `install.test.mjs` runs `install.sh` on a tarball packed from the tree, with the Node on `PATH` and with a Node download from a fake `nodejs.org`, and `--upgrade` against a release served from a local directory; `install.ps1` is checked statically, and run when `pwsh` is on `PATH`.
+- `npm test`: the integration tests in `test/integration/`. `commands.test.mjs` runs `screencapture` and `sccapture` on `@ai-ecoverse/slicc-kernel/node` (the newest kernel, pinned exactly) with wasm-bash and wasm-coreutils, and a fake `capture.screen` and `clipboard.write` handler (`createNodeKernel({ requests })`): every option's header, the bytes written unchanged, the errnos and their messages, `-c`, `-v`, and slicc-kernel 1.152.2, which has no `/dev/embedder`. `test/integration/repo.test.mjs` checks the workflow, the release config, the pinned devDependencies and what `npm pack` ships. The host tests run `host/` against fake `screencapture`, `grim`, `slurp`, `gnome-screenshot`, `import`, `scrot`, `wl-copy`, `xclip`, `xdg-open`, `powershell.exe` and `pwsh.exe` on a temporary `PATH`, and `--upgrade` against installers served from a local HTTP server (a 500 whose body never ends has to be closed within 2 seconds), with the platform forced, so each branch is checked on any machine; only CI touches a real screen. `install.test.mjs` runs `install.sh` on a tarball packed from the tree, with the Node on `PATH` and with a Node download from a fake `nodejs.org`, a truncated tarball and Node archive whose checksums match, and `--upgrade` against a release served from a local directory; `install.ps1` is checked statically, and run when `pwsh` is on `PATH`, also with `$PSNativeCommandUseErrorActionPreference = $true` and `$ErrorActionPreference = 'Stop'` (an install, a failed npm and the launcher's exit 2), and on a truncated tarball. `scripts/assets.mjs` has to leave a rejected tarball under npm's name and take one already renamed. On Windows the host tests fake a program with a copy of a small `.exe` that `csc.exe` builds from C# (`fake-windows.mjs`), which runs the fake's script with Node, so the Windows branches run for real; the macOS and Linux branches and the `sh`-based `--upgrade` tests are skipped there.
+- `npm run test:windows`: on Windows, the host tests and `windows.test.mjs`, which installs a tarball packed from the tree with `install.ps1` under both Windows PowerShell and `pwsh`, from a local HTTP server into a temporary `-Dir` named `my 'bin' (x86) & 100%`; runs `sccapture.cmd` and `sccapture.ps1` with `--version`, `--help` and a usage error; checks the arguments `node` gets through both launchers (full of `)`, `&`, `%`, `^`, spaces, quotes, trailing backslashes and empty ones, in pwsh's `Standard` and `Legacy` argument passing and with `$PSNativeCommandArgumentPassing` removed, plus a comma list `a,'b c'`, through copies of the launchers that run a script printing its argv), and through them the `SCCAPTURE_*` data a fake `powershell.exe` gets for a file named `a ) & ^ 'f' b.png`; checks that neither launcher leaks `SCCAPTURE_INSTALL_DIR` or `NODE_USE_ENV_PROXY`, that the `.cmd` restores the code page, and that the printed PATH undo works; captures the real screen to a PNG through `sccapture.cmd` (also with pwsh's `PSModulePath`) and through `sccapture.ps1` from Windows PowerShell and from `pwsh`, checked by its magic bytes and its size; installs again with `$PSNativeCommandUseErrorActionPreference = $true` and `$ErrorActionPreference = 'Stop'`, where `sccapture.ps1 --nope` exits 2 and leaves both preferences as they were, and a truncated tarball, with `2>&1`, exits 1 with `could not unpack`; upgrades in place with `--upgrade` from `sccapture.cmd`, `sccapture.ps1` and `pwsh`; and downloads Node as a `.zip` from a fake `nodejs.org`, after refusing a truncated one. CI runs it on `windows-latest` (`windows-test` in `ci.yml`); elsewhere `windows.test.mjs` is skipped.
 - `page.test.mjs` registers [the page module](#the-page-module) through `createNodeKernel({ requests })`, with a fake `display` and fake `ImageCapture`, `OffscreenCanvas` and `<video>` injected through `create`, and runs the real `screencapture`: the constraints, the crop, the type and quality, the delay and its progress, an interrupt in the picker and in the delay, **Stop sharing**, the picker's timeout, the errnos and their messages end to end, and that every track is stopped. `browser.test.mjs` runs the module in Chrome, through slicc-shared-web's harness, with a `display` that returns a canvas's `captureStream()`: PNG, JPEG and WebP, the crop, the `<video>` fallback, an abort and the stopped track. It runs on CI only, and is skipped without `CI`.
 - `npm run test:unit`: the unit tests in the gitignored `test/unit/`, with coverage in `coverage/unit/lcov.info`. `npm run test:sh` runs the `test/unit/*.sh.mjs` ones, which trace `bin/` with `set -x` in the node kernel, and writes `coverage/sh/lcov.info`. The pre-commit hook wants 100% coverage of the changed lines of both, and runs `diff-cover` through `uvx`, so install [uv](https://docs.astral.sh/uv/) once.
 
-CI is `.github/workflows/ci.yml`, the only workflow, which runs [slicc-shared-web's pipeline](https://github.com/ai-ecoverse/slicc-shared-web#pipeline) at the devDependency's version: `npm run lint`, then `npm test`, then on a pull request the Claude and Codex reviews. The merge queue requires `ci / integration` and `ci / review`. On a push to `main`, semantic-release releases and publishes to npm through trusted publishing, with provenance from `ci.yml`, and attaches the installers.
+CI is `.github/workflows/ci.yml`, the only workflow, which runs [slicc-shared-web's pipeline](https://github.com/ai-ecoverse/slicc-shared-web#pipeline) at the devDependency's version: `npm run lint`, then `npm test`, and on a pull request and in the merge queue `npm run test:windows` on `windows-latest`, then on a pull request the Claude and Codex reviews. The merge queue requires `ci / integration` and `ci / review`. On a push to `main`, semantic-release releases and publishes to npm through trusted publishing, with provenance from `ci.yml`, and attaches the installers.
 
 ## License
 

package/host/capture.mjs

@@ -18,6 +18,7 @@ export async function run({
   fds = [0, 1, 2],
   entry = fileURLToPath(new URL('sccapture.mjs', import.meta.url)),
   wait = (seconds) => setTimeout(seconds * 1000),
+  timeout = 60000,
 } = {}) {
   const os = names[platform] ? platform : 'linux';
   const parsed = parse(argv);
@@ -34,7 +35,8 @@ export async function run({
       say(fds[2], `sccapture: ${parsed.special[0]}: takes no other arguments\n${usage}`);
       return 2;
     }
-    if (parsed.special[0] === '--upgrade') return upgrade({ entry, env, platform: os, fds });
+    if (parsed.special[0] === '--upgrade')
+      return upgrade({ entry, env, platform: os, fds, timeout });
     const pkg = JSON.parse(readFileSync(join(dirname(dirname(entry)), 'package.json'), 'utf8'));
     say(fds[1], `${pkg.version}\n`);
     return 0;

package/host/upgrade.mjs

@@ -15,13 +15,17 @@ function version(entry) {
   return JSON.parse(readFileSync(join(dirname(dirname(entry)), 'package.json'), 'utf8')).version;
 }
 
-async function download(url) {
+async function download(url, timeout) {
   try {
-    const response = await fetch(url, { redirect: 'follow' });
-    if (!response.ok) return { error: `HTTP ${response.status}` };
+    const response = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(timeout) });
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => {});
+      return { error: `could not download ${url}: HTTP ${response.status}` };
+    }
     return { text: await response.text() };
   } catch (error) {
-    return { error: error.cause?.message ?? error.message };
+    if (error.name === 'TimeoutError') return { error: 'download timed out' };
+    return { error: `could not download ${url}: ${error.cause?.message ?? error.message}` };
   }
 }
 
@@ -64,7 +68,7 @@ function wait(path, args, { env, stderr }) {
   });
 }
 
-export async function upgrade({ entry, env, platform, fds }) {
+export async function upgrade({ entry, env, platform, fds, timeout }) {
   const dir = env.SCCAPTURE_INSTALL_DIR;
   if (!dir) {
     say(fds[1], 'npm install -g @ai-ecoverse/slicc-capture@latest\n');
@@ -72,8 +76,8 @@ export async function upgrade({ entry, env, platform, fds }) {
   }
   const name = platform === 'win32' ? 'install.ps1' : 'install.sh';
   const url = `${(env.SLICC_INSTALL_BASE_URL || latest).replace(/\/+$/, '')}/${name}`;
-  const fetched = await download(url);
-  if (fetched.error) return fail(fds, `could not download ${url}: ${fetched.error}`);
+  const fetched = await download(url, timeout);
+  if (fetched.error) return fail(fds, fetched.error);
   const scratch = mkdtempSync(join(tmpdir(), 'sccapture-upgrade-'));
   try {
     const path = join(scratch, name);
@@ -85,6 +89,11 @@ export async function upgrade({ entry, env, platform, fds }) {
     }
     const child = { ...env };
     delete child.SCCAPTURE_INSTALL_DIR;
+    if (platform === 'win32') {
+      for (const key of Object.keys(child)) {
+        if (key.toUpperCase() === 'PSMODULEPATH') delete child[key];
+      }
+    }
     const result = await wait(run.tool.path, run.args, { env: child, stderr: fds[2] });
     if (result.error) return fail(fds, `${run.tool.file}: ${result.error.message}`);
     if (result.code !== 0) return 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-capture",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "screencapture for SLICC, and sccapture for SLICC and any host",
   "type": "module",
   "license": "Apache-2.0",
@@ -53,6 +53,7 @@
     "lint": "slicc-lint && shellcheck -s sh -e SC1091 install.sh bin/* && for f in install.sh bin/*; do dash -n \"$f\" || exit 1; done",
     "format": "biome check --write .",
     "test": "node --test --test-timeout=120000 test/integration/*.test.mjs",
+    "test:windows": "node --test --test-concurrency=1 --test-timeout=600000 test/integration/host.test.mjs test/integration/windows.test.mjs",
     "test:unit": "mcr -c node_modules/@ai-ecoverse/slicc-shared-web/mcr.config.mjs node --test 'test/unit/**/*.test.mjs'",
     "test:sh": "node scripts/cover.mjs",
     "build": "npm pack --dry-run",
@@ -61,8 +62,8 @@
     "release": "semantic-release"
   },
   "devDependencies": {
-    "@ai-ecoverse/slicc-cdp": "1.40.0",
-    "@ai-ecoverse/slicc-kernel": "1.153.0",
+    "@ai-ecoverse/slicc-cdp": "1.41.1",
+    "@ai-ecoverse/slicc-kernel": "1.157.1",
     "@ai-ecoverse/slicc-shared-web": "2.12.0",
     "@ai-ecoverse/wasm-bash": "5.3.0-23",
     "@ai-ecoverse/wasm-coreutils": "9.12.0-15",