@rxtx4816/cockpit-plugin-base-react 1.0.1 → 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RXTX4816
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @rxtx4816/cockpit-plugin-base-react
+
+Shared foundation for building [Cockpit](https://cockpit-project.org/) plugins with React and PatternFly v6. Extracts the boilerplate that every plugin needs — bootstrapping, i18n, dark theme, async patterns, systemd integration, shared tooling config, and a full QEMU VM test harness — so each plugin only contains its own logic.
+
+## What's included
+
+**Plugin runtime**
+- `bootstrapPlugin` — mounts your React app into the Cockpit frame with i18n and error boundary wired up
+- `dark-theme` — side-effect module that automatically syncs the `pf-v6-theme-dark` class with the Cockpit shell, responding to user preference changes and system theme
+- `initCockpitI18n` — sets up i18next with Cockpit's locale loading conventions
+
+**Hooks**
+- `useAsyncAction` — wraps an async operation with `loading`, `error`, and `execute` state; ideal for buttons that trigger backend calls
+- `useAutoRefresh` — runs a callback on a configurable interval, with manual refresh support
+- `useAsyncStream` — consumes a Cockpit channel as a line-buffered async stream
+- `useConfirmAction` — multi-step confirmation flow with typed state transitions
+- `usePollingFetch` — fetch with automatic polling, refresh, and loading state
+
+**Components**
+- `ConfirmDialog` — confirmation modal driven by `useConfirmAction`, supports multi-step flows
+- `ErrorBoundary` — catches render errors and shows a PatternFly alert with details
+- `HelpPopover` — PatternFly popover for contextual help text
+- `LogViewer` — scrollable terminal-style log display backed by an async stream
+- `StatusBadge` — color-coded badge for service or resource states
+- `ToastProvider` + hook — global toast notification system
+
+**Systemd layer**
+- `useServiceStatus` — reactive hook for a systemd service state (active, failed, inactive…)
+- `ServiceControl` — start/stop/restart/enable control component
+- `api` — typed wrappers around `cockpit.spawn` for systemctl operations
+
+**Shared tooling config**
+- `tsconfig.base.json` — TypeScript base config tuned for Cockpit plugins
+- `eslint.config.base` — `createEslintConfig()` factory with TS, React, and react-hooks rules
+- `vitest.config.base` — Vitest base config with jsdom and PatternFly setup
+
+**Testing utilities**
+- Vitest setup file that installs jsdom and jest-dom matchers
+- `mockCockpit` — in-memory Cockpit API mock for unit tests
+- `mockHttpClient` — mock for Cockpit HTTP client used in tests
+
+**QEMU VM test harness**
+- `npm run vm` — spins up real cloud VMs (Arch, Debian, Fedora) with Cockpit installed and your plugin mounted via virtfs. Used for end-to-end testing against a live Cockpit instance. See [VM Testing](docs/wiki/VM-Testing.md).
+
+**Reusable CI/CD workflows**
+- Lint, typecheck, test, and build on every push
+- RPM, DEB, and Arch package build verification
+- Semantic version bumping from conventional commits
+- Automated release asset upload and AUR publishing
+- GitHub Wiki sync from `docs/wiki/`
+
+## Install
+
+```bash
+npm install @rxtx4816/cockpit-plugin-base-react
+```
+
+Peer dependencies: `react >=19`, `react-dom >=19`, `i18next >=26`, `react-i18next >=17`
+
+## Quick start
+
+```tsx
+// src/index.tsx
+import "./i18n";
+import "@rxtx4816/cockpit-plugin-base-react/dark-theme";
+import { bootstrapPlugin } from "@rxtx4816/cockpit-plugin-base-react/bootstrap";
+import App from "./App";
+
+bootstrapPlugin(App);
+```
+
+For full setup guidance, config sharing, and workflow integration see the [wiki](docs/wiki/Home.md).
+
+## Documentation
+
+- [Getting Started](docs/wiki/Getting-Started.md)
+- [Hooks](docs/wiki/Hooks.md)
+- [Components](docs/wiki/Components.md)
+- [Systemd Layer](docs/wiki/Systemd.md)
+- [Testing](docs/wiki/Testing.md)
+- [VM Testing](docs/wiki/VM-Testing.md)
+- [CI/CD Workflows](docs/wiki/CI-CD.md)
+
+## License
+
+MIT © 2026 RXTX4816

package/docs/wiki/CI-CD.md

@@ -0,0 +1,87 @@
+# CI/CD Workflows
+
+The package ships reusable GitHub Actions workflows that plugins call with `uses:`. This keeps CI logic in one place and lets all plugins inherit fixes and improvements automatically.
+
+## Using the workflows
+
+In your plugin's `.github/workflows/`:
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    uses: RXTX4816/cockpit-plugin-base-react/.github/workflows/ci-plugin.yml@main
+    with:
+      plugin-name: cockpit-caddy
+```
+
+---
+
+## Available workflows
+
+### ci-plugin.yml
+
+Runs on every push and pull request. Steps: lint → typecheck → test → build → verify build output.
+
+Required inputs:
+- `plugin-name` — used to verify `src/main.js` and `src/main.css` exist after build
+
+### pkg-ci-plugin.yml
+
+Builds and verifies RPM, DEB, and Arch packages using a placeholder `0.0.0` version. Confirms that the packaging definitions (`.spec`, `debian/`, `PKGBUILD`) are valid before a real release.
+
+Required inputs:
+- `plugin-name`
+- `spec-file` — path to the RPM spec file (e.g. `cockpit-caddy.spec`)
+- `aur-pkgname` — AUR package name
+
+### semantic-release-plugin.yml
+
+Determines the next version from conventional commits since the last git tag and creates the tag. Does not build or publish anything — it only tags. The tag then triggers whatever release workflow you have listening on `push.tags`.
+
+Version bump rules:
+- `BREAKING CHANGE` anywhere in a commit body → major
+- `feat:` prefix → minor
+- anything else → patch
+- no commits since last tag → skip (exits 0, no tag created)
+
+Required secrets:
+- `RELEASE_TOKEN` — a GitHub token with `contents: write` permission
+
+Optional inputs:
+- `initial_version` — version to use when no prior tag exists (default: `v1.0.0`)
+
+### release-plugin.yml
+
+Builds release assets (tarball + sha256, RPM, DEB) and uploads them to a GitHub release. Also updates the `PKGBUILD` and pushes to AUR.
+
+Required inputs:
+- `plugin-name`, `spec-file`, `aur-pkgname`
+- `maintainer-name`, `maintainer-email`
+
+Required secrets:
+- `AUR_SSH_KEY` — SSH private key registered with the AUR account
+- `RELEASE_TOKEN` — GitHub token with `contents: write`
+
+### sync-wiki-plugin.yml
+
+Copies all `.md` files from `docs/wiki/` in your plugin repo to the GitHub Wiki. Triggered by push to main.
+
+No inputs or secrets required beyond the default `GITHUB_TOKEN`.
+
+---
+
+## Secrets reference
+
+| Secret | Used by | Description |
+|---|---|---|
+| `RELEASE_TOKEN` | semantic-release, release | GitHub PAT with `contents: write` |
+| `AUR_SSH_KEY` | release | SSH private key for AUR pushes |
+| `NPM_TOKEN` | (base package only) | npm automation token for publishing |

package/docs/wiki/Components.md

@@ -0,0 +1,56 @@
+# Components
+
+All components are exported from the components entrypoint:
+
+```ts
+import { ConfirmDialog, ErrorBoundary, HelpPopover, LogViewer, StatusBadge, ToastProvider } from "@rxtx4816/cockpit-plugin-base-react/components";
+```
+
+`ToastProvider` is mounted automatically by `bootstrapPlugin`. The others are available for use anywhere in your plugin.
+
+---
+
+## ConfirmDialog
+
+A PatternFly modal dialog driven by `useConfirmAction` state. Supports multi-step confirmation flows — for example, showing a warning first and requiring the user to type a resource name before proceeding.
+
+Receives the `state` and `cancel` from `useConfirmAction` and renders the appropriate step content.
+
+---
+
+## ErrorBoundary
+
+A React error boundary that catches render errors anywhere in the component tree and displays a PatternFly alert with the error message and stack trace. Prevents the entire plugin from going blank on an unexpected error.
+
+Mounted automatically by `bootstrapPlugin`, but can also be used to wrap specific subtrees.
+
+---
+
+## HelpPopover
+
+A small PatternFly popover for contextual help. Renders a help icon button that opens a popover with a title and body text. Use it next to form fields or section headings to explain non-obvious behaviour.
+
+---
+
+## LogViewer
+
+A scrollable, terminal-style log display that accepts an array of output lines (typically from `useAsyncStream`). Automatically scrolls to the bottom on new output. Used for displaying real-time command output or service journal entries.
+
+---
+
+## StatusBadge
+
+A color-coded label for service or resource states. Maps state strings (e.g. `"active"`, `"failed"`, `"inactive"`, `"unknown"`) to PatternFly status colors. Used by `ServiceControl` and can be used standalone wherever you need to display a state.
+
+---
+
+## ToastProvider
+
+Global toast notification context. Wrap your app with `ToastProvider` (done automatically by `bootstrapPlugin`) and use the `useToast` hook to fire notifications from anywhere:
+
+```ts
+const { addToast } = useToast();
+addToast({ title: "Saved", variant: "success" });
+```
+
+Toasts are displayed in the top-right corner and auto-dismiss after a configurable timeout.

package/docs/wiki/Getting-Started.md

@@ -0,0 +1,92 @@
+# Getting Started
+
+## Installation
+
+```bash
+npm install @rxtx4816/cockpit-plugin-base-react
+```
+
+Peer dependencies required in your plugin:
+
+```bash
+npm install react react-dom i18next react-i18next
+```
+
+---
+
+## Bootstrapping your plugin
+
+Every Cockpit plugin needs an entry point that initialises i18n, the dark theme, and mounts React. This package handles all of it:
+
+```tsx
+// src/index.tsx
+import "./i18n";
+import "@rxtx4816/cockpit-plugin-base-react/dark-theme";
+import { bootstrapPlugin } from "@rxtx4816/cockpit-plugin-base-react/bootstrap";
+import App from "./App";
+
+bootstrapPlugin(App);
+```
+
+`bootstrapPlugin` wraps your app in an `ErrorBoundary` and a `ToastProvider`, then mounts it into the `#app` element that Cockpit expects.
+
+---
+
+## i18n setup
+
+Create `src/i18n.ts` in your plugin:
+
+```ts
+import { initCockpitI18n } from "@rxtx4816/cockpit-plugin-base-react/i18n";
+
+initCockpitI18n();
+```
+
+This sets up i18next with Cockpit's locale loading conventions so `useTranslation()` works throughout your plugin.
+
+---
+
+## Shared tooling config
+
+Extend from the base configs so all plugins stay consistent.
+
+**tsconfig.json**
+```json
+{
+  "extends": "@rxtx4816/cockpit-plugin-base-react/tsconfig.base.json",
+  "compilerOptions": {
+    "paths": {}
+  }
+}
+```
+
+**eslint.config.js**
+```js
+import { createEslintConfig } from "@rxtx4816/cockpit-plugin-base-react/eslint.config.base";
+
+export default createEslintConfig();
+```
+
+Pass extra globals if your plugin uses custom Cockpit types:
+```js
+export default createEslintConfig({ CockpitHttpClient: "readonly" });
+```
+
+**vitest.config.ts**
+```ts
+import { defineConfig } from "@rxtx4816/cockpit-plugin-base-react/vitest.config.base";
+
+export default defineConfig();
+```
+
+---
+
+## Dark theme
+
+Importing the `dark-theme` side-effect module is all that's needed. It listens for three signals and keeps the `pf-v6-theme-dark` class on `<html>` in sync:
+
+- `localStorage` key `shell:style` (values: `"light"`, `"dark"`, `"auto"`)
+- The custom `cockpit-style` event dispatched by the Cockpit shell switcher
+- The OS-level `prefers-color-scheme` media query
+
+No configuration required.

package/docs/wiki/Home.md

@@ -0,0 +1,13 @@
+# cockpit-plugin-base-react Wiki
+
+This wiki covers everything you need to build, test, and ship Cockpit plugins using `@rxtx4816/cockpit-plugin-base-react`.
+
+## Contents
+
+- [Getting Started](Getting-Started.md) — install, bootstrap, and first plugin setup
+- [Hooks](Hooks.md) — async state, polling, streams, confirmation flows
+- [Components](Components.md) — UI building blocks: toasts, dialogs, logs, badges
+- [Systemd Layer](Systemd.md) — service status, control, and typed API wrappers
+- [Testing](Testing.md) — unit testing with mocked Cockpit and HTTP client
+- [VM Testing](VM-Testing.md) — end-to-end testing with real QEMU VMs
+- [CI/CD Workflows](CI-CD.md) — reusable GitHub Actions for builds, packages, and releases

package/docs/wiki/Hooks.md

@@ -0,0 +1,58 @@
+# Hooks
+
+All hooks are exported from the main entrypoint:
+
+```ts
+import { useAsyncAction, useAutoRefresh, useAsyncStream, useConfirmAction, usePollingFetch } from "@rxtx4816/cockpit-plugin-base-react";
+```
+
+---
+
+## useAsyncAction
+
+Wraps an async operation with `loading`, `error`, and `execute` state. Designed for buttons or forms that trigger backend calls.
+
+The hook returns an object with:
+- `execute(...args)` — triggers the operation
+- `loading` — true while the operation is in progress
+- `error` — the caught error if the operation failed, or null
+- `reset()` — clears error state
+
+Errors are caught automatically; unhandled promise rejections do not propagate to the component tree.
+
+---
+
+## useAutoRefresh
+
+Runs a callback on a configurable interval. Returns a `refresh()` function for on-demand triggering and a `loading` flag.
+
+Useful for periodically re-fetching data without managing `setInterval` lifecycle yourself. The interval is cleared on unmount.
+
+---
+
+## useAsyncStream
+
+Consumes a Cockpit channel as a line-buffered async stream. Returns the accumulated output lines and an `error` state.
+
+Used internally by `LogViewer` and useful anywhere you need to display or process real-time output from a spawned process.
+
+---
+
+## useConfirmAction
+
+Manages a multi-step confirmation flow with typed state transitions. Returns:
+
+- `state` — current step or `null` when idle
+- `start(initialStep)` — opens the flow
+- `next(step)` — advances to the next step
+- `cancel()` — resets to idle
+
+Pairs with `ConfirmDialog` to build destructive action flows (e.g. delete with a typed confirmation).
+
+---
+
+## usePollingFetch
+
+Fetches a resource with automatic polling and returns `{ data, loading, error, refresh }`. The poll interval is configurable.
+
+Handles the full lifecycle: initial fetch, polling, cleanup on unmount, and error recovery. Calling `refresh()` triggers an immediate re-fetch and resets the poll timer.

package/docs/wiki/Systemd.md

@@ -0,0 +1,43 @@
+# Systemd Layer
+
+The systemd layer provides typed hooks, a control component, and low-level API wrappers for interacting with systemd services through Cockpit.
+
+```ts
+import { useServiceStatus, ServiceControl } from "@rxtx4816/cockpit-plugin-base-react/systemd";
+```
+
+---
+
+## useServiceStatus
+
+Reactive hook that tracks the state of a systemd service. Polls via `systemctl is-active` and returns:
+
+- `status` — one of `"active"`, `"inactive"`, `"failed"`, `"activating"`, `"deactivating"`, `"unknown"`
+- `loading` — true on the initial fetch
+- `error` — any error from the underlying `cockpit.spawn` call
+- `refresh()` — manually re-check the service state
+
+The hook automatically re-polls at a configurable interval, so your UI stays in sync without manual management.
+
+---
+
+## ServiceControl
+
+A self-contained component that renders start/stop/restart/enable/disable buttons for a named service. Internally uses `useServiceStatus` for the current state and the `api` helpers to dispatch commands.
+
+Buttons are disabled while an operation is in progress. Status changes are reflected immediately via an optimistic state update, then confirmed by the next poll.
+
+---
+
+## API helpers
+
+Low-level typed wrappers around `cockpit.spawn` for common systemctl operations:
+
+- `startService(name)` — `systemctl start`
+- `stopService(name)` — `systemctl stop`
+- `restartService(name)` — `systemctl restart`
+- `enableService(name)` — `systemctl enable`
+- `disableService(name)` — `systemctl disable`
+- `getServiceStatus(name)` — returns the current active state string
+
+All functions return Promises and throw on non-zero exit codes.

package/docs/wiki/Testing.md

@@ -0,0 +1,51 @@
+# Testing
+
+## Setup
+
+The package ships a Vitest setup file that configures jsdom and installs jest-dom matchers. Reference it from your plugin's `vitest.config.ts` (handled automatically when you extend the base config):
+
+```ts
+import { defineConfig } from "@rxtx4816/cockpit-plugin-base-react/vitest.config.base";
+export default defineConfig();
+```
+
+---
+
+## Test utilities
+
+```ts
+import { mockCockpit, mockHttpClient } from "@rxtx4816/cockpit-plugin-base-react/testing/helpers";
+```
+
+### mockCockpit
+
+Returns an in-memory mock of the `cockpit` browser global. Stubs out `cockpit.spawn`, `cockpit.file`, `cockpit.http`, and channel creation so tests never attempt real system calls.
+
+Set it up in your test file:
+
+```ts
+beforeEach(() => {
+  vi.stubGlobal("cockpit", mockCockpit());
+});
+```
+
+Individual spawn calls can be configured to return specific output or to reject, letting you test both success and error paths.
+
+### mockHttpClient
+
+Returns a mock of the Cockpit HTTP client with configurable per-path responses. Useful for testing components that call `cockpit.http().get(path)`.
+
+```ts
+const client = mockHttpClient({ "/api/status": '{"running": true}' });
+```
+
+`get`, `post`, and `request` are all `vi.fn()` instances, so you can assert call counts and arguments with standard Vitest matchers.
+
+---
+
+## Running tests
+
+```bash
+npm test          # single run
+npm run test:watch  # watch mode
+```

package/docs/wiki/VM-Testing.md

@@ -0,0 +1,99 @@
+# VM Testing
+
+The package ships a QEMU-based VM harness for end-to-end testing against a real Cockpit instance running on a real OS. It spins up cloud VMs (Arch, Debian, Fedora by default), installs Cockpit, and mounts your built plugin via virtfs — no packaging or installation step required.
+
+## Prerequisites
+
+Arch Linux:
+```bash
+sudo pacman -S qemu-full cloud-image-utils wget
+```
+
+KVM access is strongly recommended. Without it the VMs run without hardware acceleration and will be significantly slower.
+
+## How it works
+
+1. A base cloud image is downloaded once per distro and kept on disk
+2. Each VM gets a thin overlay disk so the base image is never modified
+3. cloud-init provisions the VM on first boot: creates a `test` user, installs Cockpit and any plugin-specific packages, and mounts your plugin's `src/` directory read-only into the Cockpit install path via 9p/virtfs
+4. Changes to your built output (`src/main.js`, `src/main.css`) are immediately visible inside the VM without a restart
+
+## Plugin configuration
+
+Each plugin provides `scripts/test-vm.config.sh` to customise the harness:
+
+```bash
+PLUGIN_NAME="cockpit-caddy"
+MOUNT_TAG="cockpit_caddy"
+INSTALL_PATH="/usr/share/cockpit/cockpit-caddy"
+
+extra_packages() {
+  echo "caddy"
+}
+
+extra_runcmd() {
+  echo "  - systemctl enable --now caddy"
+}
+```
+
+## Usage
+
+Add to your plugin's `package.json`:
+```json
+"vm": "node_modules/@rxtx4816/cockpit-plugin-base-react/scripts/test-vm.sh"
+```
+
+Then:
+
+```bash
+npm run build                    # build the plugin first
+npm run vm download arch         # download base image (once)
+npm run vm start arch            # start the VM
+npm run vm wait arch             # block until cloud-init finishes (~2 min first boot)
+# open https://localhost:9090 — login: test / test
+```
+
+After the initial boot, subsequent starts are fast (no re-provisioning unless you `clean`).
+
+## All commands
+
+| Command | Description |
+|---|---|
+| `download [vm\|all]` | Download base cloud images |
+| `build` | Run `npm run build` |
+| `start [vm ...]` | Start VM(s) in background |
+| `wait <vm>` | Block until cloud-init completes |
+| `stop [vm ...]` | Stop VM(s) |
+| `status` | Show all VMs with ports and running state |
+| `ssh <vm>` | Open an SSH session into the VM |
+| `logs <vm>` | Tail the VM serial console |
+| `clean [vm ...]` | Wipe disk and cloud-init state (base image kept) |
+| `rebuild [vm ...]` | `clean` + `start` in one step |
+| `reset [vm ...]` | Remove all VM files including base image |
+
+## Ports
+
+By default the VMs are assigned sequential ports starting from:
+- Cockpit: `9090`, `9091`, `9092` (arch, debian, fedora)
+- SSH: `2220`, `2221`, `2222`
+
+These can be changed in your `test-vm.config.sh` via `SSH_BASE` and `COCKPIT_BASE`.
+
+## Live reload workflow
+
+Because the plugin is mounted via virtfs, you can iterate quickly:
+
+```bash
+npm run watch       # rebuild on source changes
+npm run vm start arch
+npm run vm wait arch
+# reload the browser tab after each rebuild — no VM restart needed
+```
+
+## Environment overrides
+
+| Variable | Default | Description |
+|---|---|---|
+| `VM_MEM` | `1024` | Memory per VM in MB |
+| `VM_CPUS` | `2` | vCPU count |
+| `VM_DISK_SIZE` | `12G` | Overlay disk size |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxtx4816/cockpit-plugin-base-react",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "Shared infrastructure for Cockpit plugins: i18n, dark theme, test setup, config presets, CI/CD workflows, and QEMU VM harness",
   "type": "module",
   "author": "RXTX4816",
@@ -60,23 +60,29 @@
       "default": "./eslint.config.base.js"
     },
     "./vitest.config.base": {
-      "default": "./vitest.config.base.ts"
+      "default": "./vitest.config.base.js"
     }
   },
   "files": [
+    "LICENSE",
+    "README.md",
+    "docs/",
     "src/",
     "scripts/",
     "tsconfig.base.json",
     "eslint.config.base.js",
-    "vitest.config.base.ts"
+    "vitest.config.base.js"
   ],
   "bin": {
     "cockpit-test-vm": "./scripts/test-vm.sh"
   },
   "scripts": {
+    "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch"
   },
   "peerDependencies": {
     "i18next": ">=26",
@@ -100,6 +106,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-i18next": "^17.0.8",
+    "typedoc": "^0.28.19",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   },

package/src/bootstrap.tsx

@@ -1,6 +1,13 @@
 import { ComponentType } from "react";
 import { createRoot } from "react-dom/client";
 
+/**
+ * Mounts a React application into the `#root` DOM element.
+ *
+ * Call this once at the plugin entry point after {@link initCockpitI18n}.
+ *
+ * @param App - The root React component to render.
+ */
 export function bootstrapPlugin(App: ComponentType): void {
   const root = createRoot(document.getElementById("root")!);
   root.render(<App />);

package/src/cockpit.d.ts

@@ -1,5 +1,6 @@
 // Ambient type declarations for the Cockpit browser global.
 // Superset covering cockpit-caddy and cockpit-compose usage patterns.
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
 /// <reference path="./css.d.ts" />
 
 declare interface CockpitProcess extends Promise<string> {

package/src/components/ConfirmDialog.tsx

@@ -9,18 +9,33 @@ import {
 import type { ReactNode } from "react";
 
 interface Props {
+  /** Controls modal visibility. */
   isOpen: boolean;
+  /** Modal heading text. */
   title: string;
+  /** Optional body content rendered above the inline error alert. */
   body?: ReactNode;
+  /** Label for the primary confirm button. */
   confirmLabel: string;
+  /** Label for the cancel button. Defaults to `"Cancel"`. */
   cancelLabel?: string;
+  /** Button variant — use `"danger"` for destructive actions. Defaults to `"primary"`. */
   variant?: "primary" | "danger";
+  /** When `true`, the confirm button shows a spinner and both buttons are disabled. */
   loading?: boolean;
+  /** If set, renders an inline danger alert above the footer buttons. */
   error?: string | null;
+  /** Called when the user clicks the confirm button. */
   onConfirm: () => void;
+  /** Called when the user clicks cancel or closes the modal. */
   onClose: () => void;
 }
 
+/**
+ * A PatternFly `Modal` wired up for a single confirm/cancel action.
+ *
+ * Pair with `useConfirmAction` to manage the open/close and loading state.
+ */
 export function ConfirmDialog({
   isOpen,
   title,

package/src/components/ErrorBoundary.tsx

@@ -3,6 +3,7 @@ import { EmptyState, EmptyStateBody } from "@patternfly/react-core";
 
 interface Props {
   children: ReactNode;
+  /** Heading shown in the PatternFly EmptyState fallback. Defaults to `"Something went wrong"`. */
   fallbackTitle?: string;
 }
 
@@ -10,6 +11,10 @@ interface State {
   error: Error | null;
 }
 
+/**
+ * React error boundary that catches unhandled render errors and displays a
+ * PatternFly `EmptyState` fallback instead of a blank page.
+ */
 export class ErrorBoundary extends Component<Props, State> {
   state: State = { error: null };
 

package/src/components/HelpPopover.tsx

@@ -3,11 +3,17 @@ import { Popover, Button } from "@patternfly/react-core";
 import { OutlinedQuestionCircleIcon } from "@patternfly/react-icons";
 
 interface Props {
+  /** Popover heading text. */
   header: string;
+  /** Popover body text. */
   body: string;
+  /** `aria-label` for the trigger button. Defaults to `header`. */
   "aria-label"?: string;
 }
 
+/**
+ * A question-mark icon button that opens a PatternFly `Popover` with help text.
+ */
 export function HelpPopover({ header, body, "aria-label": ariaLabel }: Props) {
   const [visible, setVisible] = useState(false);
   return (

package/src/components/LogViewer.tsx

@@ -12,17 +12,32 @@ import {
 } from "@patternfly/react-core";
 
 interface Props {
+  /** Log lines to display. Each string becomes one line in the pre block. */
   lines: string[];
+  /** When `true`, shows a spinner instead of the log content. */
   loading?: boolean;
+  /** If set, renders a danger alert at the top of the component. */
   error?: string | null;
+  /** When provided, adds a refresh button to the toolbar. */
   onRefresh?: () => void;
+  /** Placeholder text for the search input. Defaults to `"Search logs…"`. */
   searchPlaceholder?: string;
+  /** Message shown when `lines` is empty. Defaults to `"No log entries."`. */
   emptyMessage?: string;
+  /** Message shown when the search filter matches nothing. Defaults to `"No matching entries."`. */
   noMatchesMessage?: string;
+  /** Title of the danger alert when `error` is set. Defaults to `"Failed to load logs"`. */
   errorTitle?: string;
+  /** `aria-label` for the refresh button. Defaults to `"Refresh"`. */
   refreshAriaLabel?: string;
 }
 
+/**
+ * A scrollable, searchable log viewer with a toolbar.
+ *
+ * Pass `lines` from `useAsyncStream` or any string array. The search
+ * input filters lines client-side; `onRefresh` adds a refresh button.
+ */
 export function LogViewer({
   lines,
   loading = false,

package/src/components/StatusBadge.tsx

@@ -1,17 +1,38 @@
 import { Label, type LabelProps } from "@patternfly/react-core";
 
+/**
+ * Display configuration for a single status value.
+ */
 export interface StatusBadgeConfig {
+  /** PatternFly label color. */
   color: LabelProps["color"];
+  /** Human-readable label text. */
   label: string;
 }
 
 interface Props<T extends string> {
+  /** The current status value to look up in `config`. */
   status: T;
+  /** Map of status values to their display configuration. */
   config: Record<string, StatusBadgeConfig>;
+  /** Shown when `status` has no entry in `config`. Defaults to a grey label with the raw status string. */
   fallback?: StatusBadgeConfig;
+  /** Renders a compact PatternFly `Label`. */
   isCompact?: boolean;
 }
 
+/**
+ * Renders a PatternFly `Label` whose color and text are driven by a `config` map.
+ *
+ * @example
+ * ```tsx
+ * const STATUS_CONFIG: Record<ServiceStatus, StatusBadgeConfig> = {
+ *   active:  { color: "green", label: "Active" },
+ *   failed:  { color: "red",   label: "Failed" },
+ * };
+ * <StatusBadge status={serviceStatus} config={STATUS_CONFIG} />
+ * ```
+ */
 export function StatusBadge<T extends string>({ status, config, fallback, isCompact }: Props<T>) {
   const entry = config[status] ?? fallback ?? { color: "grey", label: status };
   return <Label color={entry.color} isCompact={isCompact}>{entry.label}</Label>;

package/src/components/ToastProvider.tsx

@@ -2,6 +2,7 @@ import { createContext, useCallback, useContext, useRef, useState, type ReactNod
 import { Alert, AlertGroup, AlertActionCloseButton } from "@patternfly/react-core";
 import "./ToastProvider.css";
 
+/** Severity level of a toast notification. */
 export type ToastVariant = "success" | "danger" | "warning" | "info";
 
 interface Toast {
@@ -11,11 +12,19 @@ interface Toast {
   body?: string;
 }
 
+/**
+ * Context value exposed by {@link ToastProvider} and consumed by {@link useToast}.
+ */
 export interface ToastContextValue {
+  /** Adds a toast with an explicit variant. */
   addToast: (variant: ToastVariant, title: string, body?: string) => void;
+  /** Shorthand for `addToast("success", ...)`. */
   success: (title: string, body?: string) => void;
+  /** Shorthand for `addToast("danger", ...)`. */
   error: (title: string, body?: string) => void;
+  /** Shorthand for `addToast("warning", ...)`. */
   warn: (title: string, body?: string) => void;
+  /** Shorthand for `addToast("info", ...)`. */
   info: (title: string, body?: string) => void;
 }
 
@@ -23,6 +32,12 @@ const ToastContext = createContext<ToastContextValue | null>(null);
 
 const AUTO_DISMISS_MS = 5000;
 
+/**
+ * Provides toast notification state to the component tree.
+ *
+ * Wrap your app root with `<ToastProvider>` and call {@link useToast} anywhere
+ * inside to fire notifications. Toasts auto-dismiss after 5 seconds.
+ */
 export function ToastProvider({ children }: { children: ReactNode }) {
   const [toasts, setToasts] = useState<Toast[]>([]);
   const counterRef = useRef(0);
@@ -71,6 +86,12 @@ const NOOP_TOAST: ToastContextValue = {
   info: () => {},
 };
 
+/**
+ * Returns the nearest {@link ToastProvider}'s context value.
+ *
+ * Falls back to a no-op implementation when called outside a `ToastProvider`,
+ * so it is safe to use in unit tests without a provider wrapper.
+ */
 export function useToast(): ToastContextValue {
   return useContext(ToastContext) ?? NOOP_TOAST;
 }

package/src/hooks/useAsyncAction.ts

@@ -1,5 +1,13 @@
 import { useState, useCallback } from "react";
 
+/**
+ * Wraps an async function with `loading` and `error` state.
+ *
+ * @param action - The async function to execute. A new stable reference should be
+ *   passed via `useCallback` to avoid unnecessary re-renders.
+ * @returns An object with `execute` (calls the action), `loading`, `error`, and
+ *   `clearError` (resets the error state).
+ */
 export function useAsyncAction<T>(
   action: () => Promise<T>,
 ): {

package/src/hooks/useAsyncStream.ts

@@ -1,23 +1,34 @@
 import { useState, useEffect, useRef, useCallback } from "react";
 
+/**
+ * Accumulated result of a streaming Cockpit process.
+ */
 export interface AsyncStreamResult {
+  /** All output lines received so far, with blank lines and CR stripped. */
   lines: string[];
+  /** `true` once the process exits (success or failure). */
   done: boolean;
+  /** `true` when the process exited with an error. */
   failed: boolean;
+  /** Error message when `failed` is `true`, otherwise empty string. */
   errorMsg: string;
+  /** Closes the underlying process and stops accumulating output. */
   cancel: () => void;
 }
 
 /**
- * Generic hook for accumulating line-buffered output from a CockpitProcess.
+ * Accumulates line-buffered output from a Cockpit process into a `lines` array.
  *
  * The caller supplies a `startProcess` factory that receives a `launch` callback.
  * Call `launch(proc)` synchronously once the process is ready — this avoids the
- * JS Promise "following" behaviour that occurs when a CockpitProcess (which extends
- * Promise) is returned from inside a .then().
+ * JS Promise "following" behaviour that occurs when a `CockpitProcess` (which extends
+ * `Promise`) is returned from inside a `.then()`.
  *
- * The `deps` array works like useEffect deps — the hook tears down and restarts
+ * The `deps` array works like `useEffect` deps — the hook tears down and restarts
  * the process whenever any dep changes.
+ *
+ * @param startProcess - Factory that receives a `launch` callback and must call it with the process.
+ * @param deps - Re-run dependencies (same semantics as `useEffect`).
  */
 export function useAsyncStream(
   startProcess: (launch: (proc: CockpitProcess) => void) => Promise<void>,

package/src/hooks/useAutoRefresh.ts

@@ -1,5 +1,12 @@
 import { useEffect, useRef, useState } from "react";
 
+/**
+ * Calls `fn` on a repeating interval, pausing automatically when the browser tab is hidden.
+ *
+ * @param fn - The callback to invoke on each tick. May be async — rejections are swallowed.
+ * @param intervalMs - Interval duration in milliseconds.
+ * @param paused - When `true`, suspends polling without tearing down the effect.
+ */
 export function useAutoRefresh(
   fn: () => void | Promise<void>,
   intervalMs: number,

package/src/hooks/useConfirmAction.ts

@@ -1,16 +1,34 @@
 import { useState, useCallback } from "react";
 
+/** Current phase of the confirmation flow. */
 export type ConfirmStep = "idle" | "confirming" | "submitting";
 
+/**
+ * State and controls returned by {@link useConfirmAction}.
+ */
 export interface ConfirmActionState {
+  /** Current phase of the flow. */
   step: ConfirmStep;
+  /** Error message from the last failed `submit`, or `null`. */
   error: string | null;
+  /** Transitions from `idle` → `confirming`, opening the dialog. */
   confirm: () => void;
+  /** Transitions back to `idle` and clears the error. */
   cancel: () => void;
+  /**
+   * Runs `action` while in the `submitting` phase.
+   * On success transitions to `idle`; on failure stays in `confirming` with `error` set.
+   */
   submit: (action: () => Promise<void>) => Promise<void>;
+  /** Clears the error without changing the step. */
   clearError: () => void;
 }
 
+/**
+ * Manages state for a multi-step confirmation flow: idle → confirming → submitting.
+ *
+ * Pair with `ConfirmDialog` to wire up the confirmation modal.
+ */
 export function useConfirmAction(): ConfirmActionState {
   const [step, setStep] = useState<ConfirmStep>("idle");
   const [error, setError] = useState<string | null>(null);

package/src/hooks/usePollingFetch.ts

@@ -1,16 +1,31 @@
 import { useState, useCallback, useEffect } from "react";
 import { useAutoRefresh } from "./useAutoRefresh";
 
+/**
+ * Result returned by {@link usePollingFetch}.
+ */
 export interface PollingFetchResult<T> {
+  /** Most recently fetched value, or `initial` before the first fetch completes. */
   data: T;
+  /** `true` only during the initial fetch — background polls update silently. */
   loading: boolean;
+  /** Error message from the most recent failed fetch, or `null`. */
   error: string | null;
+  /** Manually triggers a fetch; runs silently (no `loading` flash). */
   refresh: () => Promise<void>;
 }
 
 /**
- * Initial fetch shows loading=true; subsequent background polls update silently.
- * Calling refresh() manually also runs silently (no loading flash).
+ * Fetches data on mount and then polls at a fixed interval.
+ *
+ * The initial load sets `loading = true`; subsequent background polls and manual
+ * `refresh()` calls update `data` silently without a loading flash.
+ *
+ * @param fetcher - Async function that returns the data. Wrap in `useCallback` to
+ *   avoid restarting the interval on every render.
+ * @param initial - Value used for `data` before the first fetch resolves.
+ * @param intervalMs - Polling interval in milliseconds.
+ * @param paused - When `true`, pauses background polling (does not cancel an in-flight request).
  */
 export function usePollingFetch<T>(
   fetcher: () => Promise<T>,

package/src/i18n.ts

@@ -1,6 +1,10 @@
 import i18n from "i18next";
 import { initReactI18next } from "react-i18next";
 
+/**
+ * i18next `resources` map keyed by locale (e.g. `"en"`, `"de"`), each with a
+ * `translation` namespace object. Pass this to {@link initCockpitI18n}.
+ */
 export type LocaleResources = Record<string, { translation: Record<string, unknown> }>;
 
 // Reads Cockpit's language setting in priority order:
@@ -25,6 +29,14 @@ const cockpitDetector = {
   },
 };
 
+/**
+ * Initialises i18next with Cockpit's active locale and sets up a live observer
+ * so the UI re-translates when the user switches language in Cockpit settings.
+ *
+ * Call once at plugin startup, before {@link bootstrapPlugin}.
+ *
+ * @param resources - Translation resources keyed by locale. See {@link LocaleResources}.
+ */
 export function initCockpitI18n(resources: LocaleResources): void {
   void i18n
     .use({ type: "languageDetector", ...cockpitDetector } as Parameters<typeof i18n.use>[0])

package/src/systemd/ServiceControl.tsx

@@ -7,12 +7,22 @@ import type { ServiceStatus } from "./types";
 
 type PendingAction = "start" | "stop" | "restart" | "reload";
 
+/**
+ * Overrides for all user-visible strings in {@link ServiceControl}.
+ * Every field is optional — unset fields fall back to English defaults.
+ */
 export interface ServiceControlLabels {
+  /** Start button label. */
   start?: string;
+  /** Stop button label. */
   stop?: string;
+  /** Restart button label. */
   restart?: string;
+  /** Reload button label. */
   reload?: string;
+  /** Cancel button label in the confirmation dialog. */
   cancel?: string;
+  /** Confirm button label in the confirmation dialog. */
   confirmAction?: string;
   confirmStartTitle?: string;
   confirmStartBody?: string;
@@ -42,14 +52,28 @@ const DEFAULTS: Required<ServiceControlLabels> = {
 };
 
 interface Props {
+  /** The systemd unit name (e.g. `"nginx.service"`). */
   unit: string;
+  /** Current unit status — drives which buttons are enabled. */
   status: ServiceStatus;
+  /** When `true`, shows a spinner in place of the status badge. */
   loading?: boolean;
+  /** Called after a successful action so the parent can re-poll status. */
   onRefresh?: () => void;
+  /** Optional status badge rendered to the left of the action buttons. */
   statusBadge?: ReactNode;
+  /** Override any user-visible string. See {@link ServiceControlLabels}. */
   labels?: ServiceControlLabels;
 }
 
+/**
+ * A row of Start / Stop / Restart / Reload buttons for a systemd unit.
+ *
+ * Each action opens a `ConfirmDialog` before executing. Errors are shown
+ * both inline in the dialog and via the nearest `ToastProvider`.
+ *
+ * Pair with `useServiceStatus` for reactive status updates.
+ */
 export function ServiceControl({ unit, status, loading = false, onRefresh, statusBadge, labels }: Props) {
   const toast = useToast();
   const l = { ...DEFAULTS, ...labels };

package/src/systemd/api.ts

@@ -1,5 +1,13 @@
 import type { ServiceStatus } from "./types";
 
+/**
+ * Returns the current {@link ServiceStatus} of a systemd unit.
+ *
+ * Checks with `which` first — returns `"not-installed"` when the unit binary is absent.
+ * Then calls `systemctl is-active` and maps the output to a {@link ServiceStatus} value.
+ *
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ */
 export async function getServiceStatus(unit: string): Promise<ServiceStatus> {
   try {
     await cockpit.spawn(["which", unit]);
@@ -19,18 +27,35 @@ export async function getServiceStatus(unit: string): Promise<ServiceStatus> {
   }
 }
 
+/**
+ * Starts the given systemd unit via `systemctl start`. Requests superuser escalation.
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ */
 export async function startService(unit: string): Promise<void> {
   await cockpit.spawn(["systemctl", "start", unit], { superuser: "try" });
 }
 
+/**
+ * Stops the given systemd unit via `systemctl stop`. Requests superuser escalation.
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ */
 export async function stopService(unit: string): Promise<void> {
   await cockpit.spawn(["systemctl", "stop", unit], { superuser: "try" });
 }
 
+/**
+ * Restarts the given systemd unit via `systemctl restart`. Requests superuser escalation.
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ */
 export async function restartService(unit: string): Promise<void> {
   await cockpit.spawn(["systemctl", "restart", unit], { superuser: "try" });
 }
 
+/**
+ * Reloads the configuration of the given systemd unit via `systemctl reload`.
+ * Requests superuser escalation.
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ */
 export async function reloadService(unit: string): Promise<void> {
   await cockpit.spawn(["systemctl", "reload", unit], { superuser: "try" });
 }

package/src/systemd/types.ts

@@ -1 +1,10 @@
+/**
+ * Possible states of a systemd service unit.
+ *
+ * - `"active"` — unit is running
+ * - `"inactive"` — unit is stopped
+ * - `"failed"` — unit exited with an error
+ * - `"unknown"` — `systemctl is-active` returned an unrecognised value
+ * - `"not-installed"` — the unit binary was not found on the system
+ */
 export type ServiceStatus = "active" | "inactive" | "failed" | "unknown" | "not-installed";

package/src/systemd/useServiceStatus.test.ts

@@ -1,5 +1,5 @@
 import { renderHook, act, waitFor } from "@testing-library/react";
-import { vi, describe, it, expect, beforeEach, afterEach } from "vitest";
+import { vi, describe, it, expect, beforeEach } from "vitest";
 import { useServiceStatus } from "./useServiceStatus";
 
 const mockSpawn = vi.fn();

package/src/systemd/useServiceStatus.ts

@@ -5,6 +5,13 @@ import type { ServiceStatus } from "./types";
 
 const DEFAULT_INTERVAL = 5000;
 
+/**
+ * Polls the status of a systemd unit and returns reactive state.
+ *
+ * @param unit - The systemd unit name (e.g. `"nginx.service"`).
+ * @param intervalMs - How often to re-poll. Defaults to `5000` ms.
+ * @returns `{ status, loading, error, refresh }` — call `refresh()` to force an immediate re-poll.
+ */
 export function useServiceStatus(unit: string, intervalMs = DEFAULT_INTERVAL) {
   const [status, setStatus] = useState<ServiceStatus>("unknown");
   const [loading, setLoading] = useState(true);

package/src/testing/helpers.ts

@@ -1,5 +1,16 @@
 import { vi } from "vitest";
 
+/**
+ * Creates a fake `CockpitProcess` that emits `data` chunks then resolves (or rejects).
+ *
+ * @param data - One or more output chunks delivered via the `stream` callback.
+ * @param error - When provided, the process rejects with this message instead of resolving.
+ *
+ * @example
+ * ```ts
+ * vi.spyOn(cockpit, "spawn").mockReturnValue(mockProcess("hello\nworld\n"));
+ * ```
+ */
 export function mockProcess(data: string | string[], error?: string): CockpitProcess {
   const chunks = Array.isArray(data) ? data : [data];
   let streamCb: ((data: string) => void) | null = null;
@@ -20,6 +31,11 @@ export function mockProcess(data: string | string[], error?: string): CockpitPro
   }) as CockpitProcess;
 }
 
+/**
+ * Creates a fake `CockpitHttpClient` whose `get` method returns canned responses.
+ *
+ * @param responses - Map of URL paths to response body strings. Unmatched paths return `"{}"`.
+ */
 export function mockHttpClient(responses: Record<string, string> = {}): CockpitHttpClient {
   return {
     get: vi.fn((path: string) => Promise.resolve(responses[path] ?? "{}")),

package/{vitest.config.base.ts → vitest.config.base.js}

@@ -1,22 +1,13 @@
 import { defineConfig } from "vitest/config";
-import type { TestUserConfig } from "vitest/config";
 
-type TestConfig = TestUserConfig;
-
-export function createVitestConfig(overrides: TestConfig = {}) {
+export function createVitestConfig(overrides = {}) {
   const { coverage: coverageOverrides, setupFiles: extraSetupFiles, ...rest } = overrides;
 
   return defineConfig({
     server: {
-      // Allow Vite's dev server to serve files from symlinked file: packages
-      // that live outside the consuming project's root directory.
       fs: { allow: [".."] },
     },
     resolve: {
-      // Deduplicate packages that must be singletons when cockpit-plugin-base-react
-      // is installed as a file: link (symlink) — without this, the linked
-      // package resolves these from its own node_modules and React / i18next
-      // end up with two separate instances, breaking hooks and translations.
       dedupe: ["react", "react-dom", "i18next", "react-i18next", "@patternfly/react-core", "@patternfly/react-icons"],
     },
     test: {