paseo-plugin-machine-status 0.2.2 → 0.3.0

package/OVERVIEW.md

@@ -14,7 +14,7 @@ Machine Status shows what the daemon's Mac is doing while your agents work: CPU
 
 ## Setup
 
-- A macOS daemon on Paseo 0.8 to 0.13. On other platforms the screen says it cannot collect metrics.
+- A macOS daemon on Paseo 0.11 to 0.13. On other platforms the screen says it cannot collect metrics.
 - Docker Desktop, OrbStack or Rancher Desktop for the Docker tab. Without one, the tab says which is missing.
 
 ## What it can change

package/README.md

@@ -1,3 +1,5 @@
+<p align="center"><img src="assets/icon.png" width="88" alt=""></p>
+
 <h1 align="center">paseo-plugin-machine-status</h1>
 
 <p align="center">
@@ -7,19 +9,18 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/Paseo-0.8.x%20%E2%80%93%200.13.x-3987e5" alt="Supports Paseo 0.8.x through 0.13.x, including betas">
+  <a href="https://github.com/dutchakdev/paseo-plugin-machine-status/actions/workflows/ci.yml"><img src="https://github.com/dutchakdev/paseo-plugin-machine-status/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/paseo-plugin-machine-status"><img src="https://img.shields.io/npm/v/paseo-plugin-machine-status" alt="npm"></a>
+  <img src="https://img.shields.io/badge/Paseo-0.11.x%20%E2%80%93%200.13.x-3987e5" alt="Supports Paseo 0.11.x through 0.13.x, including betas">
   <img src="https://img.shields.io/badge/macOS-only-9aa1a6" alt="macOS only">
-  <img src="https://img.shields.io/badge/tests-237-199e70" alt="237 tests">
   <img src="https://img.shields.io/badge/dependencies-none-c98500" alt="No runtime dependencies">
   <img src="https://img.shields.io/badge/license-MIT-9aa1a6" alt="MIT licensed">
 </p>
 
 <p align="center">
-  <img src="docs/preview.svg" alt="The dashboard: KPI tiles, a load history chart, memory breakdown and disk usage" width="920">
+  <img src="docs/screenshot.png" alt="The Machine screen in the Paseo desktop app: CPU, memory, swap and disk tiles, load and memory history, disk and swap, and the top processes" width="920">
 </p>
 
-<p align="center"><sub>Generated by <code>npm run preview</code> from the plugin&apos;s own palette, thresholds and chart geometry, so the picture cannot drift from the code.</sub></p>
-
 One sidebar item, three tabs, and a pill beside the message box.
 
 > Requires macOS. Metrics come from `vm_stat`, `sysctl`, `df`, `pmset` and
@@ -28,18 +29,29 @@ One sidebar item, three tabs, and a pill beside the message box.
 
 ## Install
 
-```bash
-paseo plugin install npm:paseo-plugin-machine-status   # Paseo 0.9 and newer
-paseo plugin ls          # expect: running
-```
-
-Paseo 0.8 has no npm sources, so install from Git there:
-`paseo plugin add dutchakdev/paseo-plugin-machine-status`. Either way,
-`paseo plugin update machine-status` pulls later releases. The plugin supports **Paseo 0.8.x through 0.13.x, including betas**,
-on both the daemon, which runs its collectors, and the app, which runs its screens.
-
-The manifest remains `>=0.8.0`, which already admits 0.9.x through 0.13.x. Paseo also checks a
-prerelease's stable version core, so `0.13.0-beta.1` satisfies this range; see
+Plugins must be enabled daemon-wide first, under **Settings → Plugins → Enable
+plugins** (the root `pluginsEnabled` field in `~/.paseo/config.json`). Then pick the
+source that matches your Paseo:
+
+| Paseo | Source | Command |
+| ----- | ------ | ------- |
+| 0.11 and newer | [Plugin directory](https://paseo.sh/plugins), the reviewed version | `paseo plugin add dutchakdev/machine-status` |
+| 0.11 and newer | npm, the newest release before the directory approves it | `paseo plugin install npm:paseo-plugin-machine-status` |
+| 0.8 to 0.10, 0.11.0 betas | GitHub, release 0.2.3, the last one for these versions | `paseo plugin add dutchakdev/paseo-plugin-machine-status --ref v0.2.3` |
+
+`paseo plugin ls` should then show `machine-status` as `running`, and
+`paseo plugin update machine-status` pulls later releases from the same source. From
+Paseo 0.11 a bare `owner/name` names a directory entry, so a GitHub source there needs
+the `git:` prefix: `git:dutchakdev/paseo-plugin-machine-status`.
+
+The plugin supports **Paseo 0.11.x through 0.13.x, including betas**, on both the
+daemon, which runs its collectors, and the app, which runs its screens.
+
+The manifest asks for `>=0.11.0` because it declares the icon shown in the plugin
+directory, and Paseo 0.8 to 0.10 refuse a manifest with a field they do not know.
+Paseo also checks a prerelease's stable version core, so `0.13.0-beta.1` satisfies
+this range. The 0.11.0 betas pass that check but predate the `icon` field, so they
+refuse the manifest as well and need the release named in the install table; see
 [version requirements](https://paseo.sh/docs/plugins/reference#requirements).
 
 To work on it locally instead:
@@ -53,9 +65,6 @@ paseo plugin install "$PWD"
 paseo plugin ls          # expect: running
 ```
 
-Plugins must be enabled daemon-wide first, under **Settings → Plugins → Enable
-plugins** (the root `pluginsEnabled` field in `~/.paseo/config.json`).
-
 Open it from the **Machine** sidebar item, or ⌘K → "Machine status". On Paseo 0.11
 and newer, ⌘K also offers "Machine: ports & services" and "Machine: Docker", which
 open straight on that tab, and the tab travels in the screen's link (`?tab=services`,
@@ -160,6 +169,12 @@ a documented anti-pattern.
 
 ### Colour
 
+<p align="center">
+  <img src="docs/preview.png" alt="The dashboard drawn from sample data: KPI tiles, a load history chart, memory breakdown and disk usage" width="920">
+</p>
+
+<p align="center"><sub>Generated by <code>npm run preview</code> from sample data and the plugin&apos;s own palette, thresholds and chart geometry, so the colours cannot drift from the code.</sub></p>
+
 Chrome (backgrounds, text, borders) comes from Paseo's six theme tokens. Series
 colour does not: a categorical hue has to stay the same hue across themes or it
 stops identifying anything. Paseo never says which theme is active, so the plugin
@@ -335,6 +350,7 @@ npm run check                         # typecheck, then the tests
 paseo plugin reload machine-status    # source edits need an explicit reload
 paseo plugin logs machine-status
 npm run preview                       # regenerates docs/preview.svg from the real palette
+./scripts/preview-png.sh              # renders it to docs/preview.png for the plugin directory
 ```
 
 Tests cover the command-output parsers against captured real output, the path and
@@ -349,13 +365,16 @@ including a refusal to terminate the test runner itself.
 ### Paseo versions
 
 The SDK stays pinned to 0.8.0 for typechecking and tests, so the compiler proves
-the plugin uses only the oldest supported API. Paseo supplies the runtime instances
-on every supported release line, so none of it ships with the plugin.
+the plugin uses only the 0.8 API, which every supported release still provides.
+Paseo supplies the runtime instances on every supported release line, so none of
+it ships with the plugin.
 
 Paseo 0.11 replaced surfaces with screens and kept the old calls as deprecated
-aliases. The manifest still admits 0.8, and each connected app evaluates the client
-entry against its own version, so `client/compat.tsx` describes the 0.11 additions
-locally and calls them only after checking that the app has them:
+aliases. Up to 0.2.3 the manifest admitted 0.8, and each connected app evaluates the
+client entry against its own version, so `client/compat.tsx` describes the 0.11
+additions locally and calls them only after checking that the app has them. Since the
+manifest asks for 0.11, every app that loads the plugin takes the first row; the
+fallback stays in the code until it is removed on its own:
 
 | App version | Screen | Sidebar | Opens with | Tab shortcuts in ⌘K |
 | ----------- | ------ | ------- | ---------- | ------------------- |

package/index.server.ts

@@ -6,13 +6,14 @@ import {
   pruneDockerHandler,
   readContainerLogsHandler,
   readDockerHandler,
+  removeImageHandler,
 } from "./server/docker";
 import { explainProcessHandler } from "./server/explain";
 import { readMetricsHandler } from "./server/metrics";
 import { killProcessHandler, listProcessesHandler } from "./server/processes";
 import { readServicesHandler } from "./server/services";
 import { applyCleanup, killProcess, listProcesses, planCleanup, readMetrics } from "./shared/contracts";
-import { controlContainer, controlEngine, pruneDocker, readContainerLogs, readDocker } from "./shared/docker";
+import { controlContainer, controlEngine, pruneDocker, readContainerLogs, readDocker, removeImage } from "./shared/docker";
 import { explainProcess } from "./shared/explain";
 import { readServices } from "./shared/services";
 
@@ -34,6 +35,7 @@ export default function contribute(server: PluginServerContext) {
   server.handle(controlEngine, controlEngineHandler);
   server.handle(readContainerLogs, readContainerLogsHandler);
   server.handle(pruneDocker, pruneDockerHandler);
+  server.handle(removeImage, removeImageHandler);
 
   // No timers, watchers or sockets are created at registration time, so there is
   // nothing to release. Paseo removes the handlers and stops the subprocess.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-plugin-machine-status",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Machine dashboard, open ports and Docker control inside Paseo",
   "license": "MIT",
   "author": "dutchakdev",
@@ -43,6 +43,7 @@
   "files": [
     "paseo-plugin.json",
     "OVERVIEW.md",
+    "assets/icon.png",
     "index.client.tsx",
     "index.server.ts",
     "client/",

package/paseo-plugin.json

@@ -1,4 +1,5 @@
 {
   "id": "machine-status",
-  "requirements": { "paseo": ">=0.8.0" }
+  "icon": "assets/icon.png",
+  "requirements": { "paseo": ">=0.11.0" }
 }

package/shared/docker.ts

@@ -22,6 +22,14 @@ export const DockerUsageRowSchema = z.object({
   safeToReclaim: z.boolean(),
 });
 
+/**
+ * The ids this plugin hands the client come from `{{.ID}}` in `docker ps` and
+ * `docker images`: hex, 12 characters, or 64 untruncated. Anything else, such
+ * as `--force`, would reach the Docker CLI as an argument, so it is refused at
+ * the contract rather than trusted because the client normally sends an id.
+ */
+export const DockerIdSchema = z.string().regex(/^[0-9a-f]{12,64}$/, "Expected a Docker id");
+
 export const DockerImageSchema = z.object({
   id: z.string(),
   reference: z.string(),
@@ -62,7 +70,7 @@ export const controlEngine = defineRpc({
 export const readContainerLogs = defineRpc({
   name: "docker.logs",
   input: z.object({
-    id: z.string().min(1),
+    id: DockerIdSchema,
     lines: z.number().int().min(10).max(500).default(120),
   }),
   output: z.object({ ok: z.boolean(), text: z.string(), error: z.string().nullable() }),
@@ -70,14 +78,14 @@ export const readContainerLogs = defineRpc({
 
 export const removeImage = defineRpc({
   name: "docker.image.remove",
-  input: z.object({ id: z.string().min(1) }),
+  input: z.object({ id: DockerIdSchema }),
   output: z.object({ ok: z.boolean(), error: z.string().nullable() }),
 });
 
 export const controlContainer = defineRpc({
   name: "docker.control",
   input: z.object({
-    id: z.string().min(1),
+    id: DockerIdSchema,
     action: z.enum(["start", "stop", "restart", "remove"]),
   }),
   output: z.object({ ok: z.boolean(), error: z.string().nullable() }),