npm - @ai-ecoverse/slicc-capture - Versions diffs - 1.0.0 → 1.2.0 - Mend

@ai-ecoverse/slicc-capture 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -13,13 +13,13 @@ screencapture -T 3 -R 0,0,800,600 -t jpg crop.jpg
 ## Install
-In SLICC, the package declares `screencapture` and `sccapture` in `slicc.commands`, so installing it puts both in `/usr/bin`:
+In SLICC, the package declares `screencapture` and `sccapture` in `slicc.commands` (POSIX `sh` scripts in `bin/`), so installing it puts both in `/usr/bin`. They need slicc-kernel 1.153.0 or later, for [`/dev/embedder`](#the-request) (`engines.slicc-kernel` is `>=1.153.0`; an older kernel refuses them with exit 126 and `<cmd>: @ai-ecoverse/slicc-capture@<version> needs slicc-kernel >=1.153.0; this kernel is <version>`):
 ```sh
 pnpm add -g @ai-ecoverse/slicc-capture
 ```
-On macOS and Linux:
+On a host, the installer puts `sccapture` in `~/.local/bin`, with Node 24 or later, which it downloads (`node-<version>-<os>-<arch>.tar.gz`, or the `.zip` on Windows, checked against nodejs.org's `SHASUMS256.txt`) when none is on `PATH`:
 ```sh
 curl -fsSL https://get.sliccy.ai/slicc-capture | sh
@@ -31,24 +31,30 @@ On Windows, in PowerShell:
 irm https://get.sliccy.ai/slicc-capture.ps1 | iex
 ```
-Or, on any machine with Node 24 or later:
+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:
 ```sh
-npm install -g @ai-ecoverse/slicc-capture
+curl -fsSL https://github.com/ai-ecoverse/slicc-capture/releases/latest/download/install.sh | sh
 ```
-or without installing, `npx -p @ai-ecoverse/slicc-capture sccapture shot.png`.
+| `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 |
-### The installers
+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`.
-Each release attaches `install.sh` and `install.ps1` next to the package tarball, `slicc-capture-<version>.tgz`, and a `SHA256SUMS` that lists all three. The PR that adds the installers also adds them, the tarball and `SHA256SUMS` to `@semantic-release/github`'s `assets` in `.releaserc.json`, with a test in `test/integration/repo.test.mjs`, so no release ships without them. get.sliccy.ai serves the latest release's installers. Both work like mcpcat's `install.sh`:
+The get.sliccy.ai entries for `slicc-capture` and `slicc-capture.ps1` are added once the first release is out.
-- **Options:** `--version <version>` installs that release instead of the latest; `--dir <dir>` puts the launcher there instead of the default; `--help` prints the usage and exits 0. An unknown option prints `slicc-capture: unknown option: <arg>` to stderr and exits 1. The environment variables `VERSION` and `INSTALL_DIR` do the same as the options. Through a pipe, `sh -s -- --dir ~/bin` passes options to `install.sh`, and `& ([scriptblock]::Create((irm https://get.sliccy.ai/slicc-capture.ps1))) --dir C:\tools` to `install.ps1`.
-- **Node 24 or later:** the `node` on `PATH` if it is new enough, else the one the installer downloaded before; else it downloads the current Node LTS from nodejs.org, checks it against that release's `SHASUMS256.txt`, and keeps it in the data directory. On musl Linux, where nodejs.org has no build, it says to install Node with the package manager and exits 1.
-- **Where it goes:** the tarball is checked against `SHA256SUMS`, unpacked into `<data>/<version>`, and `<data>/current` points at it. `<data>` is `${XDG_DATA_HOME:-~/.local/share}/slicc-capture` on macOS and Linux, `%LOCALAPPDATA%\slicc-capture` on Windows. The launcher, `sccapture` (`sccapture.cmd` on Windows), goes into `~/.local/bin` (`%LOCALAPPDATA%\slicc-capture\bin` on Windows) and runs that Node on `<data>/<version>/host/sccapture.mjs`, so the launcher keeps working when the `node` on `PATH` changes.
-- **Output:** `sccapture <version> installed to <launcher>`, and, when the directory isn't on `PATH`, the line that adds it. Any failure (no `curl` or `wget`, a checksum mismatch, an unsupported OS or architecture) is one line on stderr and exit 1; on an unsupported OS it names `npm install -g @ai-ecoverse/slicc-capture` instead.
+With npm, on a machine with Node 24 or later:
-The get.sliccy.ai entries for `slicc-capture` and `slicc-capture.ps1` are added once the first release is out.
+```sh
+npm install -g @ai-ecoverse/slicc-capture
+sccapture shot.png
+```
+or without installing, `npx -p @ai-ecoverse/slicc-capture sccapture shot.png`.
 ## Commands
@@ -66,33 +72,55 @@ Short options may be grouped (`-xc`), an option's value may be attached or separ
 ### In SLICC
-`screencapture file` asks seven's page to capture. `getDisplayMedia` needs a user gesture, so the page first shows a prompt, `screencapture wants to capture your screen`, with **Choose…** and **Cancel**; **Choose…** opens Chrome's picker. After the user picks, the command waits for `-T` seconds, if given, takes one frame, crops it to `-R`, if given, encodes it and stops the capture.
+`screencapture file` asks seven's page to capture, as a `capture.screen` request on `/dev/embedder` ([below](#the-request)). `getDisplayMedia` needs a user gesture, so the page first shows a prompt, `screencapture wants to capture your screen`, with **Choose…** and **Cancel**; **Choose…** opens Chrome's picker. After the user picks, the page waits for `-T` seconds, if given, takes one frame, crops it to `-R`, if given, encodes it and stops the capture. The command writes the bytes it gets back unchanged; an existing file is replaced only once the capture has arrived.
 - **The file:** written as PNG, JPEG or WebP: `-t` decides, else the file's extension (`.png`, `.jpg` or `.jpeg`, `.webp`), else PNG. JPEG and WebP use quality 0.92. On success it prints `captured <n> KB to <file>`.
-- **`-c`:** copies the capture to the clipboard as `image/png`, through [slicc-clipboard](https://github.com/ai-ecoverse/slicc-clipboard), and prints `captured <n> KB to clipboard`. A file named with `-c` is ignored, as with macOS's `-c`, and so is `-t`. slicc-clipboard's device is text only today; `-c` needs its image path, which is being added there.
-- **`-v`:** shows the capture inline in the agent's tool result. With a file, it writes the file and prints `<path> (<n> KB)` followed by the image; without one, it prints only the image; with `-c`, it copies and shows. slicc 6 printed the image as `<img:data:<type>;base64,<data>>`; seven's marker for an inline image is being agreed with slicc-agent, and `-v` uses whatever that is. macOS's `-v` (record a video) is out of scope everywhere.
+- **`-c`:** captures a PNG and copies it to the clipboard as `image/png`, with a `clipboard.write` request on `/dev/embedder`, which seven's embedder (slicc-bios) answers; [slicc-clipboard](https://github.com/ai-ecoverse/slicc-clipboard)'s `/dev/clipboard` stays text only. It prints `captured <n> KB to clipboard`. A file named with `-c` is ignored, as with macOS's `-c`, and so is `-t`. The `clipboard.write` request is sent before the prompt, so a page that doesn't answer it fails at once, without a capture.
+- **`-v`:** shows the capture inline in the agent's tool result, by printing one line `<img:<absolute path>>` on stdout, the marker agreed in [ai-ecoverse/slicc-agent#713](https://github.com/ai-ecoverse/slicc-agent/issues/713): the agent reads that file, detects PNG, JPEG, GIF or WebP by its magic bytes, fits the image to 1600 px wide and 1 MB of base64, and replaces the line with `<path> (<mime>, <bytes> bytes)` and the image in the tool result (at most 4 per command). With a file, `-v` writes it and prints only the marker for it; without one, it writes the capture to a new `${TMPDIR:-/tmp}/screencapture-XXXXXX.<type>`, which it leaves there for the agent, and prints the marker for that; with `-c`, it copies, prints `captured <n> KB to clipboard`, and then the marker of such a file. slicc 6's `<img:data:<type>;base64,<data>>` is gone: base64 on stdout is scrubbed and cut by the output tail. The agent's side of #713 isn't shipped yet; until it is, the marker shows as the line itself. macOS's `-v` (record a video) is out of scope everywhere.
 - **No file:** without a file, `-c` or `-v`: `screencapture: output file required (or use -c for clipboard)` and the usage to stderr, exit 2.
 Errors, on stderr, from slicc 6 where they still apply:
 | error | exit |
 | --- | --- |
-| `screencapture: user cancelled or permission denied` (**Cancel**, the picker closed, or the capture refused) | 1 |
-| `screencapture: timed out waiting for the picker` (no answer within 5 minutes) | 1 |
-| `screencapture: browser APIs are unavailable in this environment` (an embedder that doesn't answer capture requests) | 1 |
-| `screencapture: screen capture is not supported in this browser` (no `getDisplayMedia`) | 1 |
-| `screencapture: -R: rectangle outside the capture` | 1 |
-| `screencapture: failed to write file: <message>` | 1 |
-| `screencapture: failed to copy to clipboard: <message>` | 1 |
+| `screencapture: user cancelled, permission denied, or the surface is protected` (`EACCES`: **Cancel**, the picker closed, the capture refused, or the embedder refused the surface the user picked) | 1 |
+| `screencapture: timed out waiting for the picker` (no answer within 5 minutes; the page's message) | 1 |
+| `screencapture: browser APIs are unavailable in this environment` (`ENOTSUP` for the header: no page answers `capture.screen`) | 1 |
+| `screencapture: screen capture is not supported in this browser` (`ENOTSUP` from the page, without a message of its own: no `getDisplayMedia`) | 1 |
+| `screencapture: -R: rectangle outside the capture` (the page's message) | 1 |
+| `screencapture: <message>` (any other error of the page, `EIO` or `ENOENT`: the first line of its message, else the errno's text, such as `I/O error`) | 1 |
+| `screencapture: the page sent no image` (an empty reply) | 1 |
+| `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 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 |
 | `screencapture: unknown option: <arg>`, then the usage | 2 |
 | `screencapture: <opt>: not supported in SLICC` | 2 |
 | `screencapture: -t <format>: not supported in SLICC` | 2 |
 | `screencapture: -T: invalid delay: <value>`, `-R: invalid rectangle: <value>`, `-D: invalid display: <value>`, `-J: invalid style: <value>` | 2 |
 | `screencapture: more than one file: not supported in SLICC` | 2 |
-As `sccapture`, the messages start with `sccapture:`.
+As `sccapture`, the messages start with `sccapture:`. A line of progress from the page (`progress(line)`) reaches stderr as `<cmd>: <line>` while the command waits.
+### The request
+The commands run in a kernel worker, which has no `getDisplayMedia`, so they ask seven's page over [`/dev/embedder`](https://github.com/ai-ecoverse/slicc-kernel#devembedder) (slicc-kernel 1.153.0, [#1527](https://github.com/ai-ecoverse/slicc-kernel/issues/1527)): one open file description per request, a JSON header line `{ kind, …options }`, then the body, and the reply read to end-of-file. The page side, the prompt, `getDisplayMedia`, the frame, the crop and the encoding, is a page module that slicc-bios registers for `capture.screen` and wraps with its own prompt, user activation, `selfBrowserSurface: 'exclude'` and a check of the picked surface against protected origins; it answers this contract:
-**The bridge from the kernel to the page is not settled yet.** The commands run in a kernel worker, which has no `getDisplayMedia`, so a request has to reach seven's page and the frame has to come back. slicc-clipboard does this with a kernel character device that the kernel answers from its embedder's hook; slicc-open, slicc-capture and slicc-audio are agreeing one pattern for all three in [ai-ecoverse/slicc-kernel#1527](https://github.com/ai-ecoverse/slicc-kernel/issues/1527) (pending), with the kernel and seven's embedder (slicc-bios). Until then this section describes only what the user sees. The page side (the prompt, `getDisplayMedia`, the frame, the crop and the encoding) ships in this package for the embedder; its entry point, the transport and the `engines.slicc-kernel` it needs are added here once the pattern is agreed.
+- **`capture.screen`:** the header is plain JSON, with no body, and the reply is the encoded image's bytes, nothing else. The command opens the device read-write (`exec 3<>/dev/embedder`), writes the header from a child `sh` that stays until the reply is read (so the page's progress reaches stderr), and reads the reply with a `cat <&3` that it starts in the background, so that a signal to the command can stop it.
+| header field | value | from |
+| --- | --- | --- |
+| `kind` | `"capture.screen"` | |
+| `type` | `"image/png"`, `"image/jpeg"` or `"image/webp"` | `-t`, else the file's extension, else PNG; always PNG with `-c` |
+| `quality` | `0.92`, only for JPEG and WebP | |
+| `cursor` | `"always"` or `"never"`, for `getDisplayMedia`'s `cursor` | `-C` |
+| `surface` | `"monitor"` or `"window"`, absent without one, for `displaySurface` (a hint: the user still picks) | `-m` and `-D` give `"monitor"`; `-w`, `-W` and `-J window` give `"window"`; the last one wins |
+| `delay` | seconds as a JSON number (`3`, `0.5`), absent without `-T`; the page waits that long after the picker | `-T` |
+| `rect` | `{ "x", "y", "width", "height" }`, whole numbers in the frame's pixels, absent without `-R`; outside the frame, the page rejects with `-R: rectangle outside the capture` | `-R` |
+For example, `screencapture -C -T 2 -R 0,0,800,600 shot.jpg` sends `{"kind":"capture.screen","type":"image/jpeg","quality":0.92,"cursor":"always","delay":2,"rect":{"x":0,"y":0,"width":800,"height":600}}`. The page rejects with a `NotAllowedError` or `AbortError` for **Cancel**, a closed picker, a refused permission or a protected surface (`EACCES`); a `NotSupportedError` without `getDisplayMedia` (`ENOTSUP`); and any other error, such as a `TimeoutError` `timed out waiting for the picker` after 5 minutes, with the message the command prints (`EIO`). It aborts the capture when its `signal` does.
+- **`clipboard.write`:** `-c` sends `{"kind":"clipboard.write","type":"image/png"}` and the PNG as the body, and reads the reply, which is empty, to end-of-file. slicc-bios answers it; with no page that does, the header write fails with `ENOTSUP`. The device is opened read-write and the reply read only after the whole body is written, so a page that answers without reading the body ([slicc-kernel#1536](https://github.com/ai-ecoverse/slicc-kernel/issues/1536)) is the only way a body over 1 MiB could block; the embedder's handler reads it.
 ### Options
@@ -103,8 +131,8 @@ Every option of macOS's `screencapture`, and what it does in SLICC and with `scc
 | `-a` | don't capture attached windows | no-op | passed | no-op | no-op |
 | `-b` | capture the Touch Bar | not supported | passed | not supported | not supported |
 | `-B <bundleid>` | open in that app | not supported | passed | not supported | not supported |
-| `-c` | to the clipboard | through slicc-clipboard, as `image/png` | passed | see [Linux](#linux) | `Clipboard.SetImage` |
-| `-C` | include the cursor | asks for `cursor: 'always'` (else `'never'`), which the browser may not honour | passed | see [Linux](#linux) | draws the cursor into the image |
+| `-c` | to the clipboard | a `clipboard.write` request, as `image/png` | passed | see [Linux](#linux) | `Clipboard.SetImage` |
+| `-C` | include the cursor | `"cursor": "always"` (else `"never"`), which the browser may not honour | passed | see [Linux](#linux) | draws the cursor into the image |
 | `-d` | show errors graphically | no-op | passed | no-op | no-op |
 | `-D <display>` | that display (1 is main) | prefers `displaySurface: 'monitor'`; the user picks the screen | passed | not supported | screen *n*: 1 is the primary, then the others in `AllScreens` order; no such screen is `sccapture: -D <n>: no such display`, exit 1 |
 | `-g` | record default audio input | not supported | not supported | not supported | not supported |
@@ -126,7 +154,7 @@ Every option of macOS's `screencapture`, and what it does in SLICC and with `scc
 | `-T <seconds>` | wait before capturing | waits after the picker | passed | `sccapture` waits, then runs the tool | `sccapture` waits, then captures |
 | `-u` | show the UI afterwards, file ignored | not supported | passed | not supported | not supported |
 | `-U` | the interactive toolbar | not supported | passed | not supported | not supported |
-| `-v` | record a video | inline in the tool result (slicc 6's `-v`) | not supported | not supported | not supported |
+| `-v` | record a video | inline in the tool result, as an `<img:<path>>` line ([slicc-agent#713](https://github.com/ai-ecoverse/slicc-agent/issues/713)) | not supported | not supported | not supported |
 | `-V <seconds>` | record a video for that long | not supported | not supported | not supported | not supported |
 | `-w` | window selection only | prefers `displaySurface: 'window'` | passed | see [Linux](#linux) | not supported |
 | `-W` | start in window selection | prefers `displaySurface: 'window'` | passed | as `-w` | not supported |
@@ -149,7 +177,6 @@ Only `sccapture` is installed on a host (the package's `bin`, a small Node scrip
 - **The file and its format:** without `-t`, the file's extension picks the format (on macOS, `sccapture` adds `-t` for `.jpg`, `.jpeg`, `.pdf`, `.tiff`, `.gif` and `.bmp`), else PNG. `-c` copies PNG; a file, `-t` and `-P` are then ignored, except on macOS, where `screencapture` decides. Success prints nothing, as `screencapture` does.
 - **A file is required**, as in SLICC (`sccapture: output file required (or use -c for clipboard)`, exit 2), except on macOS with `-p`, `-u`, `-P`, `-M` or `-B`, which `screencapture` handles without one.
 - **Errors:** with no tool on `PATH`, `sccapture: no screenshot tool found (tried grim, gnome-screenshot)` (the names tried on that platform) to stderr, exit 1; with `-c` and no clipboard tool, `sccapture: no clipboard tool found (tried wl-copy, xclip)`, exit 1. A tool that fails, a cancelled selection included, has its stderr passed through, exit 1. An unknown option prints `sccapture: unknown option: <arg>` and the usage to stderr, exit 2; an option the table marks as not supported on that platform prints `sccapture: <opt>: not supported on <platform>`, exit 2. The values of `-T`, `-R`, `-D` and `-J` are checked as in SLICC, and `-l` takes a window id in decimal or `0x` hex, else `sccapture: -l: invalid window: <value>`, exit 2. `-h` and `--help` print the usage to stdout and exit 0.
-- **`--upgrade`:** the command counts as installed by the installer when it runs from `<data>/<version>/host/sccapture.mjs` with a `<data>/current` next to it, and as installed with npm otherwise. `--dir` is the directory on `PATH` whose `sccapture` (`sccapture.cmd` on Windows) names `<data>`, else the installer's default. It downloads the installer with `curl`, else `wget` (`curl.exe` on Windows), and without one prints `sccapture: no downloader found (tried curl, wget)`, exit 1; a failed download has its stderr passed through, exit 1. The installer runs with `sh` (`powershell.exe`, else `pwsh.exe`, with `-ExecutionPolicy Bypass -File` on Windows), without `VERSION` and `INSTALL_DIR` in its environment, so it installs the latest release where the command is; the new version is read from `<data>/current/package.json`.
 - **Other Unix systems** are treated as Linux.
 ### Linux
@@ -182,7 +209,9 @@ Every host command takes `--upgrade`. It runs the latest release's installer (`i
 For slicc-capture, the commands are `sccapture` on a host and `screencapture` and `sccapture` in SLICC.
-`--version` prints the version (`0.1.0`) to stdout and exits 0, on a host and in SLICC; the installers call the launcher with it. It takes no other arguments either.
+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.
+`--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.
 ## Development
@@ -194,9 +223,9 @@ 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.
-- `npm test`: the integration tests in `test/integration/`. `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`, `pwsh.exe`, `curl`, `wget` and a fake installer on a temporary `PATH`, with the platform forced, so each branch is checked on any machine; only CI touches a real screen.
-- `npm run test:unit`: the unit tests in the gitignored `test/unit/`, with coverage in `coverage/unit/lcov.info`. The pre-commit hook wants 100% coverage of the changed lines, and runs `diff-cover` through `uvx`, so install [uv](https://docs.astral.sh/uv/) once.
+- `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 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.

package/bin/sccapture ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ #!/bin/sh
2	+ . "${0%/*}/screencapture"

package/bin/screencapture ADDED Viewed

@@ -0,0 +1,310 @@
+#!/bin/sh
+me=${0##*/}
+dev=/dev/embedder
+usage() {
+  printf 'usage: %s [-acdimorvwxCW] [-t format] [-T seconds] [-R x,y,w,h] [-D display] [-J style] [file]\n' "$me"
+}
+say() {
+  printf '%s: %s\n' "$me" "$1" >&2
+}
+bad() {
+  say "$1"
+  usage >&2
+  exit 2
+}
+refuse() {
+  say "$1"
+  exit 2
+}
+die() {
+  say "$1"
+  exit 1
+}
+first() {
+  [ -n "$problem" ] || problem=$1
+}
+num() {
+  n=$1
+  while :; do
+    case $n in
+      0[0-9]*) n=${n#0} ;;
+      *) break ;;
+    esac
+  done
+  printf '%s' "$n"
+}
+digits() {
+  case $1 in
+    '' | *[!0-9]*) return 1 ;;
+  esac
+}
+delay() {
+  case $1 in
+    '' | .* | *. | *.*.* | *[!0-9.]*) return 1 ;;
+  esac
+}
+rect() {
+  case $1 in
+    *,*,*,*,*) return 1 ;;
+    *,*,*,*) ;;
+    *) return 1 ;;
+  esac
+  rx=${1%%,*}
+  rest=${1#*,}
+  ry=${rest%%,*}
+  rest=${rest#*,}
+  rw=${rest%%,*}
+  rh=${rest#*,}
+  digits "$rx" && digits "$ry" && digits "$rw" && digits "$rh" || return 1
+  [ "$(num "$rw")" != 0 ] && [ "$(num "$rh")" != 0 ]
+}
+format() {
+  case $1 in
+    [pP][nN][gG]) printf png ;;
+    [jJ][pP][gG] | [jJ][pP][eE][gG]) printf jpeg ;;
+    [wW][eE][bB][pP]) printf webp ;;
+  esac
+}
+value() {
+  case $1 in
+    T)
+      delay "$2" || first "-T: invalid delay: $2"
+      wait=$2
+      ;;
+    R)
+      rect "$2" || first "-R: invalid rectangle: $2"
+      area=$2
+      ;;
+    D)
+      case $2 in
+        [1-9]*) digits "$2" || first "-D: invalid display: $2" ;;
+        *) first "-D: invalid display: $2" ;;
+      esac
+      surface=monitor
+      ;;
+    J)
+      case $2 in
+        window) surface=window ;;
+        selection | video) style=${style:-"-J $2: not supported in SLICC"} ;;
+        *) first "-J: invalid style: $2" ;;
+      esac
+      ;;
+    t) type=$2 ;;
+    *) off=${off:-"-$1"} ;;
+  esac
+}
+flag() {
+  case $1 in
+    c) clip=1 ;;
+    C) cursor=always ;;
+    v) view=1 ;;
+    m) surface=monitor ;;
+    w | W) surface=window ;;
+    a | d | i | o | r | x) ;;
+    *) off=${off:-"-$1"} ;;
+  esac
+}
+version() {
+  while IFS= read -r line; do
+    case $line in
+      *'"version": "'*)
+        line=${line#*'"version": "'}
+        printf '%s\n' "${line%%\"*}"
+        return
+        ;;
+    esac
+  done <"${0%/*}/../package.json"
+}
+relay() {
+  while IFS= read -r line; do
+    case $line in
+      *": $dev: "*) printf '%s\n' "${line#*": $dev: "}" >"$work/message" ;;
+      *": printf: write error: "*) printf '%s\n' "${line##*: }" >"$work/header" ;;
+      "cat: -: "* | "cat: write error: "*) printf '%s\n' "${line##*: }" >"$work/errno" ;;
+      *) printf '%s: %s\n' "$me" "${line#*: }" >&2 ;;
+    esac
+  done
+}
+ask() {
+  rm -f "$work/message" "$work/header" "$work/errno"
+  { { "$@"; } 2>&1 >&5 | relay; } 5>&1 &
+  wait "$!"
+  header=
+  errno=
+  message=
+  [ ! -f "$work/header" ] || header=$(cat "$work/header")
+  [ ! -f "$work/errno" ] || errno=$(cat "$work/errno")
+  [ ! -f "$work/message" ] || message=$(cat "$work/message")
+  errno=${errno:-$header}
+  [ -z "$errno" ]
+}
+because() {
+  printf '%s' "${message:-$errno}"
+}
+copyfail() {
+  case $header in
+    "Not supported") die "failed to copy to clipboard: this page does not copy images (no clipboard.write)" ;;
+  esac
+  die "failed to copy to clipboard: $(because)"
+}
+stop() {
+  [ ! -s "$work/pid" ] || kill -TERM "$(cat "$work/pid")" 2>/dev/null
+  wait
+  say interrupted
+  exit $((128 + $1))
+}
+absolute() {
+  case $1 in
+    */*) dir=${1%/*} base=${1##*/} ;;
+    *) dir=. base=$1 ;;
+  esac
+  dir=$(cd -- "${dir:-/}" && pwd)
+  printf '%s/%s' "${dir%/}" "$base"
+}
+cleanup() {
+  rm -rf "$work"
+}
+argc=$#
+clip=
+view=
+cursor=never
+surface=
+wait=
+area=
+type=
+style=
+off=
+problem=
+wrong=
+special=
+help=
+ended=
+files=0
+file=
+while [ $# -gt 0 ]; do
+  arg=$1
+  shift
+  if [ -n "$ended" ]; then
+    files=$((files + 1))
+    file=${file:-$arg}
+    continue
+  fi
+  case $arg in
+    --) ended=1 ;;
+    --help) help=1 ;;
+    --version | --upgrade) special=${special:-$arg} ;;
+    --clipboard) clip=1 ;;
+    --view) view=1 ;;
+    --*) wrong=${wrong:-"unknown option: $arg"} ;;
+    -?*)
+      rest=${arg#-}
+      while [ -n "$rest" ]; do
+        letter=${rest%"${rest#?}"}
+        rest=${rest#?}
+        case $letter in
+          h) help=1 ;;
+          [BDGJlRtTV])
+            if [ -n "$rest" ]; then
+              value "$letter" "$rest"
+            elif [ $# -gt 0 ]; then
+              value "$letter" "$1"
+              shift
+            else
+              wrong=${wrong:-"-$letter: option requires a value"}
+            fi
+            rest=
+            ;;
+          [abcCdgikmMoprPsSuUvwWx]) flag "$letter" ;;
+          *)
+            wrong=${wrong:-"unknown option: -$letter"}
+            rest=
+            ;;
+        esac
+      done
+      ;;
+    *)
+      files=$((files + 1))
+      file=${file:-$arg}
+      ;;
+  esac
+done
+if [ -n "$help" ]; then
+  usage
+  exit 0
+fi
+[ -z "$wrong" ] || bad "$wrong"
+if [ -n "$special" ]; then
+  [ "$argc" -eq 1 ] || bad "$special: takes no other arguments"
+  if [ "$special" = --upgrade ]; then
+    printf 'pnpm add -g @ai-ecoverse/slicc-capture@latest\n'
+  else
+    version
+  fi
+  exit 0
+fi
+[ -z "$off" ] || refuse "$off: not supported in SLICC"
+[ -z "$problem" ] || refuse "$problem"
+[ -z "$style" ] || refuse "$style"
+mime=png
+if [ -n "$clip" ]; then
+  file=
+  files=0
+elif [ -n "$type" ]; then
+  mime=$(format "$type")
+  [ -n "$mime" ] || refuse "-t $type: not supported in SLICC"
+else
+  case $file in
+    *.[jJ][pP][gG] | *.[jJ][pP][eE][gG]) mime=jpeg ;;
+    *.[wW][eE][bB][pP]) mime=webp ;;
+  esac
+fi
+[ "$files" -le 1 ] || refuse "more than one file: not supported in SLICC"
+[ -n "$file" ] || [ -n "$clip" ] || [ -n "$view" ] || bad "output file required (or use -c for clipboard)"
+[ -c "$dev" ] || die "$dev not available (needs slicc-kernel >= 1.153.0)"
+request="{\"kind\":\"capture.screen\",\"type\":\"image/$mime\""
+[ "$mime" = png ] || request="$request,\"quality\":0.92"
+request="$request,\"cursor\":\"$cursor\""
+[ -z "$surface" ] || request="$request,\"surface\":\"$surface\""
+[ -z "$wait" ] || request="$request,\"delay\":$(num "${wait%%.*}")${wait#"${wait%%.*}"}"
+[ -z "$area" ] || request="$request,\"rect\":{\"x\":$(num "$rx"),\"y\":$(num "$ry"),\"width\":$(num "$rw"),\"height\":$(num "$rh")}"
+request="$request}"
+work=$(mktemp -d)
+trap cleanup EXIT
+trap 'stop 1' HUP
+trap 'stop 2' INT
+trap 'stop 15' TERM
+if [ -n "$clip" ]; then
+  exec 4<>"$dev"
+  ask sh -c "printf '%s\\n' \"\$1\" >&4" sh '{"kind":"clipboard.write","type":"image/png"}' || copyfail
+fi
+exec 3<>"$dev"
+if ! ask sh -c "printf '%s\\n' \"\$1\" >&3 || exit 1; cat <&3 & echo \$! >\"\$2\"; wait \$!" sh "$request" "$work/pid" >"$work/image"; then
+  case $header in
+    "Not supported") die "browser APIs are unavailable in this environment" ;;
+  esac
+  case $errno in
+    "Permission denied") die "user cancelled, permission denied, or the surface is protected" ;;
+    "Not supported") die "${message:-screen capture is not supported in this browser}" ;;
+  esac
+  die "$(because)"
+fi
+exec 3<&-
+size=$(wc -c <"$work/image")
+[ "$size" -gt 0 ] || die "the page sent no image"
+kb=$(((size + 512) / 1024))
+if [ -n "$clip" ]; then
+  ask cat "$work/image" >&4 || copyfail
+  ask sh -c 'cat <&4' >/dev/null || copyfail
+  exec 4<&-
+  printf 'captured %s KB to clipboard\n' "$kb"
+fi
+if [ -z "$file" ]; then
+  [ -n "$view" ] || exit 0
+  file=$(mktemp "${TMPDIR:-/tmp}/screencapture-XXXXXX.$mime")
+fi
+err=$(tee -- "$file" <"$work/image" 2>&1 >/dev/null) || die "failed to write file: ${err#tee: }"
+if [ -n "$view" ]; then
+  printf '<img:%s>\n' "$(absolute "$file")"
+elif [ -z "$clip" ]; then
+  printf 'captured %s KB to %s\n' "$kb" "$file"
+fi

package/host/tools.mjs CHANGED Viewed

@@ -33,7 +33,7 @@ export function spawned(path, args, { env, stdin = 'ignore', capture = false })
     let child;
     try {
       child = spawn(path, args, {
-        env,
+        env: { ...env, SCCAPTURE_INSTALL_DIR: undefined },
         stdio: [stdin, capture ? 'pipe' : 'ignore', 'pipe'],
         shell: false,
         windowsHide: true,

package/host/upgrade.mjs CHANGED Viewed

@@ -1,107 +1,101 @@
-import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
-import { dirs, lookup, say, step } from './tools.mjs';
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { lookup, say } from './tools.mjs';
-const base = 'https://github.com/ai-ecoverse/slicc-capture/releases/latest/download';
+const latest = 'https://github.com/ai-ecoverse/slicc-capture/releases/latest/download';
-function version(dir) {
-  return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version;
+function fail(fds, text) {
+  say(fds[2], `sccapture: ${text}\n`);
+  return 1;
 }
-function home(platform, env) {
-  if (platform === 'win32') return join(env.LOCALAPPDATA ?? homedir(), 'slicc-capture');
-  return join(env.XDG_DATA_HOME || join(env.HOME ?? homedir(), '.local', 'share'), 'slicc-capture');
+function version(entry) {
+  return JSON.parse(readFileSync(join(dirname(dirname(entry)), 'package.json'), 'utf8')).version;
 }
-function real(path) {
+async function download(url) {
   try {
-    return realpathSync(path);
-  } catch {
-    return path;
+    const response = await fetch(url, { redirect: 'follow' });
+    if (!response.ok) return { error: `HTTP ${response.status}` };
+    return { text: await response.text() };
+  } catch (error) {
+    return { error: error.cause?.message ?? error.message };
   }
 }
-function launcher(platform, env, data) {
-  const fallback =
-    platform === 'win32'
-      ? join(home(platform, env), 'bin')
-      : join(env.HOME ?? homedir(), '.local', 'bin');
-  const name = platform === 'win32' ? 'sccapture.cmd' : 'sccapture';
-  const marks = [data];
-  if (real(home(platform, env)) === data) marks.push(home(platform, env));
-  for (const dir of [...dirs(platform, env), fallback]) {
-    let text;
-    try {
-      text = readFileSync(join(dir, name), 'utf8');
-    } catch {
-      continue;
-    }
-    if (marks.some((mark) => text.includes(mark))) return dir;
+function first(files, platform, env) {
+  for (const file of files) {
+    const path = lookup(file, platform, env);
+    if (path) return { file, path };
   }
-  return fallback;
+  return undefined;
 }
-export function installed(entry) {
-  const data = dirname(dirname(dirname(real(entry))));
-  if (basename(data) !== 'slicc-capture' || !existsSync(join(data, 'current'))) return undefined;
-  return data;
+function installer(platform, env, path, dir) {
+  if (platform === 'win32') {
+    const tool = first(['powershell.exe', 'pwsh.exe'], platform, env);
+    const args = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', path];
+    return tool && { tool, args: [...args, '-Dir', dir] };
+  }
+  const tool = first(['sh'], platform, env);
+  return tool && { tool, args: [path, '--dir', dir] };
+}
+function wait(path, args, { env, stderr }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(path, args, {
+        env,
+        stdio: ['ignore', 'pipe', stderr],
+        shell: false,
+        windowsHide: true,
+      });
+    } catch (error) {
+      resolve({ error });
+      return;
+    }
+    const out = [];
+    child.stdout.on('data', (chunk) => out.push(chunk));
+    child.on('error', (error) => resolve({ error }));
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout: Buffer.concat(out) }));
+  });
 }
 export async function upgrade({ entry, env, platform, fds }) {
-  const root = dirname(dirname(entry));
-  const old = version(root);
-  const data = installed(entry);
-  if (!data) {
+  const dir = env.SCCAPTURE_INSTALL_DIR;
+  if (!dir) {
     say(fds[1], 'npm install -g @ai-ecoverse/slicc-capture@latest\n');
     return 0;
   }
-  const windows = platform === 'win32';
-  const getters = windows ? ['curl.exe'] : ['curl', 'wget'];
-  const getter = getters
-    .map((name) => ({ name, path: lookup(name, platform, env) }))
-    .find((g) => g.path);
-  if (!getter) {
-    say(fds[2], `sccapture: no downloader found (tried ${getters.join(', ')})\n`);
-    return 1;
-  }
-  const shells = windows ? ['powershell.exe', 'pwsh.exe'] : ['sh'];
-  const shell =
-    shells.map((name) => lookup(name, platform, env)).find(Boolean) ??
-    (windows ? undefined : '/bin/sh');
-  if (!shell) {
-    say(fds[2], `sccapture: no PowerShell found (tried ${shells.join(', ')})\n`);
-    return 1;
-  }
-  const child = {};
-  for (const [key, value] of Object.entries(env)) {
-    if (!['VERSION', 'INSTALL_DIR'].includes(key.toUpperCase())) child[key] = value;
-  }
+  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 scratch = mkdtempSync(join(tmpdir(), 'sccapture-upgrade-'));
   try {
-    const name = windows ? 'install.ps1' : 'install.sh';
-    const script = join(scratch, name);
-    const url = `${base}/${name}`;
-    const fetch = getter.name === 'wget' ? ['-q', '-O', script, url] : ['-fsSL', '-o', script, url];
-    if (!(await step(getter.name, getter.path, fetch, { env: child }, fds))) return 1;
-    const dir = launcher(platform, env, data);
-    const args = windows
-      ? [
-          '-NoProfile',
-          '-NonInteractive',
-          '-ExecutionPolicy',
-          'Bypass',
-          '-File',
-          script,
-          '--dir',
-          dir,
-        ]
-      : [script, '--dir', dir];
-    if (!(await step(name, shell, args, { env: child }, fds))) return 1;
-    const now = version(join(data, 'current'));
+    const path = join(scratch, name);
+    writeFileSync(path, fetched.text);
+    const run = installer(platform, env, path, dir);
+    if (!run) {
+      const tried = platform === 'win32' ? 'powershell.exe, pwsh.exe' : 'sh';
+      return fail(fds, `no shell found to run ${name} (tried ${tried})`);
+    }
+    const child = { ...env };
+    delete child.SCCAPTURE_INSTALL_DIR;
+    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;
+    const installed = /^sccapture (\S+) installed to /m.exec(result.stdout.toString())?.[1];
+    if (!installed) return fail(fds, `${name} did not say which version it installed`);
+    const old = version(entry);
     say(
       fds[1],
-      now === old ? `sccapture: already up to date (${old})\n` : `sccapture: ${old} → ${now}\n`
+      installed === old
+        ? `sccapture: already up to date (${old})\n`
+        : `sccapture: ${old} → ${installed}\n`
     );
     return 0;
   } finally {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-capture",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "screencapture for SLICC, and sccapture for SLICC and any host",
   "type": "module",
   "license": "Apache-2.0",
@@ -9,7 +9,8 @@
     "url": "git+https://github.com/ai-ecoverse/slicc-capture.git"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=24",
+    "slicc-kernel": ">=1.153.0"
   },
   "bin": {
     "sccapture": "host/sccapture.mjs"
@@ -25,29 +26,44 @@
     "provenance": true
   },
   "slicc": {
+    "commands": {
+      "screencapture": {
+        "script": "bin/screencapture"
+      },
+      "sccapture": {
+        "script": "bin/sccapture"
+      }
+    },
     "unitSources": [
       "host"
     ]
   },
   "files": [
+    "bin",
     "host"
   ],
   "scripts": {
     "prepare": "slicc-install-hooks",
-    "lint": "slicc-lint",
+    "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: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",
     "trust": "npx fledgling sync -y --skip-publish",
     "trust:dry": "npx fledgling sync --dry-run -y --skip-publish",
     "release": "semantic-release"
   },
   "devDependencies": {
+    "@ai-ecoverse/slicc-kernel": "1.153.0",
     "@ai-ecoverse/slicc-shared-web": "2.11.3",
+    "@ai-ecoverse/wasm-bash": "5.3.0-23",
+    "@ai-ecoverse/wasm-coreutils": "9.12.0-15",
     "@biomejs/biome": "2.5.15",
+    "@semantic-release/exec": "7.1.0",
     "lefthook": "2.2.2",
     "monocart-coverage-reports": "2.13.2",
-    "semantic-release": "25.0.9"
+    "semantic-release": "25.0.9",
+    "slicc-kernel-without-embedder": "npm:@ai-ecoverse/slicc-kernel@1.152.2"
   }
 }