@ai-ecoverse/slicc-capture 1.0.0 → 1.1.0

package/README.md

@@ -19,7 +19,7 @@ In SLICC, the package declares `screencapture` and `sccapture` in `slicc.command
 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
 
@@ -149,7 +155,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 +187,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,8 +201,8 @@ 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 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`.
+- `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` 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`. 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.
 
 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/host/tools.mjs

@@ -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

@@ -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

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-capture",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "screencapture for SLICC, and sccapture for SLICC and any host",
   "type": "module",
   "license": "Apache-2.0",
@@ -34,7 +34,7 @@
   ],
   "scripts": {
     "prepare": "slicc-install-hooks",
-    "lint": "slicc-lint",
+    "lint": "slicc-lint && shellcheck -s sh install.sh && dash -n install.sh",
     "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'",
@@ -46,6 +46,7 @@
   "devDependencies": {
     "@ai-ecoverse/slicc-shared-web": "2.11.3",
     "@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"