skillcask 0.10.0 → 0.10.2

package/README.md

@@ -33,6 +33,29 @@ powershell -ExecutionPolicy Bypass -c "irm https://github.com/puniserv/skillcask
 The two installer scripts download the binary for your platform from the latest release and put
 it in `~/.cargo/bin` (`%USERPROFILE%\.cargo\bin` on Windows).
 
+**Desktop app (macOS 14+ only for now)**
+
+```sh
+brew install puniserv/tap/skillcask puniserv/tap/skillcask-app
+skillcask app                   # or open Skillcask from Applications
+```
+
+Install with the full names: Homebrew loads a third-party tap's cask only when it is named in full
+(or listed by `brew trust`); after that, `brew upgrade` takes the short name.
+
+Without Homebrew:
+
+```sh
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/puniserv/skillcask/releases/latest/download/skillcask-app-installer.sh | sh
+```
+
+The installer downloads `Skillcask-X.Y.Z-macos-universal.zip` (signed and notarized, with its own
+CLI inside) from the latest release, checks its sha256 and Gatekeeper's verdict, and moves the app
+to `/Applications`; an earlier copy goes to the Trash. It leaves a Homebrew install alone.
+`SKILLCASK_VERSION=X.Y.Z` picks a release, `SKILLCASK_APP_DIR` another folder.
+
+Linux and Windows have the terminal UI, `skillcask ui`. More in [macOS app](#macos-app).
+
 **npm, bun**
 
 ```sh
@@ -81,6 +104,24 @@ x64), checks its sha256 and its build provenance attestation, puts `skillcask` o
 it with `args`. It runs no other action. Used at a tag (`@vX.Y.Z`) it takes the version from the
 tag.
 
+### Update
+
+`skillcask self-update` reruns the release's installer when `skillcask-installer.sh` installed
+this binary (Linux, macOS); for any other install it prints the one command to run and exits 1.
+`SKILLCASK_SELF_UPDATE=0` makes it print the installer command too. By hand:
+
+```sh
+brew update && brew upgrade skillcask skillcask-app    # Homebrew (skillcask alone without the app)
+npm install -g skillcask@latest                        # npm (bun: bun add -g skillcask@latest)
+cargo install --locked skillcask                       # Cargo
+```
+
+The installer scripts (`skillcask-installer.sh`, `skillcask-installer.ps1`,
+`skillcask-app-installer.sh`) install the latest release when run again; the app's installer moves
+the earlier copy to the Trash. The app's own CLI updates with the app; Homebrew updates the app and
+the CLI on your `PATH` separately, which is why `brew upgrade` names both. For the GitHub Action,
+bump the pinned commit and `version`. `skillcask --version` prints what you have.
+
 ## Use
 
 ```sh
@@ -298,18 +339,24 @@ Every command except `publish`, `validate` and `projects` takes `-g, --global`.
 | `validate [paths…]` | Check `SKILL.md` files against the Agent Skills spec, see below. |
 | `projects [dirs…]` | Directories that hold `skills.toml` under the given ones (default: the current one), up to 6 levels down; hidden directories, `node_modules`, `vendor`, `target` and `Library` are skipped. |
 | `ui` | A terminal UI over the commands above: skills with their state and updates, `info`, SKILL.md and `audit` per skill, add, adopt (also offered when an add hits a skill skillcask does not manage), update (diff first), remove, doctor, a filter of the list, search of the registries (and skills.sh, asked once), the repositories in use (`R`, `S` turns skills.sh on or off) and a projects picker; `g` switches between the project and `--global`. |
+| `app` | Opens the macOS app (see [macOS app](#macos-app)); exits 1 when it is not installed, and on Linux and Windows. |
+| `self-check [--json]` | Whether a newer skillcask is released, from the `skillcask-app` cask file of the tap; one anonymous request, only when run; writes nothing. |
+| `self-update [--dry-run]` | Update skillcask: reruns the release's installer for an installer-script install (Linux, macOS), else prints the Homebrew, npm, cargo or app command and exits 1. `--dry-run` prints what would run. |
 | `<other>` | Runs `skillcask-<other>` from `PATH`, like git and cargo plugins. |
 
-`status`, `outdated`, `info`, `search`, `doctor`, `audit`, `projects` and `config` take `--json`: one JSON document on one line of
-stdout, with the same exit code; warnings and errors stay on stderr. Package text in it is
-escaped as in the terminal (`<U+202E>`). `status --json` has `repositories`
+`status`, `outdated`, `info`, `search`, `doctor`, `audit`, `projects`, `config` and
+`self-check` take `--json`: one JSON document on one line of stdout, with the same exit code;
+warnings and errors stay on stderr. Package text in it is escaped as in the terminal
+(`<U+202E>`). `status --json` has `repositories`
 (`[{"name", "type", "url", "allowed"}]`) and `skills-sh`; `search --json` results carry `source` (the repository
 name, or `skills.sh`) and `installs`, and the document has `"skills-sh": true|false|null` (`null`:
-never decided). For example `skillcask outdated --json | jq
+never decided). `self-check --json` is `{"version", "latest", "newer"}` (`latest` is `null` when
+the cask holds no readable version). For example `skillcask outdated --json | jq
 '.packages[] | select(.within != .locked)'`.
 
 Exit codes: 0 ok, 1 manifest/lock/status problems, 2 authentication, 3 network, 4 hash mismatch,
-5 IO or archive error.
+5 IO or archive error. `self-update` exits 1 when it updated nothing and printed the command to run;
+when it runs the installer, the installer's exit code is its own.
 
 Output is coloured in a terminal (`NO_COLOR` turns it off, `CLICOLOR_FORCE` on) and errors name
 the next step on a `hint:` line. For coding agents, `--agent` or `SKILLCASK_AGENT=1` prints terse,
@@ -448,6 +495,15 @@ too young falls back to an older commit when the server supports partial fetches
   and paths that collide by case or Unicode form fail a skill that contains them, and are
   skipped outside the selected skills.
 - No package code runs, ever. No telemetry.
+- `self-check` and the app's "Check for Updates…" send nothing but the request for the tap's cask
+  file, which carries the skillcask version in its User-Agent (`skillcask/<version>`): no token,
+  account, project or skill data; GitHub sees your IP address. The app checks
+  daily only after you say yes. `SKILLCASK_SELF_CHECK_URL` points it at a mirror (HTTPS only).
+- `self-update` sends the same request, then, for an installer-script install only, downloads that
+  release's `skillcask-installer.sh` the same way (`SKILLCASK_SELF_UPDATE_URL` replaces the
+  download base) and runs it with `/bin/sh`, without your `SKILLCASK_*`, `INSTALLER_*` and
+  `CARGO_DIST_*` variables. The script checks the archive's sha256 with `sha256sum`, so
+  `self-update` refuses to run it when `sha256sum` is not on `PATH`.
 - `add` and `update` (and `install` when it resolves) warn about characters a reviewer cannot
   see in the text files of new content: bidi controls (`U+202A`-`U+202E`, `U+2066`-`U+2069`,
   `U+200E`, `U+200F`, `U+061C`), zero-width characters (`U+200B`-`U+200D`, `U+2060`, `U+FEFF`) and
@@ -553,7 +609,23 @@ file through the GitLab raw files API
 project folder, see each skill's state, updates and audit findings, read its SKILL.md and diffs,
 and run `add` (also `--adopt`), `update`, `remove`, `install` and `doctor --fix`; its Settings
 change every key `skillcask -g config` lists. It has no package logic of its own: it runs the
-`skillcask` binary and reads its `--json` output.
+`skillcask` binary, 0.9.4 or newer, and reads its `--json` output.
+
+Install it with Homebrew, then open it from Applications or with `skillcask app`. The cask depends
+on the formula; name both, since Homebrew loads from a third-party tap only what it was asked for
+or what `brew trust` lists:
+
+```sh
+brew install puniserv/tap/skillcask puniserv/tap/skillcask-app
+```
+
+Every release also has `Skillcask-X.Y.Z-macos-universal.zip`, signed with a Developer ID and
+notarized (D50): unzip it into `/Applications`.
+
+The app tells you about a newer release but installs nothing ([Update](#update)). Its app menu
+has Check for Updates…, which runs `skillcask self-check`; it checks daily only after you say yes
+once (it asks in the sidebar; Settings › Updates switches it). A newer version gets a card and a
+sheet with the Homebrew command to copy, or the release page for a download (D51).
 
 `macos/bundle.sh` builds a universal `Skillcask.app` that carries its own CLI at
 `Contents/Helpers/skillcask`. Run outside a bundle (`swift run` from `macos/`), the app uses the

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT OR Apache-2.0",
       "name": "skillcask",
-      "version": "0.10.0"
+      "version": "0.10.2"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.10.0"
+  "version": "0.10.2"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/puniserv/skillcask/releases/download/v0.10.0"
+    "https://github.com/puniserv/skillcask/releases/download/v0.10.2"
   ],
   "bin": {
     "skillcask": "run-skillcask.js"
@@ -104,7 +104,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.10.0",
+  "version": "0.10.2",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"