@ai-ecoverse/slicc 1.50.3 → 1.51.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 (2) hide show
  1. package/README.md +26 -3
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -21,6 +21,7 @@
21
21
  | `slicc browsers --json` | list running CDP endpoints and installed browsers, ranked |
22
22
  | `slicc update [--check]` | replace this binary with the latest release (works now; see [Updates](#updates)) |
23
23
  | `slicc install jerk` | install slicc-jerk into slicc's data folder (works now; see [Companion tools](#companion-tools)) |
24
+ | `slicc capabilities --json` | what this slicc offers a program that drives it: its commands, events and control ops (works now; see [Driving slicc from a program](#driving-slicc-from-a-program-slicc-capabilities)) |
24
25
 
25
26
  ## Install
26
27
 
@@ -294,7 +295,7 @@ Errors name the step that failed (`attestation identity: …`). A bundle from a
294
295
 
295
296
  These checks come first, so `--check` refuses the same way and nothing asks GitHub.
296
297
 
297
- Release builds outside npm and app bundles print a notice on stderr when a newer release exists: ``slicc X is available (you have Y); run `slicc update` ``. A go-installed release says ``run `go install github.com/ai-ecoverse/slicc-cli/cmd/slicc@latest` `` instead. The notice comes from a cache (`<user cache dir>/slicc/update-check-seven.json`; six's Go follower uses `update-check.json`, see [Coming from SLICC six](#coming-from-slicc-six)), and a background check refreshes it at most once every 24 hours, so no run waits on the check for more than 2 seconds. `--version`, `update`, and any command line with `--help`, `-h` or `-help` print no notice.
298
+ Release builds outside npm and app bundles print a notice on stderr when a newer release exists: ``slicc X is available (you have Y); run `slicc update` ``. A go-installed release says ``run `go install github.com/ai-ecoverse/slicc-cli/cmd/slicc@latest` `` instead. The notice comes from a cache (`<user cache dir>/slicc/update-check-seven.json`; six's Go follower uses `update-check.json`, see [Coming from SLICC six](#coming-from-slicc-six)), and a background check refreshes it at most once every 24 hours, so no run waits on the check for more than 2 seconds. `--version`, `capabilities`, `update`, and any command line with `--help`, `-h` or `-help` print no notice.
298
299
 
299
300
  ## Telemetry
300
301
 
@@ -302,7 +303,7 @@ Release builds (a plain `X.Y.Z` version, linked in or, for `go install`, from th
302
303
  - `enter`, with the subcommand as `source`, from a fixed list (`abort`, `attach`, `browsers`, `follow`, `install`, `launch`, `open`, `pair`, `prompt`, `unpair`, `update`, `wait`, `watch`, `default` for no command (no arguments, or only flags), `join` for a bare join URL, otherwise `unknown`). No other argument is ever sent.
303
304
  - `error`, for operational failures, from a fixed set of sources (`update`, `signal`, `link`, `browser`, `ssh`, `cdp`). Messages pass through go-optel's sanitizer, which strips URLs and paths.
304
305
 
305
- `--version`, and any command line with `--help`, `-h` or `-help` (such as `slicc update --help`), send nothing, and development builds never configure a client.
306
+ `--version`, `capabilities`, and any command line with `--help`, `-h` or `-help` (such as `slicc update --help`), send nothing, and development builds never configure a client.
306
307
 
307
308
  ## Environment
308
309
 
@@ -323,6 +324,28 @@ Release builds (a plain `X.Y.Z` version, linked in or, for `go install`, from th
323
324
  | `SLICC_LINK_URL` | inside seven only: the link facade's address, `tcp://127.0.0.1:<port>` (see [Inside seven](#inside-seven)) |
324
325
  | `SLICC_USER_DATA_DIR`, `XDG_STATE_HOME` | read, as SLICC six reads them, only to find six's Chrome profile (see [Using SLICC six's Chrome profile](#using-slicc-sixs-chrome-profile)) |
325
326
 
327
+ ## Driving slicc from a program: `slicc capabilities`
328
+
329
+ ```
330
+ slicc capabilities [--json]
331
+ ```
332
+
333
+ `slicc capabilities --json` is the handshake of a program that drives `slicc`, such as a native app: one JSON document on stdout, from the binary's own tables, so it describes exactly the `slicc` it came from. It reads no files, asks no network, sends no telemetry and prints no update notice, so it works the same inside an app bundle. Without `--json` it prints the version, the contract and a table of the commands.
334
+
335
+ ```
336
+ {"schema":1,"version":"<slicc version>","contract":1,"commands":{"<name>":{"json":"document"|"events"|"none","vocabulary"?:"events"|"agent"}},"events":{"schema":1,"names":[…]},"agent":{"events":[…],"own":[…]},"control":{"v":1,"ops":["status",…]}}
337
+ ```
338
+
339
+ - **`schema`:** the shape of this document, 1.
340
+ - **`version`:** the version `slicc --version` prints.
341
+ - **`contract`:** 1. It goes up only for a breaking change to a contract this document describes: a field or event that changes meaning or goes away. New commands, fields, events and ops leave it alone.
342
+ - **`commands`:** every command, keyed by name: `default` for `slicc` with no command, `follow`, `prompt`, `watch`, `wait` and `abort` (also after a join URL), `attach`, `open`, `pair`, `unpair`, `tray`, `browsers`, `launch`, `update`, `install`, `capabilities`, `version` and `help`. `json` says what `--json` prints: `document` (one JSON value), `events` (NDJSON, one event a line) or `none` (no `--json`). An `events` command has `vocabulary`: `events` for lines with `schema` and `event` (see [The default](#the-default-slicc) and [`slicc launch`](#slicc-launch---browser-id---profile-name---url-url---headless---no-seven-flags---json)), or `agent` for seven's agent events with `t` (see [`agent`](#agent-page-cap-agent-node--page)).
343
+ - **`events`:** `schema`, the `schema` every `event` line carries, and `names`, every `event` a `vocabulary: "events"` command can print, sorted.
344
+ - **`agent`:** `events`, the `t` of every agent event slicc knows, and `own`, the lines slicc itself adds to that stream (`settled`, see [Remote control](#remote-control-slicc-prompt-watch-wait-and-abort)).
345
+ - **`control`:** `v`, the version of the [control socket](#running-links-slicc-tray) protocol, and `ops`, the ops it answers.
346
+
347
+ A program reads `contract` and the names it needs, and treats anything it doesn't know as absent: an older `slicc` lacks the newer commands, events and ops, and a newer one may have more. `TestCapabilitiesNameEveryCommandEventAndOp` fails when a command, an event or a control op is added to the code without appearing here, and keeps the document's fixture, [`test/integration/testdata/native/capabilities.json`](test/integration/testdata/native/capabilities.json), in step with the binary.
348
+
326
349
  ## The default: `slicc`
327
350
 
328
351
  ```
@@ -2152,7 +2175,7 @@ CI installs a pinned release: `go install github.com/ai-ecoverse/slicc-cli/cmd/s
2152
2175
 
2153
2176
  ## Development
2154
2177
 
2155
- Go 1.26 and Node ≥ 24 (for the lint tools). `npm run build` writes `bin/slicc`. `npm run lint` runs the slicc lint tools, `gofmt`, `go mod tidy -diff`, `go vet` (also with `GOOS=darwin` and `GOOS=windows`, since CI tests on Linux only) and golangci-lint; `npm run lint:sh` runs shellcheck on `install.sh` and the scripts. `npm test` runs the integration tests in `test/integration/`, which build the binary and drive it; run `npm ci` first, since the [Inside seven](#inside-seven) tests need the pinned `@ai-ecoverse/slicc-kernel`. Unit tests stay next to the code and out of git (`npm run test:unit`). `go build` and `npm run build` link no version, so these binaries report `dev`. `npm run dist` cross-builds all six targets into `artifacts/release/` with `SHA256SUMS`, unsigned. `npm run npm:stage` then stages the npm packages into `dist/npm/`, and `npm run npm:check` packs them with `npm publish --dry-run`.
2178
+ Go 1.26 and Node ≥ 24 (for the lint tools). `npm run build` writes `bin/slicc`. `npm run lint` runs the slicc lint tools, `gofmt`, `go mod tidy -diff`, `go vet` (also with `GOOS=darwin` and `GOOS=windows`, since CI tests on Linux only) and golangci-lint; `npm run lint:sh` runs shellcheck on `install.sh` and the scripts. `npm test` runs the integration tests in `test/integration/`, which build the binary and drive it; run `npm ci` first, since the [Inside seven](#inside-seven) tests need the pinned `@ai-ecoverse/slicc-kernel`. Unit tests stay next to the code and out of git (`npm run test:unit`). `test/integration/testdata/native/` holds the fixtures of the contracts a native app relies on, each written by the integration test that checks it: run that test with `SLICC_FIXTURE_WRITE=1` to rewrite a fixture after a deliberate change, and commit the result. `go build` and `npm run build` link no version, so these binaries report `dev`. `npm run dist` cross-builds all six targets into `artifacts/release/` with `SHA256SUMS`, unsigned. `npm run npm:stage` then stages the npm packages into `dist/npm/`, and `npm run npm:check` packs them with `npm publish --dry-run`.
2156
2179
 
2157
2180
  **CI.** `.github/workflows/ci.yml` is one caller of [slicc-shared-web's pipeline](https://github.com/ai-ecoverse/slicc-shared-web#pipeline), pinned at the release of the `@ai-ecoverse/slicc-shared-web` devDependency, with `secrets: inherit`. On pull requests and in the merge queue it runs `lint` (`npm run lint` with golangci-lint, pinned in `ci.yml` and installed into `$RUNNER_TEMP`, then `npm run lint:sh`), then `npm test` on four Linux shards of the pool, then on a pull request the Claude and Codex reviews with this repo's `review-prompt`. The checks to require are `ci / integration` and `ci / review`. A push to `main` runs lint and the release (see [Releases](#releases)); it runs no tests, since what reaches `main` passed the merge queue. macOS and Windows aren't tested on pull requests or in the merge queue: lint vets both, and platform code needs a local run there. `.github/workflows/windows.yml` runs `TestWindowsArgs` on `windows-latest` on each push to `main`; it isn't a required check, and a red run there needs a follow-up pull request. **Test shards.** `npm test` runs `scripts/test-shard.mjs ci/4 -race -count=1 -timeout 15m -v ./test/integration/...`. On the pipeline's shard `SLICC_TEST_SHARD` (0 to 3) it runs that shard's share of the top-level tests; without it (a local run) it runs them all. The split is greedy by measured time: `test/integration/shard-times.json` holds each top-level test's seconds on `linux`, each test goes to the shard with the least time so far, a test without a time counts as the median, and the last shard runs everything the others don't, so a new test still runs. `go test` gets the pipeline's own `NODE_OPTIONS` back (without its shard preload and JUnit reporter) and none of its `SLICC_TEST_*` variables. The script writes each top-level test's result to the shard's JUnit report (`SLICC_TEST_JUNIT`), which the pipeline's `integration` check counts: it fails when no test ran or one failed. It also fails a shard that selects no tests or whose `go test -v` runs none, and, when a shard hits its `-timeout`, names the test that was running and how long the finished ones took. `node scripts/shard-times.mjs --run <CI run id>` refreshes the times from a finished run's `test (<n>)` logs (`linux=<log file>` reads local `go test -v` output instead); commit the result when tests get much slower or faster. `TestEachCIShardFitsItsTimeout` fails when a shard adds up to more than three quarters of its `-timeout`, or when `timeout-minutes` leaves less than 5 minutes past it: then raise `shards` in `ci.yml` and the count in `npm test` together. The [guard vectors](https://github.com/ai-ecoverse/slicc-browsers#guard-vectors) run on every shard; `SLICC_GUARD_VECTORS=0` skips them locally. On macOS they leave out the C9 vectors (extension worlds; the `C9.` prefix that `guardSkippedOn` in `guardrunner_test.go` returns for `darwin`): there their unguarded control hung in Chrome itself ([#344](https://github.com/ai-ecoverse/slicc-cli/issues/344)). `TestCDPGuardVectorsSkipC9OnlyOnMacOS` keeps the skip to macOS, and `TestCDPHidesExtensionWorlds` covers the extension-world guard everywhere. **Node:** CI runs Node 26: on Node 24.21.0, V8 crashed the WASI kernel harness (`TestWasi*`) about once in a hundred runs on Windows and occasionally on Linux.
2158
2181
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ai-ecoverse/slicc",
3
- "version": "1.50.3",
3
+ "version": "1.51.0",
4
4
  "description": "SLICC's command line for seven: links a machine's network, compute and browsers to seven over WebRTC",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -18,12 +18,12 @@
18
18
  "node": ">=18"
19
19
  },
20
20
  "optionalDependencies": {
21
- "@ai-ecoverse/slicc-darwin-arm64": "1.50.3",
22
- "@ai-ecoverse/slicc-darwin-amd64": "1.50.3",
23
- "@ai-ecoverse/slicc-linux-arm64": "1.50.3",
24
- "@ai-ecoverse/slicc-linux-amd64": "1.50.3",
25
- "@ai-ecoverse/slicc-windows-arm64": "1.50.3",
26
- "@ai-ecoverse/slicc-windows-amd64": "1.50.3",
21
+ "@ai-ecoverse/slicc-darwin-arm64": "1.51.0",
22
+ "@ai-ecoverse/slicc-darwin-amd64": "1.51.0",
23
+ "@ai-ecoverse/slicc-linux-arm64": "1.51.0",
24
+ "@ai-ecoverse/slicc-linux-amd64": "1.51.0",
25
+ "@ai-ecoverse/slicc-windows-arm64": "1.51.0",
26
+ "@ai-ecoverse/slicc-windows-amd64": "1.51.0",
27
27
  "@ai-ecoverse/slicc-jerk": "^1.3.9"
28
28
  }
29
29
  }