release: v1.3.3 — hkm uninstall, and fixing how commands talk to the shell

.github/dependabot.yml

@@ -0,0 +1,28 @@
+# Keeps GitHub Actions current so a runtime deprecation is a pull request, not a
+# warning nobody sees.
+#
+# The Node 20 deprecation is the case this exists for: five actions kept working
+# while the runners forced them onto Node 24, and the only signal was a notice in
+# the log of a workflow that still passed. Pinned majors do not rot loudly — they
+# rot silently until the forced runtime is withdrawn and every workflow fails at
+# once. A weekly PR turns that into something reviewable.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    commit-message:
+      # Matches the Conventional Commits style the rest of the history uses, so
+      # these land in the CHANGELOG tooling like anything else.
+      prefix: ci
+    labels:
+      - dependencies
+    groups:
+      # One PR for all of them: they are bumped together in practice (upload and
+      # download artifact must stay compatible), and five separate PRs for the
+      # same deprecation is five reviews of the same decision.
+      actions:
+        patterns:
+          - "*"

.github/workflows/php-analysis.yml

@@ -79,7 +79,7 @@ jobs:
           SEMGREP_RULES: "p/php p/security-audit p/secrets"
       - name: Upload SARIF to code scanning
         if: always()
-        uses: github/codeql-action/upload-sarif@v3
+        uses: github/codeql-action/upload-sarif@v4
         with:
           sarif_file: semgrep.sarif
           category: semgrep

.github/workflows/release.yml

@@ -66,12 +66,12 @@ jobs:
       # TWO artifacts. The tarball is the DEFAULT install path — user-local,
       # no root (tools/install.sh). The .deb is for multi-user machines and CI
       # images where a system-wide install and apt-managed PHP are the point.
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v7
         with: { name: linux-tarball, path: dist/*linux*.tar.gz }
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v7
         with: { name: linux-deb, path: dist/*.deb }
       # Published alongside the assets so `curl | sh` works without a checkout.
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v7
         with: { name: installer, path: tools/install.sh }
 
   # ── Windows: .zip (x86_64, cross-compiled) ────────────────────────────────
@@ -89,7 +89,7 @@ jobs:
         with: { php-version: "8.4", tools: composer }
       - name: Bundle (windows)
         run: VERSION="${RELEASE_VERSION:-${GITHUB_REF_NAME#v}}" ./tools/bundle.sh windows
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v7
         with: { name: windows-zip, path: dist/*.zip }
 
   # ── macOS: universal .app tarball (arm64 + x86_64), built ON LINUX ─────────
@@ -109,7 +109,7 @@ jobs:
         with: { php-version: "8.4", tools: composer }
       - name: Bundle (macos)
         run: VERSION="${RELEASE_VERSION:-${GITHUB_REF_NAME#v}}" ./tools/bundle.sh macos
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v7
         with: { name: macos-app, path: dist/*.tar.gz }
 
   # ── Publish GitHub Release with all artifacts ─────────────────────────────
@@ -119,7 +119,7 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v5      # need CHANGELOG.md at the checked-out commit
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@v8
         with: { path: artifacts/ }
       - name: Resolve version + extract CHANGELOG section
         id: notes
@@ -137,7 +137,7 @@ jobs:
           else
             echo "No CHANGELOG entry for $VERSION — using auto-generated notes only."
           fi
-      - uses: softprops/action-gh-release@v2
+      - uses: softprops/action-gh-release@v3
         with:
           # When called from auto-release the ref is a branch, so name the tag
           # explicitly; on a tag push this matches GITHUB_REF_NAME anyway.

CHANGELOG.md

@@ -6,6 +6,105 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.3] - 2026-08-18
+
+Follows 1.3.2 within a day, and the theme is narrower: 1.3.2 fixed *which*
+kernel a command acts on, this one fixes *how* commands talk to the shell around
+them, plus a full uninstall. An audit of the Zig toolchain drove it — every item
+below was reproduced against the shipped `--release=small` binary.
+
+### Added
+- **`hkm uninstall`** — removes every hkm install on the machine (both kernels,
+  both pairs of launchers, the pre-1.4 user kernel, `~/.config/hkm` and the
+  shared plugin store) and deregisters the `.deb` from dpkg, while keeping **your
+  projects and the project registry**. Those two are protected by construction,
+  not by a filter: every path it can delete is computed from the install layout,
+  so a project directory cannot enter the plan at all; and `projects.json` +
+  `platform.json` are rescued out of a kernel tree into the userdata directory
+  *before* anything is deleted, so the registry survives even when its only copy
+  was inside the tree being removed. `--dry-run` prints the plan and exits;
+  system paths are reported rather than silently skipped when not root.
+
+### Changed
+- `hkm doctor` and `hkm version` share one PATH lookup with the launcher
+  passthrough (`util.findOnPath`). Three private copies of "which binary would
+  actually run" is three chances to disagree.
+- **CI actions moved off the deprecated Node 20 runtime.** `upload-artifact`
+  v5→v7, `download-artifact` v5→v8, `codeql-action/upload-sarif` v3→v4 and
+  `action-gh-release` v2→v3 all declared `node20`, which the runners were
+  already forcing onto Node 24. A `.github/dependabot.yml` now watches the
+  `github-actions` ecosystem weekly and groups the bumps into one PR, so the
+  next runtime deprecation arrives as a reviewable change rather than a notice
+  in the log of a workflow that still passes.
+
+### Fixed
+- **Command output went to stderr, so nothing could be piped.** The whole
+  `prompt` renderer used `std.debug.print`, which writes to stderr — so
+  `hkm list > projects.txt` produced an empty file and a command's results were
+  indistinguishable from its errors. Results (`intro`/`section`/`item`/`ok`/
+  `muted`/`note`/`table`/`outro`) now go to **stdout**; `err`/`warn` and every
+  interactive prompt stay on **stderr**. This was found once before and fixed a
+  single function wide (`banner.printShort`); the cause was in the shared
+  renderer all along.
+- **ANSI escapes were emitted unconditionally and `NO_COLOR` was ignored**, so
+  colour codes landed in redirected output, log files and CI transcripts.
+  Colour is now decided per stream from the rule `tools/install.sh` already
+  applied: off when `NO_COLOR` is set, when `TERM=dumb`, or when that stream is
+  not a terminal.
+- **Tables truncated to 80 columns when redirected.** `termCols()` falls back to
+  80 whenever the `ioctl` fails — exactly the non-TTY case — so piping cut the
+  end off every long path, with the `…` as the only clue. Truncation now applies
+  only when stdout really is a terminal.
+- **A mistyped command printed a raw Zig error.** Anything not handled natively
+  is forwarded to the PHP CLI, and a spawn failure propagated out of `main` as
+  `error: FileNotFound` — no filename, no mention of PHP, no pointer to
+  `hkm doctor`. The three causes (no PHP, no kernel CLI, an unknown command) are
+  now told apart and each names its own fix.
+- **Unknown flags were silently ignored, which inverted a destructive command.**
+  Every command parsed the flags it knew and dropped the rest. The token most
+  likely to be misspelled is the one that makes a command safe, so
+  `hkm uninstall --dryrun --yes` parsed as "no dry run, and don't ask" and
+  deleted the install without a prompt. `uninstall` and `upgrade` now reject
+  anything they do not recognise before acting on anything they do.
+- **`projects.json` and `plugins.lock.json` were written non-atomically.**
+  `writeFile` truncates before writing, so a process killed part way through — or
+  a full disk — left a truncated registry rather than the previous one. Both now
+  write a sibling temp file and `rename()` over the target, the same pattern
+  `install.sh` and the launcher install already used.
+- **Every unknown long option crashed the CLI parser.** `php-io-cli`'s
+  long-option branch recorded a different array shape than its two siblings, and
+  `rejectUnknownOptions()` reads the key it omitted — so the feature meant to
+  suggest a correction raised `TypeError: suggestOption(): Argument #1 ($name)
+  must be of type string, null given` on every unknown `--flag`. Fixed upstream
+  (php-io-cli `b1dd657`) rather than pinned back, so the handling stays in.
+- **`hkm uninstall` could destroy the registry it promises to keep** (found in
+  review). Two holes: `HKM_USERDATA_DIR` may point INSIDE a deletion target —
+  `/opt/hkm-kernel/projects` is the obvious case — so the plan listed it under
+  "Will KEEP" and deleted its parent moments later; and `rescueRegistry`
+  swallowed every write failure, so a failed rescue was followed by the delete
+  anyway while the command reported success. It now refuses the first layout
+  outright and aborts before removing anything if the rescue fails. Rescued
+  files are written atomically.
+- **Output fixes that had gaps of their own** (found in review): `hkm-config
+  print` still wrote the config to stderr; a line longer than 8 KiB fell back to
+  `std.debug.print` and silently changed stream; remediation text printed after
+  an error went to stdout, splitting one message across two streams;
+  `writeFileAtomic` used a fixed temp name two processes could collide on;
+  `findOnPath` skipped empty `PATH` entries, which POSIX defines as the current
+  directory; the passthrough blamed a missing PHP for a missing kernel CLI; and
+  `--` ended flag VALIDATION but not flag PARSING, so `hkm upgrade -- --system`
+  still selected the system scope.
+- **A failed `.deb` install could still report success.** The fallback path
+  treated `apt-get -f install` exiting 0 as evidence the package had landed, but
+  it exits 0 whenever it finds nothing to repair — so a `dpkg -i` that failed for
+  any non-dependency reason (a truncated download, a corrupt `.deb`) was reported
+  as "updated" with the previous kernel still installed. The dependency repair is
+  now followed by a second `dpkg -i`, and that result alone is the verdict.
+- **`prompt.item` padded by byte count**, so a key containing any multi-byte
+  glyph shifted its description column left — a single `→` misaligned the row by
+  two. It now measures display width using the helper already written for
+  `table()`.
+
 ## [1.3.2] - 2026-08-17
 
 Fixes a class of failure that made installing or upgrading on a machine with an

tools/README.md

@@ -146,6 +146,40 @@ So a pin still works wherever it was actually needed; it no longer overrides an
 install sitting next to the binary. `hkm-config check` writes one only when
 self-location failed, and `hkm-config unset HKM_KERNEL_HOME` clears a stale one.
 
+### `hkm uninstall` — remove everything, keep the projects
+
+```sh
+hkm uninstall --dry-run    # print the plan, delete nothing
+hkm uninstall              # everything this user can remove
+sudo hkm uninstall         # …including the .deb under /opt + /usr/bin
+```
+
+| Removed | Kept |
+|---|---|
+| `/opt/hkm-kernel`, `~/.local/lib/hkm-kernel`, the pre-1.4 user kernel | **your projects**, wherever they live |
+| `/usr/bin/{hkm,hkm-config}`, `~/.local/bin/{hkm,hkm-config}` | **`projects.json`** + **`platform.json`** |
+| `~/.config/hkm` (config.env), the shared plugin store | |
+| the `hkm-kernel` dpkg registration (`remove`, never `purge`) | |
+
+The two kept items are protected **by construction, not by a filter**:
+
+- Every path the command can delete is *computed* from the install layout. None
+  is read from the registry, the working directory, or an argument — so a
+  project directory cannot appear in the plan at all.
+- `projects.json` and `platform.json` are **rescued into the userdata directory
+  before anything is deleted**, so the registry survives even when its only copy
+  was inside the kernel tree being removed. Reinstall later and `hkm list` still
+  shows every project.
+
+Two rules in the rescue exist because testing found them the hard way: it only
+copies from a tree it is *actually removing*, and it prefers the user's kernel
+over the system one. The `.deb` ships `projects/projects.json` as `{}` (a
+packaged conffile), and without both rules that empty default won the race to the
+destination and shadowed the user's real project list.
+
+`tools/install.sh --uninstall` remains deliberately narrow — it removes only what
+that script installed, at that prefix. `hkm uninstall` is the full removal.
+
 ### `hkm upgrade --local`
 
 Installs the current checkout over an installed kernel, obeying the same scope

tools/install.sh

@@ -73,13 +73,20 @@ done
 
 # ── uninstall ───────────────────────────────────────────────────────────────
 if [ "$DO_UNINSTALL" -eq 1 ]; then
+  # Deliberately NARROW: this removes only what this script installed, at this
+  # prefix. It does not touch a system (.deb) install, the pre-1.4 user kernel,
+  # the config file or the plugin cache — `hkm uninstall` does all of that, and
+  # rescues the project registry out of any kernel tree before deleting it.
   say "Removing $DEST"
   rm -rf "$DEST"
   rm -f "$BINDIR/hkm" "$BINDIR/hkm-config"
   ok "Removed. Your data was left alone:"
   printf '    %s\n    %s\n' "${XDG_CONFIG_HOME:-$HOME/.config}/hkm" \
                             "${XDG_DATA_HOME:-$HOME/.local/share}/hkm"
-  printf '  Delete those too if you want a clean slate.\n'
+  printf '\n  For a FULL removal — every install on this machine, the config and\n'
+  printf '  the plugin cache, while keeping your projects and projects.json:\n'
+  printf '      hkm uninstall --dry-run    # see the plan first\n'
+  printf '      hkm uninstall              # then do it (sudo for the .deb too)\n'
   exit 0
 fi
 

tools/src/commands/doctor.zig

@@ -56,31 +56,11 @@ fn mark(present: bool) []const u8 {
     return if (present) OK else MISSING;
 }
 
-/// Locate an executable by walking PATH. Returns the FIRST match, which is the
-/// one that would actually run.
-fn findOnPath(allocator: std.mem.Allocator, io: Io, env: *EnvMap, name: []const u8) ?[]const u8 {
-    const path = env.get("PATH") orelse return null;
-    var it = std.mem.splitScalar(u8, path, ':');
-    while (it.next()) |dir| {
-        if (dir.len == 0) continue;
-        const cand = std.fs.path.join(allocator, &.{ dir, name }) catch continue;
-        if (util.fileExists(io, cand)) return cand;
-    }
-    return null;
-}
-
-/// Every match on PATH, in order — used to detect one install shadowing another.
-fn countOnPath(allocator: std.mem.Allocator, io: Io, env: *EnvMap, name: []const u8) usize {
-    const path = env.get("PATH") orelse return 0;
-    var n: usize = 0;
-    var it = std.mem.splitScalar(u8, path, ':');
-    while (it.next()) |dir| {
-        if (dir.len == 0) continue;
-        const cand = std.fs.path.join(allocator, &.{ dir, name }) catch continue;
-        if (util.fileExists(io, cand)) n += 1;
-    }
-    return n;
-}
+// findOnPath / countOnPath now live in lib/util.zig — doctor, version and the
+// passthrough diagnostic in main.zig all needed the same walk, and three copies
+// of "which binary would actually run" is three chances to disagree.
+const findOnPath = util.findOnPath;
+const countOnPath = util.countOnPath;
 
 fn dirOnPath(env: *EnvMap, dir: []const u8) bool {
     const path = env.get("PATH") orelse return false;