paseo-plugin-machine-status 0.1.1

package/client/ui.tsx

@@ -0,0 +1,263 @@
+import type { PluginTheme } from "@getpaseo/plugin";
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ActivityIndicator, Pressable, StyleSheet, Text, View } from "react-native";
+import { clampPercent } from "../shared/format";
+import { paletteFor } from "../shared/viz";
+
+/**
+ * Paseo exposes six colour tokens and a compact flag. Everything in this file is
+ * built from those alone: hardcoding a colour would break on half the themes,
+ * and there is no `surface1`, so panels are separated by hairline borders rather
+ * than by a second background.
+ */
+export interface Chrome {
+  theme: PluginTheme;
+  compact: boolean;
+}
+
+export type Tone = "accent" | "danger";
+
+export function useChromeStyles({ theme, compact }: Chrome) {
+  const palette = paletteFor(theme.colors.surface0);
+  return useMemo(
+    () =>
+      StyleSheet.create({
+        screen: { flex: 1, backgroundColor: theme.colors.surface0 },
+        content: { padding: compact ? 12 : 20, gap: compact ? 10 : 14, paddingBottom: 40 },
+        card: {
+          borderRadius: 12,
+          borderWidth: StyleSheet.hairlineWidth,
+          borderColor: palette.border,
+          padding: compact ? 12 : 16,
+          gap: compact ? 8 : 10,
+        },
+        cardTitle: {
+          color: theme.colors.foreground,
+          fontSize: compact ? 13 : 14,
+          fontWeight: "600",
+          letterSpacing: 0.4,
+          textTransform: "uppercase",
+        },
+        cardSubtitle: { color: theme.colors.foregroundMuted, fontSize: compact ? 11 : 12 },
+        heading: { color: theme.colors.foreground, fontSize: compact ? 20 : 26, fontWeight: "700" },
+        muted: { color: theme.colors.foregroundMuted, fontSize: compact ? 11 : 12 },
+        value: { color: theme.colors.foreground, fontSize: compact ? 13 : 14 },
+        valueStrong: {
+          color: theme.colors.foreground,
+          fontSize: compact ? 16 : 18,
+          fontWeight: "600",
+        },
+        danger: { color: theme.colors.statusDanger, fontSize: compact ? 11 : 12 },
+        axis: { color: theme.colors.foregroundMuted, fontSize: 10 },
+        figure: {
+          color: theme.colors.foreground,
+          fontSize: compact ? 26 : 30,
+          fontWeight: "700",
+          letterSpacing: -0.5,
+        },
+        row: { flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 12 },
+        rowWrap: { flexDirection: "row", flexWrap: "wrap", gap: compact ? 8 : 12 },
+        tiles: { flexDirection: "row", flexWrap: "wrap", gap: compact ? 10 : 14 },
+        chip: {
+          paddingVertical: 5,
+          paddingHorizontal: 12,
+          borderRadius: 7,
+          borderWidth: StyleSheet.hairlineWidth,
+          borderColor: palette.borderStrong,
+        },
+        track: { height: 6, borderRadius: 3, overflow: "hidden", backgroundColor: palette.neutral },
+        // A child View carries the opacity so the bar dims without fading its label.
+        trackDim: { ...StyleSheet.absoluteFillObject, backgroundColor: theme.colors.surface0, opacity: 0.75 },
+        fill: { height: 6, borderRadius: 3 },
+        button: {
+          paddingVertical: compact ? 10 : 12,
+          paddingHorizontal: 16,
+          borderRadius: 10,
+          alignItems: "center",
+          justifyContent: "center",
+        },
+        buttonText: { color: theme.colors.accentForeground, fontWeight: "600", fontSize: compact ? 13 : 14 },
+        ghostButton: {
+          paddingVertical: compact ? 10 : 12,
+          paddingHorizontal: 16,
+          borderRadius: 10,
+          borderWidth: StyleSheet.hairlineWidth,
+          borderColor: palette.borderStrong,
+          alignItems: "center",
+          justifyContent: "center",
+        },
+        ghostButtonText: { color: theme.colors.foreground, fontWeight: "600", fontSize: compact ? 13 : 14 },
+        selectableRow: {
+          borderRadius: 10,
+          borderWidth: StyleSheet.hairlineWidth,
+          borderColor: palette.border,
+          padding: compact ? 10 : 12,
+          gap: 4,
+        },
+        /** The design's two-column bands; they collapse to a stack when compact. */
+        band: {
+          flexDirection: compact ? "column" : "row",
+          gap: compact ? 10 : 14,
+          alignItems: "stretch",
+        },
+        divider: { height: StyleSheet.hairlineWidth, backgroundColor: palette.border },
+        /** One process per line: name, pid, cpu, bar, memory — no border, so the
+         *  list reads as a table rather than a stack of cards. */
+        processRow: {
+          flexDirection: "row",
+          alignItems: "center",
+          gap: 10,
+          paddingVertical: 7,
+          paddingHorizontal: 10,
+          borderRadius: 8,
+        },
+      }),
+    [theme, compact, palette],
+  );
+}
+
+export function Card({
+  chrome,
+  title,
+  subtitle,
+  children,
+}: {
+  chrome: Chrome;
+  title: string;
+  subtitle?: string;
+  children: React.ReactNode;
+}) {
+  const styles = useChromeStyles(chrome);
+  return (
+    <View style={styles.card}>
+      <View style={styles.row}>
+        <Text style={styles.cardTitle}>{title}</Text>
+        {subtitle ? <Text style={styles.cardSubtitle}>{subtitle}</Text> : null}
+      </View>
+      {children}
+    </View>
+  );
+}
+
+export function MetricRow({
+  chrome,
+  label,
+  value,
+}: {
+  chrome: Chrome;
+  label: string;
+  value: string;
+}) {
+  const styles = useChromeStyles(chrome);
+  return (
+    <View style={styles.row}>
+      <Text style={styles.muted}>{label}</Text>
+      <Text style={styles.value}>{value}</Text>
+    </View>
+  );
+}
+
+/** A labelled progress bar. Crosses to the danger tone once the resource is nearly spent. */
+export function Gauge({
+  chrome,
+  label,
+  valueLabel,
+  percent,
+  dangerAt = 85,
+}: {
+  chrome: Chrome;
+  label: string;
+  valueLabel: string;
+  percent: number | null;
+  dangerAt?: number;
+}) {
+  const styles = useChromeStyles(chrome);
+  const width = clampPercent(percent);
+  const tone = width >= dangerAt ? chrome.theme.colors.statusDanger : chrome.theme.colors.accent;
+  return (
+    <View style={{ gap: 6 }}>
+      <View style={styles.row}>
+        <Text style={styles.muted}>{label}</Text>
+        <Text style={styles.valueStrong}>{valueLabel}</Text>
+      </View>
+      <View style={styles.track}>
+        <View style={styles.trackDim} />
+        <View style={[styles.fill, { width: `${width}%`, backgroundColor: tone }]} />
+      </View>
+    </View>
+  );
+}
+
+export function ActionButton({
+  chrome,
+  label,
+  onPress,
+  tone = "accent",
+  variant = "solid",
+  disabled = false,
+  busy = false,
+}: {
+  chrome: Chrome;
+  label: string;
+  onPress: () => void;
+  tone?: Tone;
+  variant?: "solid" | "ghost";
+  disabled?: boolean;
+  busy?: boolean;
+}) {
+  const styles = useChromeStyles(chrome);
+  const background =
+    tone === "danger" ? chrome.theme.colors.statusDanger : chrome.theme.colors.accent;
+  const isGhost = variant === "ghost";
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      accessibilityState={{ disabled: disabled || busy }}
+      disabled={disabled || busy}
+      onPress={onPress}
+      style={({ pressed }) => [
+        isGhost ? styles.ghostButton : [styles.button, { backgroundColor: background }],
+        { opacity: disabled ? 0.45 : pressed ? 0.75 : 1 },
+      ]}
+    >
+      {busy ? (
+        <ActivityIndicator color={isGhost ? chrome.theme.colors.foreground : chrome.theme.colors.accentForeground} />
+      ) : (
+        <Text style={isGhost ? styles.ghostButtonText : styles.buttonText}>{label}</Text>
+      )}
+    </Pressable>
+  );
+}
+
+/**
+ * Two-step confirmation for destructive actions. The armed state expires on its
+ * own so a button left armed in a background tab cannot be triggered later by a
+ * stray tap. The timer is cleared on unmount.
+ */
+export function useArmedConfirm(timeoutMs = 6_000) {
+  const [armed, setArmed] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const clear = useCallback(() => {
+    if (timer.current !== null) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+  }, []);
+
+  const disarm = useCallback(() => {
+    clear();
+    setArmed(false);
+  }, [clear]);
+
+  const arm = useCallback(() => {
+    clear();
+    setArmed(true);
+    timer.current = setTimeout(() => setArmed(false), timeoutMs);
+  }, [clear, timeoutMs]);
+
+  useEffect(() => clear, [clear]);
+
+  return { armed, arm, disarm };
+}

package/index.client.tsx

@@ -0,0 +1,31 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { contributePills } from "./client/pill";
+import { MachineStatusSurface } from "./client/status";
+
+/**
+ * The app half of the plugin: the Machine surface, the ways into it from the
+ * sidebar and the Command Center, and the load pill beside each agent's composer.
+ */
+export default function contribute(client: PluginClientContext) {
+  client.addSurface("main", MachineStatusSurface);
+
+  client.addSidebarItem({
+    id: "main",
+    title: "Machine",
+    icon: "Activity",
+    surface: "main",
+  });
+
+  client.addCommandCenterItem({
+    id: "open-machine-status",
+    title: "Machine status",
+    icon: "Activity",
+    keywords: ["cpu", "memory", "disk", "swap", "battery", "thermal", "ports", "services"],
+    context: "global",
+    onSelect({ openSurface }) {
+      openSurface("main");
+    },
+  });
+
+  return contributePills(client);
+}

package/index.server.ts

@@ -0,0 +1,41 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { applyCleanupHandler, planCleanupHandler } from "./server/cleanup";
+import {
+  controlContainerHandler,
+  controlEngineHandler,
+  pruneDockerHandler,
+  readContainerLogsHandler,
+  readDockerHandler,
+} 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 { explainProcess } from "./shared/explain";
+import { readServices } from "./shared/services";
+
+/**
+ * The daemon half of the plugin. Every shell command, path and signal stays
+ * here, behind a Zod contract the app calls over RPC; nothing under `client/`
+ * can touch the machine directly.
+ */
+export default function contribute(server: PluginServerContext) {
+  server.handle(readMetrics, readMetricsHandler);
+  server.handle(planCleanup, planCleanupHandler);
+  server.handle(applyCleanup, applyCleanupHandler);
+  server.handle(listProcesses, listProcessesHandler);
+  server.handle(killProcess, killProcessHandler);
+  server.handle(readServices, readServicesHandler);
+  server.handle(explainProcess, explainProcessHandler);
+  server.handle(readDocker, readDockerHandler);
+  server.handle(controlContainer, controlContainerHandler);
+  server.handle(controlEngine, controlEngineHandler);
+  server.handle(readContainerLogs, readContainerLogsHandler);
+  server.handle(pruneDocker, pruneDockerHandler);
+
+  // No timers, watchers or sockets are created at registration time, so there is
+  // nothing to release. Paseo removes the handlers and stops the subprocess.
+  return () => {};
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "paseo-plugin-machine-status",
+  "version": "0.1.1",
+  "description": "Machine dashboard, open ports and Docker control inside Paseo",
+  "license": "MIT",
+  "author": "dutchakdev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dutchakdev/paseo-plugin-machine-status.git"
+  },
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "monitoring",
+    "macos",
+    "docker"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "preview": "tsx scripts/preview.ts"
+  },
+  "devDependencies": {
+    "@getpaseo/client": "0.8.0",
+    "@getpaseo/plugin": "0.8.0",
+    "@getpaseo/protocol": "0.8.0",
+    "@tanstack/react-query": "^5.90.11",
+    "@types/react": "~19.2.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "tsx": "^4.23.13",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.4.3"
+  },
+  "files": [
+    "paseo-plugin.json",
+    "index.client.tsx",
+    "index.server.ts",
+    "client/",
+    "server/",
+    "shared/"
+  ]
+}

package/paseo-plugin.json

@@ -0,0 +1,4 @@
+{
+  "id": "machine-status",
+  "requirements": { "paseo": ">=0.8.0" }
+}

package/server/cleanup.ts

@@ -0,0 +1,222 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { z } from "zod";
+import type { applyCleanup, CleanupTargetSchema, planCleanup } from "../shared/contracts";
+import { describeError, runTolerant } from "./exec";
+
+type CleanupTarget = z.output<typeof CleanupTargetSchema>;
+type PlanOutput = z.output<typeof planCleanup.output>;
+type ApplyInput = z.output<typeof applyCleanup.input>;
+type ApplyOutput = z.output<typeof applyCleanup.output>;
+
+interface TargetDefinition {
+  id: string;
+  label: string;
+  hint: string;
+  /** Checked in order; the first one that exists wins. Tools move their caches between versions. */
+  candidates: string[];
+}
+
+const home = (...segments: string[]): string => path.join(os.homedir(), ...segments);
+
+/**
+ * Only these paths can ever be emptied. Every entry is a package-manager or
+ * build cache that its tool recreates on demand, so removing it costs a
+ * re-download rather than data. `~/Library/Caches` as a whole is deliberately
+ * absent: it also holds application state that does not regenerate.
+ */
+const TARGET_DEFINITIONS: readonly TargetDefinition[] = [
+  {
+    id: "npm",
+    label: "npm cache",
+    hint: "Re-downloaded on the next install",
+    candidates: [home(".npm", "_cacache")],
+  },
+  {
+    id: "pnpm",
+    label: "pnpm store",
+    hint: "Rebuilt on the next pnpm install",
+    candidates: [home("Library", "pnpm", "store"), home(".local", "share", "pnpm", "store"), home(".pnpm-store")],
+  },
+  {
+    id: "yarn",
+    label: "Yarn cache",
+    hint: "Re-downloaded on the next install",
+    candidates: [home("Library", "Caches", "Yarn")],
+  },
+  {
+    id: "bun",
+    label: "Bun install cache",
+    hint: "Re-downloaded on the next bun install",
+    candidates: [home(".bun", "install", "cache")],
+  },
+  {
+    id: "turbo",
+    label: "Turbo cache",
+    hint: "Next turbo run rebuilds instead of replaying",
+    candidates: [home(".cache", "turbo")],
+  },
+  {
+    id: "xcode-derived-data",
+    label: "Xcode DerivedData",
+    hint: "Next Xcode build is a full rebuild",
+    candidates: [home("Library", "Developer", "Xcode", "DerivedData")],
+  },
+  {
+    id: "cargo",
+    label: "Cargo registry cache",
+    hint: "Re-downloaded on the next cargo build",
+    candidates: [home(".cargo", "registry", "cache")],
+  },
+  {
+    id: "go-build",
+    label: "Go build cache",
+    hint: "Next go build is a full rebuild",
+    candidates: [home("Library", "Caches", "go-build")],
+  },
+  {
+    id: "pip",
+    label: "pip cache",
+    hint: "Re-downloaded on the next pip install",
+    candidates: [home("Library", "Caches", "pip")],
+  },
+  {
+    id: "uv",
+    label: "uv cache",
+    hint: "Re-downloaded on the next uv sync",
+    candidates: [home(".cache", "uv")],
+  },
+];
+
+async function exists(target: string): Promise<boolean> {
+  try {
+    const stats = await fs.stat(target);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function resolveCandidate(definition: TargetDefinition): Promise<{ path: string; exists: boolean }> {
+  for (const candidate of definition.candidates) {
+    if (await exists(candidate)) return { path: candidate, exists: true };
+  }
+  return { path: definition.candidates[0], exists: false };
+}
+
+/**
+ * The last line of defence before anything is removed. Resolves symlinks first,
+ * so a link planted inside a cache directory cannot redirect the deletion, then
+ * requires the result to sit at least two levels below the real home directory.
+ */
+export async function assertSafePath(target: string): Promise<string> {
+  const realHome = await fs.realpath(os.homedir());
+  const resolved = await fs.realpath(target);
+  const relative = path.relative(realHome, resolved);
+
+  if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`refusing to touch ${resolved}: it is not inside the home directory`);
+  }
+  if (relative.split(path.sep).filter(Boolean).length < 2) {
+    throw new Error(`refusing to touch ${resolved}: too close to the home directory root`);
+  }
+  return resolved;
+}
+
+async function directorySizeBytes(target: string): Promise<number> {
+  const raw = await runTolerant("/usr/bin/du", ["-s", "-k", target], 120_000);
+  const match = raw.match(/^\s*(\d+)/);
+  return match ? Number(match[1]) * 1024 : 0;
+}
+
+/** Removes the directory's contents but keeps the directory, which several tools expect to exist. */
+export async function emptyDirectory(target: string): Promise<void> {
+  const entries = await fs.readdir(target);
+  const batchSize = 32;
+  for (let index = 0; index < entries.length; index += batchSize) {
+    await Promise.all(
+      entries
+        .slice(index, index + batchSize)
+        .map((entry) => fs.rm(path.join(target, entry), { recursive: true, force: true })),
+    );
+  }
+}
+
+export async function planCleanupHandler(): Promise<PlanOutput> {
+  const targets: CleanupTarget[] = await Promise.all(
+    TARGET_DEFINITIONS.map(async (definition): Promise<CleanupTarget> => {
+      const resolved = await resolveCandidate(definition);
+      const base = {
+        id: definition.id,
+        label: definition.label,
+        hint: definition.hint,
+        path: resolved.path,
+        exists: resolved.exists,
+      };
+      if (!resolved.exists) return { ...base, sizeBytes: 0, error: null };
+      try {
+        await assertSafePath(resolved.path);
+        return { ...base, sizeBytes: await directorySizeBytes(resolved.path), error: null };
+      } catch (error) {
+        return { ...base, sizeBytes: 0, error: describeError(error) };
+      }
+    }),
+  );
+
+  return {
+    scannedAt: new Date().toISOString(),
+    targets,
+    totalBytes: targets.reduce((sum, target) => sum + target.sizeBytes, 0),
+  };
+}
+
+export async function applyCleanupHandler({ targetIds }: ApplyInput): Promise<ApplyOutput> {
+  const requested = new Set(targetIds);
+  const selected = TARGET_DEFINITIONS.filter((definition) => requested.has(definition.id));
+
+  const unknown = [...requested].filter(
+    (id) => !TARGET_DEFINITIONS.some((definition) => definition.id === id),
+  );
+  if (unknown.length > 0) {
+    throw new Error(`unknown cleanup target: ${unknown.join(", ")}`);
+  }
+
+  const results = await Promise.all(
+    selected.map(async (definition) => {
+      const resolved = await resolveCandidate(definition);
+      if (!resolved.exists) {
+        return { id: definition.id, label: definition.label, ok: true, freedBytes: 0, error: null };
+      }
+      try {
+        // Re-validate at apply time: the plan may be minutes old.
+        const safePath = await assertSafePath(resolved.path);
+        const before = await directorySizeBytes(safePath);
+        await emptyDirectory(safePath);
+        const after = await directorySizeBytes(safePath);
+        return {
+          id: definition.id,
+          label: definition.label,
+          ok: true,
+          freedBytes: Math.max(0, before - after),
+          error: null,
+        };
+      } catch (error) {
+        console.error(`[machine-status] cleanup failed for ${definition.id}`, error);
+        return {
+          id: definition.id,
+          label: definition.label,
+          ok: false,
+          freedBytes: 0,
+          error: describeError(error),
+        };
+      }
+    }),
+  );
+
+  return {
+    appliedAt: new Date().toISOString(),
+    freedBytes: results.reduce((sum, result) => sum + result.freedBytes, 0),
+    results,
+  };
+}