@ai-ecoverse/slicc 1.38.0 → 1.38.1

package/README.md

@@ -1,6 +1,6 @@
 # slicc-cli
 
-`slicc` is SLICC's command line for seven, the SLICC on `*.sliccy.ai`. It is one binary for macOS, Windows and Linux. It launches and links browsers, and shares a machine's network, compute and browsers with a running seven over a WebRTC link. `npx sliccy` and Sliccstart.app run this binary. It replaces slicc-node and slicc-swift.
+`slicc` is SLICC's command line for seven, the SLICC on `*.sliccy.ai`. It is one binary for macOS, Windows and Linux. It launches and links browsers, and shares a machine's network, compute and browsers with a running seven over a WebRTC link. `npx sliccy` and Sliccstart.app run this binary. It replaces slicc-node and slicc-swift (see [Coming from slicc-node](#coming-from-slicc-node)).
 
 **Status:** being built. `slicc` (the default flow), `slicc attach` (with the `cdp` capability), `slicc <join-url> follow`, remote control with `prompt`, `watch` and `abort`, host folders with `--mount`, `slicc browsers`, `slicc launch`, `update`, `install`, `--version` and `--help` work so far, plus a hidden diagnostic, `slicc <join-url> follow --signal-only [--timeout 2m]`. It attaches through the tray hub, prints a summary of the leader's offer (its size, media sections, candidate count and DTLS fingerprint) and the ICE server URLs (credentials are never printed), and exits without answering. The link protocol is drafted alongside seven's link exit and moves into this README once both sides pass a shared test.
 
@@ -19,11 +19,17 @@
 
 ## Install
 
+```
+curl -fsSL https://get.sliccy.ai/slicc | sh
+```
+
+This installs `slicc` on macOS and Linux; see [Install with curl](#install-with-curl). Options pass through to the script: `curl -fsSL https://get.sliccy.ai/slicc | sh -s -- --help`. If `get.sliccy.ai` can't be reached, use the GitHub release URL directly:
+
 ```
 curl -fsSL https://github.com/ai-ecoverse/slicc-cli/releases/latest/download/install.sh | sh
 ```
 
-This installs `slicc` on macOS and Linux; see [Install with curl](#install-with-curl). The alternatives:
+The alternatives:
 
 - **npm:** `npm install -g @ai-ecoverse/slicc`, or `npx @ai-ecoverse/slicc`. The package is a small Node launcher; npm picks one of the platform packages `@ai-ecoverse/slicc-<os>-<arch>` (`darwin`, `linux`, `windows` × `amd64`, `arm64`) through `optionalDependencies` and their `os` and `cpu` fields. The launcher runs that binary with the same arguments, stdio and environment plus `SLICC_LAUNCHER=npm`, forwards `SIGTERM`, `SIGHUP`, `SIGQUIT` and `SIGUSR2` to it, and `SIGINT` too when stdin is not a terminal (a terminal's Ctrl-C already reaches the binary; on Windows the console delivers Ctrl-C and Ctrl-Break to both). It exits with the binary's exit code, or dies of the same signal. An install with `--omit=optional` has no binary, and the launcher says so. slicc-jerk comes the same way; fnox doesn't (see [Companion tools](#companion-tools)).
 - **GitHub releases:** every release of `ai-ecoverse/slicc-cli` carries `slicc-<os>-<arch>` (`.exe` on Windows) for all six targets, plus `install.sh` and `SHA256SUMS` (which lists `install.sh` too). See [Verifying a download](#verifying-a-download).
@@ -31,8 +37,15 @@ This installs `slicc` on macOS and Linux; see [Install with curl](#install-with-
 
 ### Install with curl
 
-`install.sh` is a POSIX `sh` script, attached to every release and kept in the repo root. It:
-- takes `VERSION` (default: the latest release; `1.2.3` or `v1.2.3`) and `INSTALL_DIR` (default: `$HOME/.local/bin`) from the environment, or `--version X` and `--dir D` as flags (`curl … | sh -s -- --version 1.2.3 --dir ~/bin`), and `--help`;
+`install.sh` is a POSIX `sh` script, attached to every release and kept in the repo root. `https://get.sliccy.ai/slicc` redirects (`302`) to the latest release's copy, `https://github.com/ai-ecoverse/slicc-cli/releases/latest/download/install.sh`, so both one-liners run the same script:
+
+```
+curl -fsSL https://get.sliccy.ai/slicc | sh
+curl -fsSL https://github.com/ai-ecoverse/slicc-cli/releases/latest/download/install.sh | sh
+```
+
+Options go after `sh -s --`, as in `curl -fsSL https://get.sliccy.ai/slicc | sh -s -- --help`. The script:
+- takes `VERSION` (default: the latest release; `1.2.3` or `v1.2.3`) and `INSTALL_DIR` (default: `$HOME/.local/bin`) from the environment, or `--version X` and `--dir D` as flags (`curl -fsSL https://get.sliccy.ai/slicc | sh -s -- --version 1.2.3 --dir ~/bin`), and `--help`;
 - supports `Darwin` and `Linux` on `x86_64`/`amd64` and `arm64`/`aarch64` (an x86_64 shell under Rosetta gets `arm64`); anything else exits 1 and points to npm, or on Windows to the release's `.exe`;
 - downloads `slicc-<os>-<arch>` and `SHA256SUMS` from the release with `curl` or `wget`, checks the hash with `sha256sum` or `shasum -a 256`, and exits 1 without installing anything when the hash differs or `SHA256SUMS` has no line for the asset;
 - copies the binary to a temporary file in `INSTALL_DIR` and sets mode `755`; it exits 1 and leaves any installed `slicc` alone when that file's `--version` fails, doesn't print `slicc <version>`, or, with a version asked for, names another version;
@@ -121,6 +134,37 @@ Six's `--version`, `version`, `--profile` and `--mount` are seven flags too, and
 - **Kept by this binary:** `<config>/slicc/` holds `ssh_host_ed25519_key`, `tray-certs.json`, `tray-join.json` and `seven-profiles/`.
 - **Profiles:** six's Chrome profiles are `~/Library/Application Support/Slicc/profiles/browser-coding-agent-chrome[-<port>]` on macOS, `$XDG_STATE_HOME/slicc/profiles` on Linux and `%LOCALAPPDATA%\Slicc\profiles` on Windows (`chrome-launch.ts:119-148`). seven's live in `<config>/slicc/seven-profiles`, so a SLICC `--profile <name>` never opens six's logins. Only `--profile six` does, in place; see [Using SLICC six's Chrome profile](#using-slicc-sixs-chrome-profile). Discovery lists six's Chrome marked `six: true`, last, and never chooses it.
 
+## Coming from slicc-node
+
+`npx @ai-ecoverse/slicc-node` and slicc-swift ran a local HTTP proxy, which seven reached on loopback with the URL and key from the launch URL's `#proxy=…&key=…` fragment. `slicc` links seven over WebRTC instead (see [Link](#link)). On this machine the link is set up over CDP, and from another machine through the tray hub. So seven never connects to a port on this machine, and there is no proxy port, no key and no launch fragment. The only listener is the [kernel services](#kernel-services) one, which carries the browser's own connections to `*.kernel.localhost` into the page (`--no-kernel` turns it off).
+
+| slicc-node | `slicc` |
+| --- | --- |
+| `npx @ai-ecoverse/slicc-node`, which opens seven in the default browser | `npx sliccy@next`, or `slicc` from `curl -fsSL https://get.sliccy.ai/slicc \| sh` (see [Install with curl](#install-with-curl)). It launches or attaches to a Chromium browser over CDP and opens seven there (see [The default](#the-default-slicc)) |
+| `--page <url>`, `--origin <url>` | `--page <url>`, `--origin <origin>` |
+| `--port`, `--rotate-key`, `--ephemeral`, `--no-open` | not needed: there is no proxy port and no key |
+| `--mount <path>[:<name>][:ro]` | the same `--mount` (see [Host folders](#host-folders)). In seven the folder is `<device>/<name>` (`mount -t hostfs lars-mbp/project /mnt/p`) rather than `<name>` |
+| `--kernel-port <n>`, `--no-kernel` | the same flags (see [Kernel services](#kernel-services)) |
+| `--cdp <url>`, the `/cdp` relay to a running browser | the [`cdp`](#cdp-browser-control) capability. The browser seven runs in is always listed. More come from `--browser` (with `--cdp <url>` for an endpoint) on `slicc`, `--cdp-extra <url>` on `attach`, and `--cdp <url>` on `follow`. `--cdp-extra` and `follow --cdp` must answer when they start |
+| `--quiet` | no request log. `--plain` prints status lines, and `SLICC_DEBUG=1` logs each `http` stream's method, scheme and host |
+| `/api/fetch-proxy` | `http`, `tcp`, `resolve` and `ws` streams under the [local policy](#network-policy): the internet, this machine and the LAN, but not the browsers' debugging ports or `slicc`'s own ports |
+| `/api/hostfs/*`, tokens re-granted after a `403` | `fs` streams, with no tokens. In seven, a mount has no medium while the link is down, and fills in when the link is back |
+| `/api/kernel-tunnel` | `kernel` streams into the page |
+| `/auth/callback`, `/api/oauth-state`, `/api/oauth-result` | not needed on `https://<label>.sliccy.ai`, where seven signs in through the relay itself. A seven on another origin needs slicc-extension to sign in |
+| `startProxy`, `launchUrl`, `persistentKey` (JS) | no JS API |
+
+**Which browser.** slicc-node opened seven in the default browser, in any profile. `slicc` links only a seven it reaches over CDP:
+- **By default:** a browser in a SLICC profile (see [`slicc launch`](#slicc-launch---browser-id---profile-name---url-url---headless---no-seven-flags---json)). Its seven is separate from the one in your everyday profile, since seven keeps its files per browser profile.
+- **A browser that is already running with CDP** (`--cdp`). That includes your everyday Chrome once its remote debugging is turned on at `chrome://inspect/#remote-debugging`. It is then listed as `wsOnly` (see [Browsers](#browsers)).
+- **Any other browser**, a non-Chromium one included, only through the tray hub: in seven's Network panel, *Link a device*, then run `slicc <join-url> follow` on this machine (see [Remote setup](#remote-setup-slicc-join-url-follow)). That link has the remote policy (public addresses only, unless `--allow`) and no kernel services.
+
+**Restarts.** slicc-node kept its key and port, so an open page reconnected after a restart. `slicc` sets the link up again instead:
+- A browser that `slicc` launched runs in its own process group. It outlives a `slicc` that crashes or is killed.
+- The next `slicc` finds that browser's seven tab and links it again, with `attached` and no `launched`. It finds the tab through the profile's `DevToolsActivePort`, or through `--cdp`. Given the same `--mount` and `--kernel-port`, the folders and kernel services come back too.
+- Quitting `slicc` normally (`q`, Ctrl-C, `SIGTERM`) closes the browsers that run launched.
+- Every new `slicc` process has a new `node` id, so seven sees a new link from the same machine.
+- `attach` sets up again on every new seven context, and `follow` reconnects by itself, with the same device certificate.
+
 ## Using SLICC six's Chrome profile
 
 `slicc --profile six` and `slicc launch --profile six` use SLICC six's own Chrome profile, with its logins, cookies and extensions, in place: it is never copied, moved or migrated. `--profile six:<port>` picks the profile six uses for serve port `<port>`. Nothing else ever chooses six's profile: not the default, `--yes`, `--json`, `--browser` or a `--cdp` URL.
@@ -444,7 +488,7 @@ slicc attach --cdp <url> [--cdp-extra <url>]... [--origin <origin>]... [--signal
 - `--signal`: `cdp` (default) or `stdio`.
 - `--name`: the link's `name` and `host` in HELLO. The default name is `slicc on <host>`, with this machine's short host name, lower-cased.
 - `--allow`, `--deny`: policy rules on top of the local default (see [Network policy](#network-policy)). The `--cdp` and `--cdp-extra` ports and endpoint addresses are denied.
-- `--runner <argv…>`: offer compute over SSH (cap `ssh`, see [SSH server](#ssh-server)). Each command runs as `<argv…> <command>`. The argv is every word after `--runner` up to a lone `--` or the end of the command line, so `--runner bash -c` or `--runner docker exec -i box sh -c -- --name box`. An argv can't contain a lone `--` itself. `--runner=…` is refused. Without `--runner` the link has no `ssh` capability, and the flags below are refused.
+- `--runner <argv…>`: offer compute over SSH (cap `ssh`, see [SSH server](#ssh-server)). Each command runs as `<argv…> <command>`. The argv is every word after `--runner` up to a lone `--` or the end of the command line, so `--runner bash -c` or `--runner docker exec -i box sh -c -- --name box`. An argv can't contain a lone `--` itself. `--runner=…` is refused. At start, slicc resolves the argv's first word as exec does (on `PATH`, or a path to an executable; a relative path is made absolute, since commands run in the home directory) and exits 2 before linking when it doesn't: `slicc: --runner <x>: program not found`, or, when the word holds whitespace (`--runner "bash -c"`), `slicc: --runner "bash -c": no program "bash -c"; did you mean --runner bash -c?`. Without `--runner` the link has no `ssh` capability, and the flags below are refused.
 - `--shell <argv…>`: the interactive form for `ssh` without a command, in the same argv syntax. The default is derived from the runner.
 - `--eval <argv…>` and `--eval-quiet <duration>`: the REPL behind the `slicc-eval` subsystem (for example `--eval python3 -i`), and the silence that ends one response (default `500ms`).
 - `--sftp`, `--no-sftp`: serve the `sftp` subsystem or not. The default is on only for a plain local shell as the runner.
@@ -516,7 +560,7 @@ HELLO from `attach`: `{ "v": 1, "role": "node", "name", "host", "version", "mode
 - `addresses: []` means "not mine": the name doesn't exist (NXDOMAIN, or any other failure but a timeout), has no address of that family, or every address was dropped.
 - RESET codes: `ETIMEDOUT` when the lookup times out (30 s at most), and `EPROTO` for an OPEN without a name or with another `family`.
 
-**`http`** (cap `http`), page → node. slicc-node's raw fetch (its README, *Request* and *Response*) carried on a stream:
+**`http`** (cap `http`), page → node. One HTTP request, fetched by the node without CORS, carried on a stream:
 - OPEN `{ "kind": "http" }`, answered OPENED `{}` at once.
 - The page sends a `u32` BE length, that many bytes of UTF-8 JSON `{ "url", "method", "headers": [[name, value], …] }` (at most 1 MiB), then the request body, then END.
 - The node sends a `u32` BE length, the JSON `{ "status", "statusText", "headers": [[name, value], …], "url" }`, then the body, then END. `url` is the request's.
@@ -608,7 +652,7 @@ Only browsers the user named are listed: the one seven runs in, `--cdp` and `--c
 - **OPENED:** `{ "product", "protocolVersion" }`, the `Browser` and `Protocol-Version` fields of `/json/version` (from `Browser.getVersion` for a `wsOnly` browser).
 - **RESET:** `ENOENT` for an id that isn't listed, `ECONNREFUSED` when the browser doesn't answer, `EPROTO` for an OPEN without `browser`.
 
-**Bytes**, both directions: a sequence of messages, each a `u32` BE length plus one UTF-8 CDP JSON message of at most 64 MiB (67 108 864 bytes). The node sends each page message as one WebSocket text message, and each text message from the browser as one stream message, after the filter below. A length over 64 MiB from the page, or a browser message over 64 MiB, is `RESET EMSGSIZE`, and a page END in the middle of a message is `RESET EPROTO`. Browser messages that start with `{"method":"Network.webSocketFrameReceived"` or `{"method":"Network.webSocketFrameSent"` are dropped: seven runs inside a browser it may debug, so those events would carry the CDP traffic itself and grow without bound (parity with slicc-node's `/cdp`).
+**Bytes**, both directions: a sequence of messages, each a `u32` BE length plus one UTF-8 CDP JSON message of at most 64 MiB (67 108 864 bytes). The node sends each page message as one WebSocket text message, and each text message from the browser as one stream message, after the filter below. A length over 64 MiB from the page, or a browser message over 64 MiB, is `RESET EMSGSIZE`, and a page END in the middle of a message is `RESET EPROTO`. Browser messages that start with `{"method":"Network.webSocketFrameReceived"` or `{"method":"Network.webSocketFrameSent"` are dropped: seven runs inside a browser it may debug, so those events would carry the CDP traffic itself and grow without bound.
 
 **Closing.**
 - The browser closes the socket with a normal close (1000): the node sends END, then discards whatever the page still sends until its END.
@@ -688,7 +732,7 @@ The browser's connection waits unread for `OPENED`.
 
 ## Host folders
 
-`--mount <path>[:<name>][:ro]` shares a folder of this machine with seven's kernel, which mounts it with its `hostfs` driver. It is repeatable and works on `slicc`, `slicc attach` and `slicc <join-url> follow`. This is slicc-node's hostfs (its README, *Host folders*), with the same operations and the same rules, carried on `fs` link streams instead of HTTP. There are no tokens: the link is the trust boundary, as for `ssh`, and seven decides which kernel mounts it creates. With `follow`, the folders go to the seven on the other machine.
+`--mount <path>[:<name>][:ro]` shares a folder of this machine with seven's kernel, which mounts it with its `hostfs` driver. It is repeatable and works on `slicc`, `slicc attach` and `slicc <join-url> follow`. Each operation is an `fs` link stream (below). There are no tokens: the link is the trust boundary, as for `ssh`, and seven decides which kernel mounts it creates. With `follow`, the folders go to the seven on the other machine.
 
 **Export.**
 - A trailing `:ro` makes the folder read-only. After that, the text after the last `:` is the name if it isn't empty and has no `/` or `\`, so `C:\work` is a path and `C:\work:proj` is named `proj`. The default name is the folder's own.
@@ -713,7 +757,7 @@ The paths are read from slicc's own environment at start. A `--mount` of one of
                                "caseInsensitive": true, "normalization": "nfd-insensitive", "ranges": true } }]
 ```
 
-- `capabilities` is slicc-node's grant answer, so seven hands it to the driver unchanged.
+- `capabilities` is in the shape slicc-kernel's `hostfs` driver takes, so seven hands it to the driver unchanged.
 - `symlinks` and `chmod` are `false` on Windows and `true` elsewhere.
 - `caseInsensitive` is probed per folder on its own volume. The last component of the folder's path that has letters is looked up again with its case swapped, and the probe is `true` when that finds the same file. When no component has letters, it is `true` on macOS and Windows.
 - `normalization` is `nfd-insensitive` on macOS and `none` elsewhere.
@@ -731,7 +775,7 @@ The paths are read from slicc's own environment at start. A `--mount` of one of
 - The last component gets lstat semantics. The kernel follows symlinks itself, so `stat` reports a symlink as one, `list` on a symlink is `ENOTDIR`, and `open` on a symlink is `ELOOP`.
 - Operations that change the namespace run one at a time, and no other operation runs alongside them. The lock covers every link and every folder of the node, so no page can swap a directory for a symlink between the check and the use.
 
-**Operations**, with slicc-node's arguments and answers:
+**Operations**, with their arguments and answers:
 
 | op | arguments | answer |
 | --- | --- | --- |
@@ -798,7 +842,7 @@ The watcher per OS:
 
 **Mount updates** (page cap `mounts`). When folders are added or removed while a link is up (`fs.Server.Add` and `Remove`, for the TUI), the node opens `OPEN { "kind": "mounts", "mounts": [ … ] }` on the control channel, with the full list in HELLO's shape. It replaces the previous list, and there are no deltas. The page answers OPENED `{}` and END, and the node sends END. Updates go one at a time per link, and one the page doesn't finish within 10 s is reset with `ETIMEDOUT`. A removed folder's handles close (`EBADF` if the name comes back), its operations are `ENOENT`, and a watch stream covering it ends with `RESET ENOENT: no such folder`. `--mount` alone never changes the set.
 
-**Errors.** The code is the POSIX name, `EIO` when there is none. The message is libuv's lower-case text for it (`no such file or directory`), or slicc-node's own for the cases it names (`path escapes the folder`, `read-only folder`, `file changed since it was opened`, `the folder root cannot be moved or removed`). It never contains a host path. Windows errors are mapped the way libuv maps them, for example `ERROR_ACCESS_DENIED` to `EPERM` and `ERROR_SHARING_VIOLATION` to `EBUSY`.
+**Errors.** The code is the POSIX name, `EIO` when there is none. The message is libuv's lower-case text for it (`no such file or directory`), or slicc's own for the cases it names (`path escapes the folder`, `read-only folder`, `file changed since it was opened`, `the folder root cannot be moved or removed`). It never contains a host path. Windows errors are mapped the way libuv maps them, for example `ERROR_ACCESS_DENIED` to `EPERM` and `ERROR_SHARING_VIOLATION` to `EBUSY`.
 
 **Windows.**
 - Paths go through `\\?\` and `GetFinalPathNameByHandle`, so device names (`CON`, `NUL`) and 8.3 short names are plain names inside the folder.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc",
-  "version": "1.38.0",
+  "version": "1.38.1",
   "description": "SLICC's command line for seven: links a machine's network, compute and browsers to seven over WebRTC",
   "license": "Apache-2.0",
   "repository": {
@@ -18,12 +18,12 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@ai-ecoverse/slicc-darwin-arm64": "1.38.0",
-    "@ai-ecoverse/slicc-darwin-amd64": "1.38.0",
-    "@ai-ecoverse/slicc-linux-arm64": "1.38.0",
-    "@ai-ecoverse/slicc-linux-amd64": "1.38.0",
-    "@ai-ecoverse/slicc-windows-arm64": "1.38.0",
-    "@ai-ecoverse/slicc-windows-amd64": "1.38.0",
-    "@ai-ecoverse/slicc-jerk": "^0.13.0"
+    "@ai-ecoverse/slicc-darwin-arm64": "1.38.1",
+    "@ai-ecoverse/slicc-darwin-amd64": "1.38.1",
+    "@ai-ecoverse/slicc-linux-arm64": "1.38.1",
+    "@ai-ecoverse/slicc-linux-amd64": "1.38.1",
+    "@ai-ecoverse/slicc-windows-arm64": "1.38.1",
+    "@ai-ecoverse/slicc-windows-amd64": "1.38.1",
+    "@ai-ecoverse/slicc-jerk": "^0.15.0"
   }
 }