@termix-ssh/plugin-sdk 1.0.19 → 1.0.21

package/dist/host-scripts/docker.d.ts

@@ -0,0 +1,137 @@
+export type ContainerRuntime = "docker" | "podman";
+export declare function normalizeContainerRuntime(value: unknown): ContainerRuntime;
+export declare function getRuntimeLabel(runtime: ContainerRuntime): string;
+/**
+ * Non-interactive SSH shells don't source ~/.zprofile or ~/.bash_profile,
+ * so PATH additions from installers like Homebrew or OrbStack are missing.
+ */
+export declare const EXTRA_PATH_DIRS = "/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:\"$HOME/.orbstack/bin\"";
+export declare function containerCommand(runtime: ContainerRuntime | undefined, args: string, isWindows?: boolean): string;
+export declare const CONTAINER_ID_RE: RegExp;
+export declare const DOCKER_TIMESTAMP_RE: RegExp;
+export declare function isContainerId(value: unknown): value is string;
+export declare const CONTAINER_ACTIONS: readonly ["start", "stop", "restart", "pause", "unpause"];
+export type ContainerAction = (typeof CONTAINER_ACTIONS)[number];
+export declare function listFormat(isWindows: boolean): string;
+export declare function statsFormat(isWindows: boolean): string;
+/** One row of `ps --format listFormat()`. */
+export interface ContainerRow {
+    id: string;
+    name: string;
+    image: string;
+    status: string;
+    state: string;
+    ports: string;
+    created: string;
+}
+/** CLI arguments, without the runtime, for each container command. */
+export declare const dockerArgs: {
+    version: () => string;
+    ping: () => string;
+    list: (all: boolean, isWindows?: boolean) => string;
+    inspect: (id: string) => string;
+    stats: (id: string, isWindows?: boolean) => string;
+    action: (action: ContainerAction, id: string) => string;
+    remove: (id: string, force: boolean) => string;
+    logs: (id: string, options?: {
+        tail?: number;
+        timestamps?: boolean;
+        since?: string;
+        until?: string;
+    }) => string;
+    states: () => string;
+    composeProjects: () => string;
+};
+/** The version from `docker --version` or `podman --version`. */
+export declare function parseRuntimeVersion(output: string): string;
+export type RuntimeProblem = "NOT_INSTALLED" | "DAEMON_NOT_RUNNING" | "PERMISSION_DENIED" | "DOCKER_ERROR";
+/** Sorts a failed `docker ps` into a reason the UI can explain. */
+export declare function classifyRuntimeError(message: string): RuntimeProblem;
+/** Parses `ps --format listFormat()` output, skipping lines that are not JSON. */
+export declare function parseContainerList(output: string): Record<string, unknown>[];
+export interface ContainerStats {
+    cpu: string;
+    memoryUsed: string;
+    memoryLimit: string;
+    memoryPercent: string;
+    netInput: string;
+    netOutput: string;
+    blockRead: string;
+    blockWrite: string;
+    pids: string;
+}
+/** Parses one `stats --no-stream --format statsFormat()` line. Throws on bad JSON. */
+export declare function parseContainerStats(output: string): ContainerStats;
+export interface ContainerState {
+    /** Docker's own state word: running, exited, restarting, ... */
+    state: string;
+    /** Health from the status text, when the image declares a healthcheck. */
+    unhealthy: boolean;
+}
+export type DockerEventName = "exited" | "started" | "unhealthy" | "restarting";
+export declare const PS_STATE_FORMAT = "'{\"name\":\"{{.Names}}\",\"state\":\"{{.State}}\",\"status\":\"{{.Status}}\"}'";
+/** Parses `ps -a --format PS_STATE_FORMAT` output, one JSON object per line. */
+export declare function parseContainerStates(output: string): Map<string, ContainerState>;
+/**
+ * The events a pair of snapshots implies. A container missing from the
+ * previous snapshot counts as newly seen rather than started, so the first
+ * poll after a restart does not replay every running container.
+ */
+export declare function diffContainerStates(previous: Map<string, ContainerState>, current: Map<string, ContainerState>): Array<{
+    container: string;
+    event: DockerEventName;
+}>;
+export interface ContainerCounts {
+    running: number;
+    stopped: number;
+    unhealthy: number;
+    total: number;
+}
+/** Counts from `ps -a --format PS_STATE_FORMAT` output. */
+export declare function countContainers(output: string): ContainerCounts;
+export declare const STACK_NAME_RE: RegExp;
+export declare const STACK_SERVICE_RE: RegExp;
+export declare const COMPOSE_FILES: string[];
+export declare const STACK_ACTIONS: readonly ["deploy", "redeploy", "pull", "start", "stop", "restart", "pause", "unpause", "down", "destroy"];
+export type StackAction = (typeof STACK_ACTIONS)[number];
+/** Actions that can target one service of a stack. */
+export declare const STACK_SERVICE_ACTIONS: StackAction[];
+export type StackState = "running" | "partial" | "stopped" | "paused" | "not-deployed";
+export interface StackSummary {
+    name: string;
+    managed: boolean;
+    state: StackState;
+    running: number;
+    total: number;
+    composeFile: string | null;
+}
+export interface StackService {
+    service: string;
+    name: string;
+    id: string;
+    image: string;
+    state: string;
+    status: string;
+    health: string;
+    ports: string;
+}
+/** `compose ls` and `compose ps --format json` print one object per line or one array. */
+export declare function parseJsonLines(output: string): Record<string, unknown>[];
+export declare function parseServices(output: string): StackService[];
+/** Turns the `compose ls` status text ("running(2), exited(1)") into a state. */
+export declare function parseStackStatus(status: string): {
+    state: StackState;
+    running: number;
+    total: number;
+};
+export declare function stackStateFromServices(services: StackService[]): {
+    state: StackState;
+    running: number;
+    total: number;
+};
+/** Stacks from `compose ls -a --format json`, for hosts with no stacks folder. */
+export declare function parseComposeProjects(output: string): StackSummary[];
+/** The compose commands one action runs, in order. */
+export declare function composeArgsFor(action: StackAction, service: string | undefined, options: {
+    removeVolumes?: boolean;
+}): string[];

package/dist/host-scripts/docker.js

@@ -0,0 +1,345 @@
+/**
+ * Docker and Podman command builders and output parsers.
+ *
+ * Container ids and names are checked with CONTAINER_ID_RE before they go on
+ * a command line, so they need no quoting. Anything free form is quoted.
+ */
+import { HostScriptError } from "./text.js";
+export function normalizeContainerRuntime(value) {
+    return value === "podman" ? "podman" : "docker";
+}
+export function getRuntimeLabel(runtime) {
+    return runtime === "podman" ? "Podman" : "Docker";
+}
+/**
+ * Non-interactive SSH shells don't source ~/.zprofile or ~/.bash_profile,
+ * so PATH additions from installers like Homebrew or OrbStack are missing.
+ */
+export const EXTRA_PATH_DIRS = '/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:"$HOME/.orbstack/bin"';
+export function containerCommand(runtime, args, isWindows = false) {
+    const cli = `${normalizeContainerRuntime(runtime)} ${args}`;
+    // cmd and PowerShell don't understand the POSIX env prefix.
+    return isWindows ? cli : `PATH="${EXTRA_PATH_DIRS}:$PATH" ${cli}`;
+}
+export const CONTAINER_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+export const DOCKER_TIMESTAMP_RE = /^[0-9T:.Z+-]+$/;
+export function isContainerId(value) {
+    return (typeof value === "string" &&
+        value.length <= 256 &&
+        CONTAINER_ID_RE.test(value));
+}
+function requireContainer(id) {
+    if (!isContainerId(id))
+        throw new HostScriptError("That is not a valid container id");
+    return id;
+}
+export const CONTAINER_ACTIONS = [
+    "start",
+    "stop",
+    "restart",
+    "pause",
+    "unpause",
+];
+const LIST_FORMAT_UNIX = `'{"id":"{{.ID}}","name":"{{.Names}}","image":"{{.Image}}","status":"{{.Status}}","state":"{{.State}}","ports":"{{.Ports}}","created":"{{.CreatedAt}}"}' `;
+const LIST_FORMAT_WINDOWS = `"{\\"id\\":\\"{{.ID}}\\",\\"name\\":\\"{{.Names}}\\",\\"image\\":\\"{{.Image}}\\",\\"status\\":\\"{{.Status}}\\",\\"state\\":\\"{{.State}}\\",\\"ports\\":\\"{{.Ports}}\\",\\"created\\":\\"{{.CreatedAt}}\\"}"`;
+const STATS_FORMAT_UNIX = `'{"cpu":"{{.CPUPerc}}","memory":"{{.MemUsage}}","memoryPercent":"{{.MemPerc}}","netIO":"{{.NetIO}}","blockIO":"{{.BlockIO}}","pids":"{{.PIDs}}"}' `;
+const STATS_FORMAT_WINDOWS = `"{\\"cpu\\":\\"{{.CPUPerc}}\\",\\"memory\\":\\"{{.MemUsage}}\\",\\"memoryPercent\\":\\"{{.MemPerc}}\\",\\"netIO\\":\\"{{.NetIO}}\\",\\"blockIO\\":\\"{{.BlockIO}}\\",\\"pids\\":\\"{{.PIDs}}\\"}"`;
+export function listFormat(isWindows) {
+    return isWindows ? LIST_FORMAT_WINDOWS : LIST_FORMAT_UNIX;
+}
+export function statsFormat(isWindows) {
+    return isWindows ? STATS_FORMAT_WINDOWS : STATS_FORMAT_UNIX;
+}
+/** CLI arguments, without the runtime, for each container command. */
+export const dockerArgs = {
+    version: () => "--version",
+    ping: () => "ps",
+    list: (all, isWindows = false) => `ps ${all ? "-a " : ""}--format ${listFormat(isWindows)}`,
+    inspect: (id) => `inspect ${requireContainer(id)}`,
+    stats: (id, isWindows = false) => `stats ${requireContainer(id)} --no-stream --format ${statsFormat(isWindows)}`,
+    action: (action, id) => {
+        if (!CONTAINER_ACTIONS.includes(action))
+            throw new HostScriptError("Unknown action");
+        return `${action} ${requireContainer(id)}`;
+    },
+    remove: (id, force) => `rm ${force ? "-f " : ""}${requireContainer(id)}`,
+    logs: (id, options = {}) => {
+        let args = `logs ${requireContainer(id)}`;
+        if (options.tail && options.tail > 0)
+            args += ` --tail ${Math.floor(options.tail)}`;
+        if (options.timestamps)
+            args += " --timestamps";
+        if (options.since && DOCKER_TIMESTAMP_RE.test(options.since)) {
+            args += ` --since ${options.since}`;
+        }
+        if (options.until && DOCKER_TIMESTAMP_RE.test(options.until)) {
+            args += ` --until ${options.until}`;
+        }
+        return `${args} 2>&1`;
+    },
+    states: () => `ps -a --format ${PS_STATE_FORMAT}`,
+    composeProjects: () => "compose ls -a --format json",
+};
+/** The version from `docker --version` or `podman --version`. */
+export function parseRuntimeVersion(output) {
+    return output.match(/(?:Docker|podman) version ([^\s,]+)/i)?.[1] ?? "unknown";
+}
+/** Sorts a failed `docker ps` into a reason the UI can explain. */
+export function classifyRuntimeError(message) {
+    if (/command not found|not found: (docker|podman)|No such file or directory/i.test(message)) {
+        return "NOT_INSTALLED";
+    }
+    if (message.includes("Cannot connect to the Docker daemon"))
+        return "DAEMON_NOT_RUNNING";
+    if (/permission denied/i.test(message))
+        return "PERMISSION_DENIED";
+    return "DOCKER_ERROR";
+}
+/** Parses `ps --format listFormat()` output, skipping lines that are not JSON. */
+export function parseContainerList(output) {
+    return output
+        .split("\n")
+        .filter((line) => line.trim())
+        .flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** Parses one `stats --no-stream --format statsFormat()` line. Throws on bad JSON. */
+export function parseContainerStats(output) {
+    const raw = JSON.parse(output.trim());
+    const split = (value) => {
+        const [first, second] = (value ?? "").split(" / ");
+        return [first?.trim() || "0B", second?.trim() || "0B"];
+    };
+    const [memoryUsed, memoryLimit] = split(raw.memory);
+    const [netInput, netOutput] = split(raw.netIO);
+    const [blockRead, blockWrite] = split(raw.blockIO);
+    return {
+        cpu: raw.cpu,
+        memoryUsed,
+        memoryLimit,
+        memoryPercent: raw.memoryPercent,
+        netInput,
+        netOutput,
+        blockRead,
+        blockWrite,
+        pids: raw.pids,
+    };
+}
+export const PS_STATE_FORMAT = `'{"name":"{{.Names}}","state":"{{.State}}","status":"{{.Status}}"}'`;
+/** Parses `ps -a --format PS_STATE_FORMAT` output, one JSON object per line. */
+export function parseContainerStates(output) {
+    const states = new Map();
+    for (const line of output.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (!parsed.name)
+                continue;
+            states.set(parsed.name, {
+                state: (parsed.state ?? "").toLowerCase(),
+                unhealthy: /\(unhealthy\)/i.test(parsed.status ?? ""),
+            });
+        }
+        catch {
+            // A partial line is not worth failing the whole poll over.
+        }
+    }
+    return states;
+}
+/**
+ * The events a pair of snapshots implies. A container missing from the
+ * previous snapshot counts as newly seen rather than started, so the first
+ * poll after a restart does not replay every running container.
+ */
+export function diffContainerStates(previous, current) {
+    const events = [];
+    for (const [name, now] of current) {
+        const before = previous.get(name);
+        if (!before)
+            continue;
+        if (before.state !== now.state) {
+            if (now.state === "exited")
+                events.push({ container: name, event: "exited" });
+            else if (now.state === "running")
+                events.push({ container: name, event: "started" });
+            else if (now.state === "restarting") {
+                events.push({ container: name, event: "restarting" });
+            }
+        }
+        // A container can go unhealthy while it stays up.
+        if (!before.unhealthy && now.unhealthy) {
+            events.push({ container: name, event: "unhealthy" });
+        }
+    }
+    return events;
+}
+/** Counts from `ps -a --format PS_STATE_FORMAT` output. */
+export function countContainers(output) {
+    const states = [...parseContainerStates(output).values()];
+    const running = states.filter((s) => s.state === "running").length;
+    return {
+        running,
+        stopped: states.length - running,
+        unhealthy: states.filter((s) => s.unhealthy).length,
+        total: states.length,
+    };
+}
+// Compose stacks
+export const STACK_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+export const STACK_SERVICE_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,126}$/;
+export const COMPOSE_FILES = [
+    "compose.yaml",
+    "compose.yml",
+    "docker-compose.yaml",
+    "docker-compose.yml",
+];
+export const STACK_ACTIONS = [
+    "deploy",
+    "redeploy",
+    "pull",
+    "start",
+    "stop",
+    "restart",
+    "pause",
+    "unpause",
+    "down",
+    "destroy",
+];
+/** Actions that can target one service of a stack. */
+export const STACK_SERVICE_ACTIONS = [
+    "deploy",
+    "pull",
+    "start",
+    "stop",
+    "restart",
+    "pause",
+    "unpause",
+];
+/** `compose ls` and `compose ps --format json` print one object per line or one array. */
+export function parseJsonLines(output) {
+    const text = output.trim();
+    if (!text)
+        return [];
+    if (text.startsWith("[")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return [];
+        }
+    }
+    return text.split("\n").flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+const str = (value) => typeof value === "string" ? value : "";
+export function parseServices(output) {
+    return parseJsonLines(output).map((row) => {
+        const publishers = Array.isArray(row.Publishers)
+            ? row.Publishers
+            : [];
+        const ports = publishers
+            .filter((p) => Number(p.PublishedPort) > 0)
+            .map((p) => `${p.PublishedPort}:${p.TargetPort}`)
+            .filter((value, index, all) => all.indexOf(value) === index)
+            .join(", ");
+        return {
+            service: str(row.Service),
+            name: str(row.Name),
+            id: str(row.ID),
+            image: str(row.Image),
+            state: str(row.State),
+            status: str(row.Status),
+            health: str(row.Health),
+            ports,
+        };
+    });
+}
+function stateOf(running, paused, total) {
+    if (total === 0)
+        return "not-deployed";
+    if (paused === total)
+        return "paused";
+    if (running === total)
+        return "running";
+    if (running > 0)
+        return "partial";
+    return "stopped";
+}
+/** Turns the `compose ls` status text ("running(2), exited(1)") into a state. */
+export function parseStackStatus(status) {
+    let running = 0;
+    let paused = 0;
+    let total = 0;
+    for (const part of status.split(",")) {
+        const match = part.trim().match(/^([a-z]+)\((\d+)\)$/i);
+        if (!match)
+            continue;
+        const count = Number(match[2]);
+        total += count;
+        if (match[1] === "running")
+            running += count;
+        if (match[1] === "paused")
+            paused += count;
+    }
+    return { state: stateOf(running, paused, total), running, total };
+}
+export function stackStateFromServices(services) {
+    const total = services.length;
+    const running = services.filter((s) => s.state === "running").length;
+    const paused = services.filter((s) => s.state === "paused").length;
+    return { state: stateOf(running, paused, total), running, total };
+}
+/** Stacks from `compose ls -a --format json`, for hosts with no stacks folder. */
+export function parseComposeProjects(output) {
+    return parseJsonLines(output)
+        .flatMap((project) => {
+        const name = str(project.Name);
+        if (!STACK_NAME_RE.test(name))
+            return [];
+        return [
+            {
+                name,
+                managed: false,
+                ...parseStackStatus(str(project.Status)),
+                composeFile: str(project.ConfigFiles).split(",")[0] || null,
+            },
+        ];
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** The compose commands one action runs, in order. */
+export function composeArgsFor(action, service, options) {
+    const target = service ? ` ${service}` : "";
+    switch (action) {
+        case "deploy":
+            return [`up -d --remove-orphans${target}`];
+        case "redeploy":
+            return [`pull${target}`, `up -d --remove-orphans${target}`];
+        case "pull":
+            return [`pull${target}`];
+        case "start":
+        case "stop":
+        case "restart":
+        case "pause":
+        case "unpause":
+            return [`${action}${target}`];
+        case "down":
+            return ["down --remove-orphans"];
+        case "destroy":
+            return [`down --remove-orphans${options.removeVolumes ? " -v" : ""}`];
+    }
+}

package/dist/host-scripts/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Host scripts: command builders and output parsers for Docker, Linux
+ * metrics, systemd, the journal and OpenRC.
+ *
+ * Pure TypeScript with no Node or ssh2 imports, so the same code runs in a
+ * plugin backend and in the mobile app. Run a script by sending it on stdin
+ * to the command from `scriptShell()`.
+ */
+export * from "./text.js";
+export * from "./shell.js";
+export * from "./docker.js";
+export * from "./metrics.js";
+export * from "./systemd.js";
+export * from "./journal.js";
+export * from "./openrc.js";

package/dist/host-scripts/index.js

@@ -0,0 +1,15 @@
+/**
+ * Host scripts: command builders and output parsers for Docker, Linux
+ * metrics, systemd, the journal and OpenRC.
+ *
+ * Pure TypeScript with no Node or ssh2 imports, so the same code runs in a
+ * plugin backend and in the mobile app. Run a script by sending it on stdin
+ * to the command from `scriptShell()`.
+ */
+export * from "./text.js";
+export * from "./shell.js";
+export * from "./docker.js";
+export * from "./metrics.js";
+export * from "./systemd.js";
+export * from "./journal.js";
+export * from "./openrc.js";

package/dist/host-scripts/journal.d.ts

@@ -0,0 +1,45 @@
+export declare const MAX_JOURNAL_LINES = 5000;
+export interface JournalQuery {
+    units: string[];
+    priority?: number;
+    since?: string;
+    until?: string;
+    boot?: string;
+    grep?: string;
+    lines: number;
+    kernel: boolean;
+}
+export interface JournalEntry {
+    /** Unix ms. */
+    time: number;
+    priority: number;
+    unit: string;
+    ident: string;
+    pid: string;
+    message: string;
+}
+export interface BootView {
+    offset: number;
+    id: string;
+    first: string;
+    last: string;
+}
+export declare function isJournalTime(value: string): boolean;
+/** Reads journal filters from a query string. Anything odd throws a HostScriptError. */
+export declare function parseJournalQuery(input: Record<string, unknown>): JournalQuery;
+/** journalctl arguments for a query, each one quoted. */
+export declare function journalArgs(query: Omit<JournalQuery, "lines"> & {
+    lines?: number;
+}, options?: {
+    follow?: boolean;
+    useGrep?: boolean;
+}): string;
+export declare function journalScript(query: JournalQuery): string;
+/** One `journalctl -o json` line, or null when it is not an entry. */
+export declare function parseEntry(line: string): JournalEntry | null;
+export declare function parseJournal(output: string, query: JournalQuery): JournalEntry[];
+export declare const BOOTS_SCRIPT = "journalctl --list-boots --no-pager 2>/dev/null | tail -n 50; exit 0\n";
+export declare function parseBoots(output: string): BootView[];
+export declare const USAGE_SCRIPT = "journalctl --disk-usage 2>&1; exit 0\n";
+export declare function parseUsage(output: string): string;
+export declare function vacuumScript(body: Record<string, unknown>): string;