@termix-ssh/plugin-sdk 1.0.20 → 1.0.22

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

@@ -0,0 +1,6 @@
+/** OpenRC scripts, with states mapped onto the words systemd uses. */
+import { type UnitAction, type UnitSummary } from "./systemd.js";
+export declare const OPENRC_LIST_SCRIPT = "\nrc-status --servicelist 2>/dev/null\necho \"@@TERMIX_RUNLEVELS@@\"\nrc-update show -v 2>/dev/null\nexit 0\n";
+export declare function parseOpenRcList(output: string): UnitSummary[];
+export declare function openRcActionScript(name: string, action: UnitAction): string;
+export declare function openRcStatusScript(name: string): string;

package/dist/host-scripts/openrc.js

@@ -0,0 +1,90 @@
+/** OpenRC scripts, with states mapped onto the words systemd uses. */
+import { isOpenRcName } from "./systemd.js";
+import { HostScriptError, shellQuote as q } from "./text.js";
+export const OPENRC_LIST_SCRIPT = `
+rc-status --servicelist 2>/dev/null
+echo "@@TERMIX_RUNLEVELS@@"
+rc-update show -v 2>/dev/null
+exit 0
+`;
+function activeOf(state) {
+    switch (state) {
+        case "started":
+            return { active: "active", sub: "running" };
+        case "crashed":
+            return { active: "failed", sub: "crashed" };
+        case "starting":
+            return { active: "activating", sub: "starting" };
+        case "stopping":
+            return { active: "deactivating", sub: "stopping" };
+        case "inactive":
+        case "hotplugged":
+            return { active: "inactive", sub: state };
+        default:
+            return { active: "inactive", sub: state || "stopped" };
+    }
+}
+export function parseOpenRcList(output) {
+    const [list = "", levels = ""] = output.split("@@TERMIX_RUNLEVELS@@");
+    const units = new Map();
+    for (const line of list.split("\n")) {
+        const match = /^\s*(\S+)\s+\[\s*([a-z ]+?)\s*\]/.exec(line);
+        if (!match)
+            continue;
+        const { active, sub } = activeOf(match[2]);
+        units.set(match[1], {
+            name: match[1],
+            type: "service",
+            load: "loaded",
+            active,
+            sub,
+            description: "",
+            fileState: "disabled",
+            preset: "",
+        });
+    }
+    for (const line of levels.split("\n")) {
+        const match = /^\s*(\S+)\s*\|\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const runlevels = match[2].trim();
+        const known = units.get(match[1]) ?? {
+            name: match[1],
+            type: "service",
+            load: "loaded",
+            active: "inactive",
+            sub: "stopped",
+            description: "",
+            fileState: "disabled",
+            preset: "",
+        };
+        known.fileState = runlevels ? "enabled" : "disabled";
+        known.description = runlevels ? `Runlevels: ${runlevels}` : "";
+        units.set(match[1], known);
+    }
+    return [...units.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function requireName(name) {
+    if (!isOpenRcName(name))
+        throw new HostScriptError("That is not a valid service name");
+    return name;
+}
+export function openRcActionScript(name, action) {
+    const s = q(requireName(name));
+    switch (action) {
+        case "start":
+        case "stop":
+        case "restart":
+            return `rc-service ${s} ${action} 2>&1 || { echo "SCRIPT_ERR:rc-service ${action} failed"; exit 1; }\n`;
+        case "enable":
+            return `rc-update add ${s} default 2>&1 || { echo "SCRIPT_ERR:rc-update add failed"; exit 1; }\n`;
+        case "disable":
+            return `rc-update del ${s} 2>&1 || { echo "SCRIPT_ERR:rc-update del failed"; exit 1; }\n`;
+        default:
+            throw new HostScriptError("OpenRC can't do that", 400);
+    }
+}
+export function openRcStatusScript(name) {
+    const s = q(requireName(name));
+    return `rc-service ${s} status 2>&1; rc-update show -v 2>/dev/null | grep -E '^ *'${s}' *\\|'; exit 0\n`;
+}

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

@@ -0,0 +1,43 @@
+/** Puts sbin on PATH and sets a plain, UTC environment. */
+export declare const SCRIPT_PRELUDE = "export PATH=\"$PATH:/usr/sbin:/sbin:/usr/local/sbin\"; export SYSTEMD_COLORS=0 SYSTEMD_PAGER=cat LC_ALL=C TZ=UTC; ";
+/**
+ * - `plain`: the login user.
+ * - `auto`: root when it can be had without a password, else the login user.
+ * - `root`: root or passwordless sudo, fails on anything else.
+ * - `root-only`: root logins only, for hosts where sudo is turned off.
+ */
+export type ScriptShellMode = "plain" | "auto" | "root" | "root-only";
+/** The command line that runs a script sent on stdin. */
+export declare function scriptShell(mode: ScriptShellMode): string;
+/**
+ * Runs a script as root with a sudo password. The command is `plain`; all of
+ * the returned stdin goes to the host. The password is read by the first
+ * line into a shell variable and piped to `sudo -S`, so it is never in argv,
+ * never in the environment and never run as a command. Root logins and
+ * passwordless sudo skip the password. The script itself travels as base64.
+ */
+export declare function passwordSudoScript(script: string, password: string): {
+    command: string;
+    stdin: string;
+};
+/** sudo asked for a password or a terminal it did not get. */
+export declare const SUDO_REFUSED_RE: RegExp;
+/** sudo got a password and it was wrong. */
+export declare const SUDO_WRONG_RE: RegExp;
+/** The user may not use sudo at all. */
+export declare const NOT_SUDOER_RE: RegExp;
+/**
+ * Scripts print `SCRIPT_ERR:` lines (or the older `SERVICES_ERR:`) before a
+ * non zero exit to explain a failure.
+ */
+export declare function scriptError(stdout: string): string;
+/** A line a script prints to explain why it stops. */
+export declare function errLine(message: string): string;
+/**
+ * Runs a long command in the background and stops it once stdin closes,
+ * which happens when the SSH channel ends. A pty can't be trusted for this:
+ * sudo keeps its own and the command would outlive the viewer.
+ */
+export declare function watchdog(command: string): string;
+/** The wrapper a streamed command runs in, as one shell command line. */
+export declare function streamCommand(script: string, sudo: boolean): string;

package/dist/host-scripts/shell.js

@@ -0,0 +1,95 @@
+/**
+ * How a script reaches the host: the command line runs a shell that reads
+ * the script from stdin (`bash -s`), so names and values in a script are
+ * never parsed out of argv.
+ */
+import { shellQuote, toBase64 } from "./text.js";
+// systemctl and friends often live in sbin, which a normal login skips.
+// TZ=UTC so tools print every time in UTC, which parses the same anywhere.
+const ENV = "SYSTEMD_COLORS=0 SYSTEMD_PAGER=cat LC_ALL=C TZ=UTC";
+/** Puts sbin on PATH and sets a plain, UTC environment. */
+export const SCRIPT_PRELUDE = `export PATH="$PATH:/usr/sbin:/sbin:/usr/local/sbin"; export ${ENV}; `;
+const SUDO = `sudo -n env PATH="$PATH" ${ENV}`;
+const ERR = "SCRIPT_ERR:";
+/** The command line that runs a script sent on stdin. */
+export function scriptShell(mode) {
+    switch (mode) {
+        case "plain":
+            return `${SCRIPT_PRELUDE}exec bash -s`;
+        case "auto":
+            return `${SCRIPT_PRELUDE}if [ "$(id -u)" = "0" ]; then exec bash -s; elif sudo -n true 2>/dev/null; then exec ${SUDO} bash -s; else exec bash -s; fi`;
+        case "root":
+            return `${SCRIPT_PRELUDE}if [ "$(id -u)" = "0" ]; then exec bash -s; else exec ${SUDO} bash -s; fi`;
+        case "root-only":
+            return `${SCRIPT_PRELUDE}if [ "$(id -u)" = "0" ]; then exec bash -s; else echo "${ERR}This needs root, or turn on Use sudo for this host"; exit 1; fi`;
+    }
+}
+/**
+ * Runs a script as root with a sudo password. The command is `plain`; all of
+ * the returned stdin goes to the host. The password is read by the first
+ * line into a shell variable and piped to `sudo -S`, so it is never in argv,
+ * never in the environment and never run as a command. Root logins and
+ * passwordless sudo skip the password. The script itself travels as base64.
+ */
+export function passwordSudoScript(script, password) {
+    if (/[\r\n\0]/.test(password)) {
+        throw new Error("A sudo password can't contain a line break");
+    }
+    const run = `bash -c "$TERMIX_S"`;
+    const stdin = `IFS= read -r TERMIX_PW
+${password}
+TERMIX_S=$(printf '%s' ${shellQuote(toBase64(script))} | base64 -d)
+if [ "$(id -u)" = "0" ]; then unset TERMIX_PW; exec ${run}
+elif sudo -n true 2>/dev/null; then unset TERMIX_PW; exec ${SUDO} ${run}
+else P=$TERMIX_PW; unset TERMIX_PW; printf '%s\\n' "$P" | sudo -k -S -p '' env PATH="$PATH" ${ENV} ${run}; exit $?
+fi
+`;
+    return { command: scriptShell("plain"), stdin };
+}
+/** sudo asked for a password or a terminal it did not get. */
+export const SUDO_REFUSED_RE = /password is required|a terminal is required|no tty present/i;
+/** sudo got a password and it was wrong. */
+export const SUDO_WRONG_RE = /incorrect password|sorry, try again|no password was provided/i;
+/** The user may not use sudo at all. */
+export const NOT_SUDOER_RE = /is not in the sudoers file|not allowed to run sudo/i;
+/**
+ * Scripts print `SCRIPT_ERR:` lines (or the older `SERVICES_ERR:`) before a
+ * non zero exit to explain a failure.
+ */
+export function scriptError(stdout) {
+    return stdout
+        .split("\n")
+        .map((line) => {
+        if (line.startsWith(ERR))
+            return line.slice(ERR.length);
+        if (line.startsWith("SERVICES_ERR:"))
+            return line.slice(13);
+        return null;
+    })
+        .filter((line) => line !== null)
+        .join("\n")
+        .trim();
+}
+/** A line a script prints to explain why it stops. */
+export function errLine(message) {
+    return `echo ${shellQuote(ERR + message)}`;
+}
+/**
+ * Runs a long command in the background and stops it once stdin closes,
+ * which happens when the SSH channel ends. A pty can't be trusted for this:
+ * sudo keeps its own and the command would outlive the viewer.
+ */
+export function watchdog(command) {
+    return `${command} &
+P=$!
+trap 'kill $P 2>/dev/null' EXIT
+cat >/dev/null
+`;
+}
+/** The wrapper a streamed command runs in, as one shell command line. */
+export function streamCommand(script, sudo) {
+    const quoted = shellQuote(`${SCRIPT_PRELUDE}${script}`);
+    return sudo
+        ? `if [ "$(id -u)" = "0" ]; then exec bash -c ${quoted}; elif sudo -n true 2>/dev/null; then exec ${SUDO} bash -c ${quoted}; else exec bash -c ${quoted}; fi`
+        : `exec bash -c ${quoted}`;
+}

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

@@ -0,0 +1,73 @@
+export declare const UNIT_TYPES: readonly ["service", "socket", "timer", "target", "mount", "automount", "path", "swap", "slice", "scope", "device"];
+export type UnitType = (typeof UNIT_TYPES)[number];
+export declare function isUnit(name: unknown): name is string;
+export declare function unitType(name: string): UnitType;
+/** Units a file may be written for. Templates and device style names are out. */
+export declare function isWritableUnitName(name: string): boolean;
+export declare function isOpenRcName(name: unknown): name is string;
+export declare function requireUnit(name: unknown): string;
+export type InitSystem = "systemd" | "openrc" | "none";
+/** A unit name or, on OpenRC, a service name. */
+export declare function requireService(name: unknown, init: string): string;
+export interface UnitSummary {
+    name: string;
+    type: string;
+    load: string;
+    active: string;
+    sub: string;
+    description: string;
+    /** enabled, disabled, static, masked and so on. Empty when unknown. */
+    fileState: string;
+    preset: string;
+}
+export interface UnitDetail {
+    name: string;
+    props: Record<string, string>;
+    status: string;
+}
+export interface TimerView {
+    name: string;
+    description: string;
+    active: string;
+    fileState: string;
+    /** Unix ms, or null when not set. */
+    next: number | null;
+    last: number | null;
+    activates: string;
+    schedule: string[];
+}
+export declare const UNIT_ACTIONS: readonly ["start", "stop", "restart", "reload", "enable", "disable", "enable-now", "disable-now", "mask", "unmask", "reset-failed", "revert"];
+export type UnitAction = (typeof UNIT_ACTIONS)[number];
+/** Actions OpenRC can do. */
+export declare const OPENRC_ACTIONS: readonly UnitAction[];
+export declare const DETECT_SCRIPT = "\nINIT=none\nif command -v systemctl >/dev/null 2>&1 && [ -d /run/systemd/system ]; then INIT=systemd\nelif command -v rc-service >/dev/null 2>&1; then INIT=openrc; fi\necho \"init=$INIT\"\nif [ \"$INIT\" = systemd ]; then echo \"version=$(systemctl --version 2>/dev/null | head -n1 | awk '{print $2}')\"; fi\nif [ \"$INIT\" = openrc ]; then echo \"version=$(openrc --version 2>/dev/null | head -n1 | awk '{print $NF}')\"; fi\necho \"os=$( . /etc/os-release 2>/dev/null; echo \"$PRETTY_NAME\")\"\necho \"hostname=$(hostname 2>/dev/null || cat /etc/hostname 2>/dev/null)\"\necho \"uid=$(id -u)\"\nif command -v journalctl >/dev/null 2>&1; then echo \"journal=1\"; fi\nif [ \"$INIT\" = systemd ]; then echo \"failed=$(systemctl list-units --state=failed --plain --no-legend --no-pager 2>/dev/null | wc -l)\"; fi\nif [ \"$INIT\" = openrc ]; then echo \"failed=$(rc-status --crashed 2>/dev/null | wc -l)\"; fi\nexit 0\n";
+export interface Detected {
+    init: InitSystem;
+    version: string;
+    os: string;
+    hostname: string;
+    root: boolean;
+    journal: boolean;
+    failed: number;
+}
+export declare function parseDetect(output: string): Detected;
+/** Types the list can show. */
+export declare const LIST_TYPES: readonly ["service", "socket", "timer", "target", "path", "mount"];
+export type ListType = (typeof LIST_TYPES)[number] | "all";
+export declare function listUnitsScript(type: ListType): string;
+/** Merges list-units and list-unit-files. Template units are left out. */
+export declare function parseUnitList(output: string): UnitSummary[];
+export declare const DETAIL_PROPS: readonly ["Id", "Description", "LoadState", "ActiveState", "SubState", "UnitFileState", "UnitFilePreset", "Result", "MainPID", "ExecMainStartTimestamp", "ActiveEnterTimestamp", "InactiveEnterTimestamp", "MemoryCurrent", "MemoryPeak", "CPUUsageNSec", "TasksCurrent", "NRestarts", "FragmentPath", "DropInPaths", "Requires", "Wants", "After", "WantedBy", "TriggeredBy", "Triggers", "User", "Group", "Restart", "Type", "ExecStart", "CanStart", "CanStop", "CanReload"];
+export declare function detailScript(unit: string): string;
+export declare function parseDetail(unit: string, output: string): UnitDetail;
+/** The systemctl call for an action. Prints `state=` after it. */
+export declare function actionScript(unit: string, action: UnitAction): string;
+/** Times systemctl prints under TZ=UTC, like "Thu 2026-10-22 02:03:51 UTC". */
+export declare function parseSystemdTime(value: string | undefined): number | null;
+export declare const TIMERS_SCRIPT = "\nUNITS=$( { systemctl list-units --all --type=timer --plain --no-legend --no-pager --full 2>/dev/null | awk '{print $1}'; systemctl list-unit-files --type=timer --plain --no-legend --no-pager --full 2>/dev/null | awk '{print $1}'; } | grep '\\.timer$' | grep -v '@\\.timer$' | sort -u)\n[ -n \"$UNITS\" ] || exit 0\nsystemctl show --no-pager -p Id -p Description -p ActiveState -p UnitFileState -p NextElapseUSecRealtime -p LastTriggerUSec -p Triggers -p TimersCalendar -p TimersMonotonic -- $UNITS\nexit 0\n";
+/** Reads systemctl show output for many units, split by blank lines. */
+export declare function parseShowBlocks(output: string): Array<Record<string, string>>;
+export declare function parseTimers(output: string): TimerView[];
+/** One line per unit from systemctl is-active, in the order asked. */
+export declare function isActiveScript(units: string[]): string;
+export declare function parseIsActive(units: string[], output: string): Map<string, string>;

package/dist/host-scripts/systemd.js

@@ -0,0 +1,320 @@
+/**
+ * systemd unit scripts and parsers, plus init system detection.
+ * Every script is meant for `scriptShell()`, sent on stdin.
+ */
+import { HostScriptError, parseKeys, shellQuote as q } from "./text.js";
+export const UNIT_TYPES = [
+    "service",
+    "socket",
+    "timer",
+    "target",
+    "mount",
+    "automount",
+    "path",
+    "swap",
+    "slice",
+    "scope",
+    "device",
+];
+// Backslash is allowed for escaped names like dev-disk-by\x2duuid.
+const UNIT_RE = new RegExp(`^[A-Za-z0-9_][A-Za-z0-9:_.@\\\\-]{0,250}\\.(${UNIT_TYPES.join("|")})$`);
+const OPENRC_RE = /^[A-Za-z0-9_][A-Za-z0-9_.@-]{0,127}$/;
+export function isUnit(name) {
+    return typeof name === "string" && UNIT_RE.test(name);
+}
+export function unitType(name) {
+    return name.slice(name.lastIndexOf(".") + 1);
+}
+/** Units a file may be written for. Templates and device style names are out. */
+export function isWritableUnitName(name) {
+    return (isUnit(name) &&
+        !name.includes("\\") &&
+        ["service", "socket", "timer", "target", "path", "mount"].includes(unitType(name)));
+}
+export function isOpenRcName(name) {
+    return typeof name === "string" && OPENRC_RE.test(name);
+}
+export function requireUnit(name) {
+    if (!isUnit(name))
+        throw new HostScriptError("That is not a valid unit name");
+    return name;
+}
+/** A unit name or, on OpenRC, a service name. */
+export function requireService(name, init) {
+    if (init === "openrc") {
+        if (!isOpenRcName(name))
+            throw new HostScriptError("That is not a valid service name");
+        return name;
+    }
+    return requireUnit(name);
+}
+export const UNIT_ACTIONS = [
+    "start",
+    "stop",
+    "restart",
+    "reload",
+    "enable",
+    "disable",
+    "enable-now",
+    "disable-now",
+    "mask",
+    "unmask",
+    "reset-failed",
+    "revert",
+];
+/** Actions OpenRC can do. */
+export const OPENRC_ACTIONS = [
+    "start",
+    "stop",
+    "restart",
+    "enable",
+    "disable",
+];
+export const DETECT_SCRIPT = `
+INIT=none
+if command -v systemctl >/dev/null 2>&1 && [ -d /run/systemd/system ]; then INIT=systemd
+elif command -v rc-service >/dev/null 2>&1; then INIT=openrc; fi
+echo "init=$INIT"
+if [ "$INIT" = systemd ]; then echo "version=$(systemctl --version 2>/dev/null | head -n1 | awk '{print $2}')"; fi
+if [ "$INIT" = openrc ]; then echo "version=$(openrc --version 2>/dev/null | head -n1 | awk '{print $NF}')"; fi
+echo "os=$( . /etc/os-release 2>/dev/null; echo "$PRETTY_NAME")"
+echo "hostname=$(hostname 2>/dev/null || cat /etc/hostname 2>/dev/null)"
+echo "uid=$(id -u)"
+if command -v journalctl >/dev/null 2>&1; then echo "journal=1"; fi
+if [ "$INIT" = systemd ]; then echo "failed=$(systemctl list-units --state=failed --plain --no-legend --no-pager 2>/dev/null | wc -l)"; fi
+if [ "$INIT" = openrc ]; then echo "failed=$(rc-status --crashed 2>/dev/null | wc -l)"; fi
+exit 0
+`;
+export function parseDetect(output) {
+    const keys = parseKeys(output);
+    const init = keys.init === "systemd" || keys.init === "openrc" ? keys.init : "none";
+    return {
+        init,
+        version: keys.version ?? "",
+        os: keys.os ?? "",
+        hostname: keys.hostname ?? "",
+        root: keys.uid === "0",
+        journal: keys.journal === "1",
+        failed: Number(keys.failed) || 0,
+    };
+}
+/** Types the list can show. */
+export const LIST_TYPES = [
+    "service",
+    "socket",
+    "timer",
+    "target",
+    "path",
+    "mount",
+];
+export function listUnitsScript(type) {
+    const types = type === "all" ? LIST_TYPES.join(",") : type;
+    if (type !== "all" && !LIST_TYPES.includes(type))
+        throw new HostScriptError("Unknown unit type");
+    return `
+systemctl list-units --all --plain --no-legend --no-pager --full --type=${types} 2>/dev/null
+echo "@@TERMIX_FILES@@"
+systemctl list-unit-files --plain --no-legend --no-pager --full --type=${types} 2>/dev/null
+exit 0
+`;
+}
+/** Merges list-units and list-unit-files. Template units are left out. */
+export function parseUnitList(output) {
+    const [loaded = "", files = ""] = output.split("@@TERMIX_FILES@@");
+    const units = new Map();
+    for (const raw of loaded.split("\n")) {
+        const line = raw.replace(/^[●*\s]+/, "").trimEnd();
+        if (!line)
+            continue;
+        const match = /^(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const [, name, load, active, sub, description] = match;
+        if (!name.includes(".") || name.includes("@."))
+            continue;
+        units.set(name, {
+            name,
+            type: unitType(name),
+            load,
+            active,
+            sub,
+            description: description.trim(),
+            fileState: "",
+            preset: "",
+        });
+    }
+    for (const raw of files.split("\n")) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const [name, state = "", preset = ""] = line.split(/\s+/);
+        if (!name || !name.includes(".") || name.includes("@."))
+            continue;
+        const known = units.get(name);
+        const cleanPreset = preset === "-" ? "" : preset;
+        if (known) {
+            known.fileState = state;
+            known.preset = cleanPreset;
+        }
+        else {
+            units.set(name, {
+                name,
+                type: unitType(name),
+                load: state === "masked" ? "masked" : "unloaded",
+                active: "inactive",
+                sub: "dead",
+                description: "",
+                fileState: state,
+                preset: cleanPreset,
+            });
+        }
+    }
+    return [...units.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export const DETAIL_PROPS = [
+    "Id",
+    "Description",
+    "LoadState",
+    "ActiveState",
+    "SubState",
+    "UnitFileState",
+    "UnitFilePreset",
+    "Result",
+    "MainPID",
+    "ExecMainStartTimestamp",
+    "ActiveEnterTimestamp",
+    "InactiveEnterTimestamp",
+    "MemoryCurrent",
+    "MemoryPeak",
+    "CPUUsageNSec",
+    "TasksCurrent",
+    "NRestarts",
+    "FragmentPath",
+    "DropInPaths",
+    "Requires",
+    "Wants",
+    "After",
+    "WantedBy",
+    "TriggeredBy",
+    "Triggers",
+    "User",
+    "Group",
+    "Restart",
+    "Type",
+    "ExecStart",
+    "CanStart",
+    "CanStop",
+    "CanReload",
+];
+export function detailScript(unit) {
+    const props = DETAIL_PROPS.map((p) => `-p ${p}`).join(" ");
+    return `
+systemctl show --no-pager ${props} -- ${q(requireUnit(unit))}
+echo "@@TERMIX_STATUS@@"
+systemctl status --no-pager --full -n 0 -- ${q(unit)} 2>&1
+exit 0
+`;
+}
+export function parseDetail(unit, output) {
+    const [props = "", status = ""] = output.split("@@TERMIX_STATUS@@");
+    return { name: unit, props: parseKeys(props), status: status.trim() };
+}
+const VERBS = {
+    start: "start",
+    stop: "stop",
+    restart: "restart",
+    reload: "reload",
+    enable: "enable",
+    disable: "disable",
+    "enable-now": "enable --now",
+    "disable-now": "disable --now",
+    mask: "mask",
+    unmask: "unmask",
+    "reset-failed": "reset-failed",
+    revert: "revert",
+};
+/** The systemctl call for an action. Prints `state=` after it. */
+export function actionScript(unit, action) {
+    const verb = VERBS[action];
+    if (!verb)
+        throw new HostScriptError("Unknown action");
+    const u = q(requireUnit(unit));
+    return `
+systemctl ${verb} -- ${u} 2>&1 || { echo "SCRIPT_ERR:systemctl ${verb} failed"; exit 1; }
+echo "state=$(systemctl is-active -- ${u} 2>/dev/null)"
+`;
+}
+/** Times systemctl prints under TZ=UTC, like "Thu 2026-10-22 02:03:51 UTC". */
+export function parseSystemdTime(value) {
+    if (!value)
+        return null;
+    const match = /(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})/.exec(value);
+    if (!match)
+        return null;
+    const [, y, mo, d, h, mi, s] = match.map(Number);
+    return Date.UTC(y, mo - 1, d, h, mi, s);
+}
+export const TIMERS_SCRIPT = `
+UNITS=$( { systemctl list-units --all --type=timer --plain --no-legend --no-pager --full 2>/dev/null | awk '{print $1}'; systemctl list-unit-files --type=timer --plain --no-legend --no-pager --full 2>/dev/null | awk '{print $1}'; } | grep '\\.timer$' | grep -v '@\\.timer$' | sort -u)
+[ -n "$UNITS" ] || exit 0
+systemctl show --no-pager -p Id -p Description -p ActiveState -p UnitFileState -p NextElapseUSecRealtime -p LastTriggerUSec -p Triggers -p TimersCalendar -p TimersMonotonic -- $UNITS
+exit 0
+`;
+/** Reads systemctl show output for many units, split by blank lines. */
+export function parseShowBlocks(output) {
+    const blocks = [];
+    for (const block of output.split(/\n\s*\n/)) {
+        const lines = block.split("\n").filter((line) => line.includes("="));
+        if (!lines.length)
+            continue;
+        // A unit can have several TimersCalendar lines; keep all of them.
+        const keys = {};
+        for (const line of lines) {
+            const eq = line.indexOf("=");
+            const key = line.slice(0, eq).trim();
+            const value = line.slice(eq + 1).trim();
+            keys[key] = key in keys ? `${keys[key]}\n${value}` : value;
+        }
+        blocks.push(keys);
+    }
+    return blocks;
+}
+function schedules(value) {
+    if (!value)
+        return [];
+    const out = [];
+    for (const line of value.split("\n")) {
+        const match = /\{\s*(\w+)=(.+?)\s*;/.exec(line);
+        if (match)
+            out.push(`${match[1]}=${match[2]}`);
+    }
+    return out;
+}
+export function parseTimers(output) {
+    return parseShowBlocks(output)
+        .filter((keys) => keys.Id?.endsWith(".timer"))
+        .map((keys) => ({
+        name: keys.Id,
+        description: keys.Description ?? "",
+        active: keys.ActiveState ?? "",
+        fileState: keys.UnitFileState ?? "",
+        next: parseSystemdTime(keys.NextElapseUSecRealtime),
+        last: parseSystemdTime(keys.LastTriggerUSec),
+        activates: (keys.Triggers ?? "").split(/\s+/)[0] ?? "",
+        schedule: [
+            ...schedules(keys.TimersCalendar),
+            ...schedules(keys.TimersMonotonic),
+        ],
+    }))
+        .sort((a, b) => (a.next ?? Infinity) - (b.next ?? Infinity));
+}
+/** One line per unit from systemctl is-active, in the order asked. */
+export function isActiveScript(units) {
+    return `systemctl is-active -- ${units.map((u) => q(requireUnit(u))).join(" ")} 2>/dev/null; exit 0\n`;
+}
+export function parseIsActive(units, output) {
+    const lines = output.split("\n").map((line) => line.trim());
+    const out = new Map();
+    units.forEach((unit, i) => out.set(unit, lines[i] || "unknown"));
+    return out;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Quoting, encoding and the error type the host scripts share.
+ *
+ * No Node APIs here: this entry also runs in the mobile app.
+ */
+/** A bad input to a host script builder. `status` is the HTTP status to answer with. */
+export declare class HostScriptError extends Error {
+    readonly status: number;
+    readonly extra: Record<string, unknown>;
+    constructor(message: string, status?: number, extra?: Record<string, unknown>);
+}
+/** Wraps a value in single quotes for a POSIX shell. */
+export declare function shellQuote(value: string): string;
+/** UTF-8 bytes of a string. */
+export declare function utf8Encode(text: string): Uint8Array;
+/** A string from UTF-8 bytes. Bad sequences become U+FFFD. */
+export declare function utf8Decode(bytes: ArrayLike<number>): string;
+/** Base64 of the UTF-8 bytes of a string, for `base64 -d` on the host. */
+export declare function toBase64(text: string): string;
+/** Reads key=value lines. Only the first = splits a line. */
+export declare function parseKeys(output: string): Record<string, string>;
+/** Trims output and keeps it short enough to show. */
+export declare function scrub(text: string, max?: number): string;