@the-seeker/server-agent 0.1.0

package/dist/install/launchd.d.ts

@@ -0,0 +1,21 @@
+import type { Detection, InstallEnvironment } from "./detect.js";
+export declare const LAUNCHD_LABEL = "io.theseeker.agent";
+export declare const PLIST_FILE_MODE = 420;
+export declare const LAUNCHD_DIR_MODE = 493;
+export declare const LOG_FILE_NAME = "agent.log";
+export declare const ERROR_LOG_FILE_NAME = "agent.error.log";
+export declare function launchAgentsDirectory(home: string): string;
+export declare function plistPath(home: string): string;
+export declare function logDirectory(home: string): string;
+export interface PlistOptions {
+    readonly nodePath: string;
+    readonly binPath: string;
+    readonly home: string;
+}
+export declare function buildPlist(options: PlistOptions): string;
+export interface LaunchdInstallOptions {
+    readonly detection: Detection;
+}
+export declare function installLaunchd(environment: InstallEnvironment, options: LaunchdInstallOptions): Promise<number>;
+export declare function uninstallLaunchd(environment: InstallEnvironment, detection: Detection): Promise<number>;
+export declare function statusLaunchd(environment: InstallEnvironment, detection: Detection): Promise<number>;

package/dist/install/launchd.js

@@ -0,0 +1,113 @@
+import { join } from "node:path";
+import { skipsServiceManager } from "./detect.js";
+export const LAUNCHD_LABEL = "io.theseeker.agent";
+export const PLIST_FILE_MODE = 0o644;
+export const LAUNCHD_DIR_MODE = 0o755;
+export const LOG_FILE_NAME = "agent.log";
+export const ERROR_LOG_FILE_NAME = "agent.error.log";
+export function launchAgentsDirectory(home) {
+    return join(home, "Library", "LaunchAgents");
+}
+export function plistPath(home) {
+    return join(launchAgentsDirectory(home), `${LAUNCHD_LABEL}.plist`);
+}
+export function logDirectory(home) {
+    return join(home, "Library", "Logs", "theseeker-agent");
+}
+function escapeXml(value) {
+    return value.split("&").join("&amp;").split("<").join("&lt;").split(">").join("&gt;");
+}
+export function buildPlist(options) {
+    const logs = logDirectory(options.home);
+    const programArguments = [options.nodePath, options.binPath, "run"].map((argument) => `    <string>${escapeXml(argument)}</string>`);
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        "<dict>",
+        "  <key>Label</key>",
+        `  <string>${LAUNCHD_LABEL}</string>`,
+        "  <key>ProgramArguments</key>",
+        "  <array>",
+        ...programArguments,
+        "  </array>",
+        "  <key>RunAtLoad</key>",
+        "  <true/>",
+        "  <key>KeepAlive</key>",
+        "  <true/>",
+        "  <key>StandardOutPath</key>",
+        `  <string>${escapeXml(join(logs, LOG_FILE_NAME))}</string>`,
+        "  <key>StandardErrorPath</key>",
+        `  <string>${escapeXml(join(logs, ERROR_LOG_FILE_NAME))}</string>`,
+        "</dict>",
+        "</plist>",
+        "",
+    ].join("\n");
+}
+function serviceTarget(uid) {
+    return `gui/${uid}/${LAUNCHD_LABEL}`;
+}
+async function bootout(environment, uid, path) {
+    if (skipsServiceManager(environment)) {
+        environment.print(`skipped: launchctl bootout ${serviceTarget(uid)}`);
+        return;
+    }
+    const result = await environment.exec("launchctl", ["bootout", serviceTarget(uid)]);
+    if (result.code !== 0)
+        await environment.exec("launchctl", ["unload", "-w", path]);
+}
+export async function installLaunchd(environment, options) {
+    const home = options.detection.userHome;
+    const path = plistPath(home);
+    const plist = buildPlist({ nodePath: options.detection.nodePath, binPath: options.detection.binPath, home });
+    await environment.fs.mkdir(launchAgentsDirectory(home), LAUNCHD_DIR_MODE);
+    await environment.fs.mkdir(logDirectory(home), LAUNCHD_DIR_MODE);
+    const existing = await environment.fs.read(path);
+    await environment.fs.write(path, plist, PLIST_FILE_MODE);
+    environment.print(`${existing === null ? "wrote" : "rewrote"} launch agent: ${path}`);
+    await bootout(environment, environment.uid, path);
+    if (skipsServiceManager(environment))
+        environment.print(`skipped: launchctl bootstrap gui/${environment.uid} ${path}`);
+    else {
+        const bootstrap = await environment.exec("launchctl", ["bootstrap", `gui/${environment.uid}`, path]);
+        if (bootstrap.code !== 0) {
+            const legacy = await environment.exec("launchctl", ["load", "-w", path]);
+            if (legacy.code !== 0) {
+                environment.print(`launchctl bootstrap failed (exit ${bootstrap.code}) ${bootstrap.stderr.trim()}`);
+                return 1;
+            }
+        }
+        environment.print(`loaded: ${serviceTarget(environment.uid)}`);
+    }
+    environment.print(`logs: ${join(logDirectory(home), LOG_FILE_NAME)}`);
+    environment.print("note: a LaunchAgent is bound to the GUI login session — it runs while this user is logged in, not at boot.");
+    return 0;
+}
+export async function uninstallLaunchd(environment, detection) {
+    const path = plistPath(detection.userHome);
+    await bootout(environment, environment.uid, path);
+    if (await environment.fs.exists(path)) {
+        await environment.fs.remove(path);
+        environment.print(`removed launch agent: ${path}`);
+    }
+    else
+        environment.print(`launch agent not present: ${path}`);
+    environment.print(`kept logs: ${logDirectory(detection.userHome)}`);
+    return 0;
+}
+export async function statusLaunchd(environment, detection) {
+    const path = plistPath(detection.userHome);
+    const installed = await environment.fs.exists(path);
+    environment.print(`launch agent: ${path} ${installed ? "present" : "missing"}`);
+    if (!installed)
+        return 1;
+    if (!skipsServiceManager(environment)) {
+        const print = await environment.exec("launchctl", ["print", serviceTarget(environment.uid)]);
+        environment.print(`state: ${print.code === 0 ? "loaded" : "not loaded"} (${serviceTarget(environment.uid)})`);
+    }
+    const logPath = join(logDirectory(detection.userHome), LOG_FILE_NAME);
+    const contents = await environment.fs.read(logPath);
+    environment.print(`--- last 20 lines of ${logPath} ---`);
+    environment.print(contents === null ? "(no log file yet)" : contents.trimEnd().split("\n").slice(-20).join("\n") || "(empty)");
+    return 0;
+}

package/dist/install/systemd.d.ts

@@ -0,0 +1,28 @@
+import type { Detection, InstallEnvironment } from "./detect.js";
+export declare const SERVICE_NAME = "theseeker-agent";
+export declare const UNIT_PATH = "/etc/systemd/system/theseeker-agent.service";
+export declare const UNIT_FILE_MODE = 420;
+export declare const SUPPLEMENTARY_GROUPS: readonly ["adm", "systemd-journal"];
+export interface UnitOptions {
+    readonly user: string;
+    readonly group: string;
+    readonly nodePath: string;
+    readonly binPath: string;
+    readonly pm2Home: string;
+    readonly addGroups: boolean;
+}
+/** `ProtectSystem=strict` still hides `/home`; the agent reads PM2 logs there, so a `/home` PM2_HOME disables the guard. */
+export declare function protectHomeValue(pm2Home: string): "read-only" | "false";
+export declare function buildUnitFile(options: UnitOptions): string;
+export declare function unitOptionsFrom(detection: Detection, addGroups: boolean): UnitOptions;
+/** Printed verbatim when the installer is not root: it writes nothing and exits 2. */
+export declare function manualInstallCommands(endpoint: string, user: string, addGroups: boolean): readonly string[];
+export declare function manualGroupCommand(user: string): readonly string[];
+export interface SystemdInstallOptions {
+    readonly detection: Detection;
+    readonly addGroups: boolean;
+    readonly endpoint: string;
+}
+export declare function installSystemd(environment: InstallEnvironment, options: SystemdInstallOptions): Promise<number>;
+export declare function uninstallSystemd(environment: InstallEnvironment): Promise<number>;
+export declare function statusSystemd(environment: InstallEnvironment): Promise<number>;

package/dist/install/systemd.js

@@ -0,0 +1,122 @@
+import { SYSTEM_CONFIG_DIR } from "../config.js";
+import { skipsServiceManager } from "./detect.js";
+export const SERVICE_NAME = "theseeker-agent";
+export const UNIT_PATH = `/etc/systemd/system/${SERVICE_NAME}.service`;
+export const UNIT_FILE_MODE = 0o644;
+export const SUPPLEMENTARY_GROUPS = ["adm", "systemd-journal"];
+/** `ProtectSystem=strict` still hides `/home`; the agent reads PM2 logs there, so a `/home` PM2_HOME disables the guard. */
+export function protectHomeValue(pm2Home) {
+    return pm2Home.startsWith("/home/") || pm2Home === "/home" ? "false" : "read-only";
+}
+export function buildUnitFile(options) {
+    const lines = [
+        "[Unit]",
+        "Description=The Seeker server monitoring agent",
+        "Documentation=https://www.npmjs.com/package/@the-seeker/server-agent",
+        "After=network-online.target",
+        "Wants=network-online.target",
+        "",
+        "[Service]",
+        "Type=simple",
+        `User=${options.user}`,
+        `Group=${options.group}`,
+    ];
+    if (options.addGroups)
+        lines.push(`SupplementaryGroups=${SUPPLEMENTARY_GROUPS.join(" ")}`);
+    lines.push(`Environment=PM2_HOME=${options.pm2Home}`, `ExecStart=${options.nodePath} ${options.binPath} run`, "Restart=always", "RestartSec=5", "NoNewPrivileges=true", "ProtectSystem=strict", `ProtectHome=${protectHomeValue(options.pm2Home)}`, `ReadWritePaths=${SYSTEM_CONFIG_DIR}`, "", "[Install]", "WantedBy=multi-user.target", "");
+    return lines.join("\n");
+}
+export function unitOptionsFrom(detection, addGroups) {
+    return {
+        user: detection.user,
+        group: detection.group,
+        nodePath: detection.nodePath,
+        binPath: detection.binPath,
+        pm2Home: detection.pm2Home,
+        addGroups,
+    };
+}
+/** Printed verbatim when the installer is not root: it writes nothing and exits 2. */
+export function manualInstallCommands(endpoint, user, addGroups) {
+    const extra = addGroups ? " --add-groups" : "";
+    return [
+        "systemd unit installation requires root.",
+        "Run the same command again with sudo:",
+        "",
+        `  sudo ${SERVICE_NAME} install --token <sa_...> --endpoint ${endpoint} --user ${user}${extra}`,
+        "",
+        "It writes:",
+        `  ${UNIT_PATH}`,
+        `  ${SYSTEM_CONFIG_DIR}/config.json (0600, owned by ${user})`,
+        "and then runs:",
+        "  sudo systemctl daemon-reload",
+        `  sudo systemctl enable --now ${SERVICE_NAME}`,
+    ];
+}
+export function manualGroupCommand(user) {
+    return [
+        `note: SupplementaryGroups was omitted. Without ${SUPPLEMENTARY_GROUPS.join(" and ")} membership the agent`,
+        "      can only read journal entries and log files its own user may read (systemd unit status still works).",
+        "      To grant broader log access run, then restart the service:",
+        `        sudo usermod -aG ${SUPPLEMENTARY_GROUPS.join(",")} ${user}`,
+        `        sudo systemctl restart ${SERVICE_NAME}`,
+    ];
+}
+async function runSystemctl(environment, args) {
+    if (skipsServiceManager(environment)) {
+        environment.print(`skipped: systemctl ${args.join(" ")}`);
+        return true;
+    }
+    const result = await environment.exec("systemctl", args);
+    if (result.code !== 0)
+        environment.print(`systemctl ${args.join(" ")} failed (exit ${result.code}) ${result.stderr.trim()}`);
+    return result.code === 0;
+}
+export async function installSystemd(environment, options) {
+    const unit = buildUnitFile(unitOptionsFrom(options.detection, options.addGroups));
+    const existing = await environment.fs.read(UNIT_PATH);
+    if (existing === unit)
+        environment.print(`unit unchanged: ${UNIT_PATH}`);
+    else {
+        await environment.fs.write(UNIT_PATH, unit, UNIT_FILE_MODE);
+        environment.print(`${existing === null ? "wrote" : "rewrote"} unit: ${UNIT_PATH}`);
+    }
+    if (!(await runSystemctl(environment, ["daemon-reload"])))
+        return 1;
+    if (!(await runSystemctl(environment, ["enable", "--now", SERVICE_NAME])))
+        return 1;
+    environment.print(`service enabled: ${SERVICE_NAME}`);
+    if (!options.addGroups)
+        for (const line of manualGroupCommand(options.detection.user))
+            environment.print(line);
+    if (protectHomeValue(options.detection.pm2Home) === "false") {
+        environment.print(`note: ProtectHome=false because PM2_HOME (${options.detection.pm2Home}) lives under /home and must stay readable.`);
+    }
+    return 0;
+}
+export async function uninstallSystemd(environment) {
+    await runSystemctl(environment, ["disable", "--now", SERVICE_NAME]);
+    if (await environment.fs.exists(UNIT_PATH)) {
+        await environment.fs.remove(UNIT_PATH);
+        environment.print(`removed unit: ${UNIT_PATH}`);
+    }
+    else
+        environment.print(`unit not present: ${UNIT_PATH}`);
+    await runSystemctl(environment, ["daemon-reload"]);
+    return 0;
+}
+export async function statusSystemd(environment) {
+    const installed = await environment.fs.exists(UNIT_PATH);
+    environment.print(`unit: ${UNIT_PATH} ${installed ? "present" : "missing"}`);
+    if (!installed)
+        return 1;
+    if (skipsServiceManager(environment))
+        return 0;
+    const active = await environment.exec("systemctl", ["is-active", SERVICE_NAME]);
+    const enabled = await environment.exec("systemctl", ["is-enabled", SERVICE_NAME]);
+    environment.print(`state: ${active.stdout.trim() || "unknown"} (${enabled.stdout.trim() || "unknown"})`);
+    const logs = await environment.exec("journalctl", ["-u", SERVICE_NAME, "-n", "20", "--no-pager"]);
+    environment.print("--- last 20 log lines ---");
+    environment.print(logs.stdout.trim() || logs.stderr.trim() || "(no log lines)");
+    return active.stdout.trim() === "active" ? 0 : 1;
+}