@the-seeker/server-agent 0.1.0

package/dist/config.js

@@ -0,0 +1,109 @@
+import { constants, readFileSync } from "node:fs";
+import { access, chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir, platform as currentPlatform } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+export const SYSTEM_CONFIG_DIR = "/etc/theseeker-agent";
+export const CONFIG_FILE_NAME = "config.json";
+export const CONFIG_FILE_MODE = 0o600;
+export const CONFIG_DIR_MODE = 0o750;
+export const ENDPOINT_ENV = "THESEEKER_AGENT_ENDPOINT";
+export const TOKEN_ENV = "THESEEKER_AGENT_TOKEN";
+const packageMeta = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const AGENT_VERSION = typeof packageMeta.version === "string" ? packageMeta.version : "0.0.0";
+export const LogLevelSchema = z.enum(["debug", "info", "warn", "error"]);
+const LOG_LEVEL_ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+export const ConfigFileSchema = z.object({
+    endpoint: z.string().min(1).optional(),
+    token: z.string().min(1).optional(),
+    pm2Home: z.string().min(1).optional(),
+    logLevel: LogLevelSchema.optional(),
+});
+export class AgentConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AgentConfigError";
+    }
+}
+export function systemConfigPath() {
+    return join(SYSTEM_CONFIG_DIR, CONFIG_FILE_NAME);
+}
+export function userConfigPath(home = homedir()) {
+    return join(home, ".config", "theseeker-agent", CONFIG_FILE_NAME);
+}
+function candidatePaths(options) {
+    const user = userConfigPath(options.home ?? homedir());
+    return (options.platform ?? currentPlatform()) === "linux" ? [systemConfigPath(), user] : [user];
+}
+async function reachable(path, mode) {
+    try {
+        await access(path, mode);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** First existing readable config file, or `null` when the agent is env-only. */
+export async function readableConfigPath(options = {}) {
+    for (const path of candidatePaths(options))
+        if (await reachable(path, constants.R_OK))
+            return path;
+    return null;
+}
+/** Where `install` should write: the system path on linux when its directory is writable, else the user path. */
+export async function writableConfigPath(options = {}) {
+    if ((options.platform ?? currentPlatform()) === "linux") {
+        const writable = await reachable(SYSTEM_CONFIG_DIR, constants.W_OK) || await reachable(dirname(SYSTEM_CONFIG_DIR), constants.W_OK);
+        if (writable)
+            return systemConfigPath();
+    }
+    return userConfigPath(options.home ?? homedir());
+}
+export async function writeConfigFile(config, path) {
+    await mkdir(dirname(path), { recursive: true, mode: CONFIG_DIR_MODE });
+    await writeFile(path, `${JSON.stringify(ConfigFileSchema.parse(config), null, 2)}\n`, { mode: CONFIG_FILE_MODE });
+    await chmod(path, CONFIG_FILE_MODE);
+}
+export async function readConfigFile(path) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        throw new AgentConfigError(`config file is not valid JSON: ${path}`);
+    }
+    const parsed = ConfigFileSchema.safeParse(value);
+    if (!parsed.success)
+        throw new AgentConfigError(`config file has unexpected fields: ${path}`);
+    return parsed.data;
+}
+/** Config file merged with the `THESEEKER_AGENT_*` overrides. Never echoes the token back to the caller's logs. */
+export async function loadConfig(options = {}) {
+    const environment = options.env ?? process.env;
+    const path = await readableConfigPath(options);
+    const file = path ? await readConfigFile(path) : {};
+    const endpoint = environment[ENDPOINT_ENV]?.trim() || file.endpoint;
+    const token = environment[TOKEN_ENV]?.trim() || file.token;
+    if (!endpoint)
+        throw new AgentConfigError(`missing endpoint: set ${ENDPOINT_ENV} or "endpoint" in the config file`);
+    if (!token)
+        throw new AgentConfigError(`missing token: set ${TOKEN_ENV} or "token" in the config file`);
+    return {
+        endpoint, token, logLevel: file.logLevel ?? "info",
+        ...(file.pm2Home ? { pm2Home: file.pm2Home } : {}),
+    };
+}
+/** Structured stdout-only logger. Callers pass event names and scalar fields; frame bodies and tokens are never accepted. */
+export function createLogger(level = "info", write = (line) => void process.stdout.write(line)) {
+    const threshold = LOG_LEVEL_ORDER[level];
+    return (entryLevel, event, fields) => {
+        if (LOG_LEVEL_ORDER[entryLevel] < threshold)
+            return;
+        const entry = { ts: new Date().toISOString(), level: entryLevel, event };
+        for (const [key, value] of Object.entries(fields ?? {}))
+            if (value !== undefined)
+                entry[key] = value;
+        write(`${JSON.stringify(entry)}\n`);
+    };
+}

package/dist/handlers.d.ts

@@ -0,0 +1,27 @@
+import type { SourceRegistry } from "./collectors/sources.js";
+import type { Logger } from "./config.js";
+import type { ErrorResponseFrame, RequestFrame, ResponseError, ResponseFrame, Source, SuccessResponseFrame } from "./protocol.js";
+export declare const AGENT_REQUEST_TIMEOUT_MS = 15000;
+export declare const MAX_CONCURRENT_REQUESTS = 4;
+export declare const SUPPORTED_ACTIONS: readonly ["logs.tail", "service.status", "pm2.describe", "nginx.sources"];
+export interface HandlerState {
+    readonly pm2Home?: string | undefined;
+    readonly nginxEnabled: boolean;
+}
+export interface HandlerDependencies {
+    readonly registry: SourceRegistry;
+    readonly state: () => HandlerState;
+    readonly log: Logger;
+    readonly platform?: string | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly maxConcurrent?: number | undefined;
+    readonly onNginxSources?: ((sources: readonly Source[]) => void) | undefined;
+}
+export interface RequestHandlers {
+    /** Resolves with the frame to send back, or `null` when the request must be ignored. */
+    handle(frame: RequestFrame): Promise<ResponseFrame | null>;
+    readonly active: number;
+}
+export declare function successResponse(requestId: string, payload: SuccessResponseFrame["payload"]): SuccessResponseFrame;
+export declare function errorResponse(requestId: string, code: ResponseError["code"], message?: string): ErrorResponseFrame;
+export declare function createRequestHandlers(deps: HandlerDependencies): RequestHandlers;

package/dist/handlers.js

@@ -0,0 +1,109 @@
+import { homedir, platform as currentPlatform } from "node:os";
+import { join } from "node:path";
+import { CollectionError, locate, responseError, run } from "./collectors/command.js";
+import { collectNginx } from "./collectors/nginx.js";
+import { mapPm2 } from "./collectors/pm2.js";
+export const AGENT_REQUEST_TIMEOUT_MS = 15000;
+export const MAX_CONCURRENT_REQUESTS = 4;
+export const SUPPORTED_ACTIONS = ["logs.tail", "service.status", "pm2.describe", "nginx.sources"];
+const UNIT_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.@:\\-]*$/;
+export function successResponse(requestId, payload) {
+    return { type: "response", request_id: requestId, ok: true, payload };
+}
+export function errorResponse(requestId, code, message = code) {
+    return { type: "response", request_id: requestId, ok: false, error: { code, message } };
+}
+function capabilityCode(capability) {
+    if (capability === "permission_denied")
+        return "permission_denied";
+    return capability === "error" ? "internal" : "unsupported";
+}
+async function serviceStatus(unit, platform, signal) {
+    if (platform !== "linux")
+        throw new CollectionError("unsupported");
+    if (!UNIT_PATTERN.test(unit))
+        throw new CollectionError("permission_denied");
+    const binary = await locate("systemctl");
+    if (!binary)
+        throw new CollectionError("unsupported");
+    const { stdout } = await run(binary, ["show", unit, "--property=ActiveState,SubState,MainPID,NRestarts", "--no-pager"], { signal });
+    const properties = new Map(stdout.split("\n").map((line) => {
+        const split = line.indexOf("=");
+        return [line.slice(0, split), line.slice(split + 1)];
+    }));
+    return { unit, active_state: properties.get("ActiveState") ?? "unknown", sub_state: properties.get("SubState") ?? "unknown" };
+}
+async function describeProcess(name, registry, state, signal) {
+    const binary = process.env["PM2_BIN"] || await locate("pm2");
+    if (!binary)
+        throw new CollectionError("unsupported");
+    const { stdout } = await run(binary, ["jlist"], {
+        timeout: 8000, maxBuffer: 8 * 1024 * 1024, signal,
+        env: { ...process.env, PM2_HOME: state.pm2Home ?? process.env["PM2_HOME"] ?? join(homedir(), ".pm2") },
+    });
+    const found = mapPm2(stdout, registry).processes.find((entry) => entry.name === name);
+    if (!found)
+        throw new CollectionError("not_found");
+    return found;
+}
+export function createRequestHandlers(deps) {
+    const timeoutMs = deps.timeoutMs ?? AGENT_REQUEST_TIMEOUT_MS;
+    const maxConcurrent = deps.maxConcurrent ?? MAX_CONCURRENT_REQUESTS;
+    let active = 0;
+    async function dispatch(frame, signal) {
+        const state = deps.state();
+        switch (frame.action) {
+            case "logs.tail":
+                return await deps.registry.tail(frame.params.source_id, frame.params.lines, signal);
+            case "service.status":
+                return await serviceStatus(frame.params.unit, deps.platform ?? currentPlatform(), signal);
+            case "pm2.describe":
+                return await describeProcess(frame.params.name, deps.registry, state, signal);
+            case "nginx.sources": {
+                const result = await collectNginx(state.nginxEnabled, deps.registry, signal);
+                if (result.capability !== "available")
+                    throw new CollectionError(capabilityCode(result.capability));
+                deps.onNginxSources?.(result.sources);
+                return { sources: result.sources };
+            }
+            default:
+                return null;
+        }
+    }
+    return {
+        get active() { return active; },
+        async handle(frame) {
+            const action = frame.action;
+            if (!SUPPORTED_ACTIONS.some((supported) => supported === action)) {
+                deps.log("warn", "request_unsupported_action", { action });
+                return null;
+            }
+            if (active >= maxConcurrent) {
+                deps.log("warn", "request_rejected_busy", { action });
+                return errorResponse(frame.request_id, "internal", "busy");
+            }
+            active++;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(new CollectionError("timeout")), timeoutMs);
+            const startedAt = Date.now();
+            try {
+                const payload = await dispatch(frame, controller.signal);
+                if (!payload) {
+                    deps.log("warn", "request_unsupported_action", { action });
+                    return null;
+                }
+                deps.log("info", "request_completed", { action, duration_ms: Date.now() - startedAt });
+                return successResponse(frame.request_id, payload);
+            }
+            catch (error) {
+                const mapped = responseError(error);
+                deps.log("warn", "request_failed", { action, code: mapped.code, duration_ms: Date.now() - startedAt });
+                return errorResponse(frame.request_id, mapped.code, mapped.message);
+            }
+            finally {
+                clearTimeout(timer);
+                active--;
+            }
+        },
+    };
+}

package/dist/install/detect.d.ts

@@ -0,0 +1,64 @@
+import type { ConfigFile } from "../config.js";
+export declare const AGENT_BIN_NAME = "theseeker-agent";
+/** Skips every `launchctl` / `systemctl` invocation so installer QA never touches the real login session. */
+export declare const SKIP_SERVICE_MANAGER_ENV = "THESEEKER_AGENT_SKIP_SERVICE_MANAGER";
+/** Structurally compatible with `process.env` without depending on the app's augmented `ProcessEnv`. */
+export type EnvironmentVariables = Readonly<Record<string, string | undefined>>;
+export interface ExecResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type ExecRunner = (file: string, args: readonly string[]) => Promise<ExecResult>;
+/** Every filesystem effect of the installer goes through this seam so unit tests can assert on generated content. */
+export interface InstallFileSystem {
+    read(path: string): Promise<string | null>;
+    write(path: string, content: string, mode: number): Promise<void>;
+    mkdir(path: string, mode: number): Promise<void>;
+    remove(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    chown(path: string, uid: number, gid: number): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+}
+/** Writes the agent config file and returns the path it landed on. */
+export type ConfigWriter = (config: ConfigFile, target: {
+    readonly platform: string;
+    readonly home: string;
+}) => Promise<string>;
+export interface InstallEnvironment {
+    readonly platform: string;
+    readonly env: EnvironmentVariables;
+    readonly home: string;
+    readonly uid: number;
+    readonly execPath: string;
+    readonly exec: ExecRunner;
+    readonly fs: InstallFileSystem;
+    readonly writeConfig: ConfigWriter;
+    readonly print: (line: string) => void;
+}
+export declare function createInstallEnvironment(overrides?: Partial<InstallEnvironment>): InstallEnvironment;
+export interface Detection {
+    readonly platform: string;
+    readonly isRoot: boolean;
+    readonly hasSystemctl: boolean;
+    readonly user: string;
+    readonly group: string;
+    readonly userHome: string;
+    readonly nodePath: string;
+    readonly binPath: string;
+    readonly pm2Home: string;
+}
+export interface DetectOptions {
+    readonly user?: string | undefined;
+    readonly pm2Home?: string | undefined;
+}
+/** True when the installer may skip service-manager calls (QA and unit tests). */
+export declare function skipsServiceManager(environment: InstallEnvironment): boolean;
+/** `npm root -g` reports `<prefix>/lib/node_modules`; the global bin directory is `<prefix>/bin`. */
+export declare function globalBinDirectory(npmRoot: string, nodePath: string): string;
+export declare function detect(environment: InstallEnvironment, options?: DetectOptions): Promise<Detection>;
+/** Numeric ids of the service user, or `null` when the user does not exist on this host. */
+export declare function resolveUserIds(environment: InstallEnvironment, user: string): Promise<{
+    readonly uid: number;
+    readonly gid: number;
+} | null>;

package/dist/install/detect.js

@@ -0,0 +1,154 @@
+import { execFile } from "node:child_process";
+import { chmod, chown, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, platform as currentPlatform } from "node:os";
+import { dirname, join } from "node:path";
+import { writableConfigPath, writeConfigFile } from "../config.js";
+export const AGENT_BIN_NAME = "theseeker-agent";
+/** Skips every `launchctl` / `systemctl` invocation so installer QA never touches the real login session. */
+export const SKIP_SERVICE_MANAGER_ENV = "THESEEKER_AGENT_SKIP_SERVICE_MANAGER";
+const realExec = (file, args) => new Promise((resolve) => {
+    execFile(file, [...args], { timeout: 20000, maxBuffer: 8 * 1024 * 1024, shell: false, encoding: "utf8" }, (error, stdout, stderr) => {
+        const raw = error && "code" in error ? error.code : undefined;
+        resolve({ code: typeof raw === "number" ? raw : error ? 1 : 0, stdout: String(stdout), stderr: String(stderr) });
+    });
+});
+const realFs = {
+    async read(path) {
+        try {
+            return await readFile(path, "utf8");
+        }
+        catch {
+            return null;
+        }
+    },
+    async write(path, content, mode) {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content, { mode });
+        await chmod(path, mode);
+    },
+    async mkdir(path, mode) {
+        await mkdir(path, { recursive: true, mode });
+    },
+    async remove(path) {
+        await rm(path, { force: true, recursive: false });
+    },
+    async exists(path) {
+        try {
+            await stat(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async chown(path, uid, gid) {
+        await chown(path, uid, gid);
+    },
+    async chmod(path, mode) {
+        await chmod(path, mode);
+    },
+};
+const realConfigWriter = async (config, target) => {
+    const path = await writableConfigPath({ platform: target.platform, home: target.home });
+    await writeConfigFile(config, path);
+    return path;
+};
+export function createInstallEnvironment(overrides = {}) {
+    return {
+        platform: overrides.platform ?? currentPlatform(),
+        env: overrides.env ?? process.env,
+        home: overrides.home ?? process.env["HOME"] ?? homedir(),
+        uid: overrides.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0),
+        execPath: overrides.execPath ?? process.execPath,
+        exec: overrides.exec ?? realExec,
+        fs: overrides.fs ?? realFs,
+        writeConfig: overrides.writeConfig ?? realConfigWriter,
+        print: overrides.print ?? ((line) => void process.stdout.write(`${line}\n`)),
+    };
+}
+/** True when the installer may skip service-manager calls (QA and unit tests). */
+export function skipsServiceManager(environment) {
+    const flag = environment.env[SKIP_SERVICE_MANAGER_ENV];
+    return typeof flag === "string" && flag.trim().length > 0 && flag !== "0";
+}
+function invokingUser(environment) {
+    const login = environment.env["USER"] ?? environment.env["LOGNAME"];
+    return login && login.trim().length > 0 ? login.trim() : undefined;
+}
+async function detectServiceUser(environment, requested) {
+    const explicit = requested?.trim();
+    if (explicit)
+        return explicit;
+    const sudoUser = environment.env["SUDO_USER"]?.trim();
+    if (sudoUser)
+        return sudoUser;
+    const login = invokingUser(environment);
+    if (login)
+        return login;
+    const probe = await environment.exec("id", ["-un"]);
+    return probe.code === 0 && probe.stdout.trim() ? probe.stdout.trim() : "root";
+}
+async function detectPrimaryGroup(environment, user) {
+    const probe = await environment.exec("id", ["-gn", user]);
+    return probe.code === 0 && probe.stdout.trim() ? probe.stdout.trim() : user;
+}
+async function detectUserHome(environment, user) {
+    if (!environment.env["SUDO_USER"] && user === invokingUser(environment))
+        return environment.home;
+    if (environment.platform === "linux") {
+        const passwd = await environment.exec("getent", ["passwd", user]);
+        const fields = passwd.code === 0 ? passwd.stdout.trim().split(":") : [];
+        const home = fields[5];
+        if (home)
+            return home;
+        return user === "root" ? "/root" : join("/home", user);
+    }
+    if (user === "root")
+        return "/var/root";
+    return join("/Users", user);
+}
+/** `npm root -g` reports `<prefix>/lib/node_modules`; the global bin directory is `<prefix>/bin`. */
+export function globalBinDirectory(npmRoot, nodePath) {
+    const root = npmRoot.trim();
+    const suffix = "/lib/node_modules";
+    if (root.length > suffix.length && root.endsWith(suffix))
+        return join(root.slice(0, root.length - suffix.length), "bin");
+    if (root.endsWith("/node_modules"))
+        return join(dirname(root), "bin");
+    return dirname(nodePath);
+}
+async function detectBinPath(environment, nodePath) {
+    const probe = await environment.exec("npm", ["root", "-g"]);
+    const directory = globalBinDirectory(probe.code === 0 ? probe.stdout : "", nodePath);
+    return join(directory, AGENT_BIN_NAME);
+}
+export async function detect(environment, options = {}) {
+    const user = await detectServiceUser(environment, options.user);
+    const [group, userHome, binPath] = await Promise.all([
+        detectPrimaryGroup(environment, user),
+        detectUserHome(environment, user),
+        detectBinPath(environment, environment.execPath),
+    ]);
+    const systemctl = environment.platform === "linux" ? await environment.exec("systemctl", ["--version"]) : { code: 1, stdout: "", stderr: "" };
+    const pm2Home = options.pm2Home?.trim() || environment.env["PM2_HOME"]?.trim() || join(userHome, ".pm2");
+    return {
+        platform: environment.platform,
+        isRoot: environment.uid === 0,
+        hasSystemctl: systemctl.code === 0,
+        user,
+        group,
+        userHome,
+        nodePath: environment.execPath,
+        binPath,
+        pm2Home,
+    };
+}
+/** Numeric ids of the service user, or `null` when the user does not exist on this host. */
+export async function resolveUserIds(environment, user) {
+    const [uidProbe, gidProbe] = await Promise.all([environment.exec("id", ["-u", user]), environment.exec("id", ["-g", user])]);
+    if (uidProbe.code !== 0 || gidProbe.code !== 0)
+        return null;
+    const uid = Number.parseInt(uidProbe.stdout.trim(), 10);
+    const gid = Number.parseInt(gidProbe.stdout.trim(), 10);
+    return Number.isFinite(uid) && Number.isFinite(gid) ? { uid, gid } : null;
+}

package/dist/install/index.d.ts

@@ -0,0 +1,25 @@
+import type { EnvironmentVariables, InstallEnvironment } from "./detect.js";
+/** Baked at build time from `AGENT_PUBLIC_WS_URL`; `--endpoint` and the env var still win. */
+export declare const DEFAULT_AGENT_ENDPOINT = "wss://ingest.theseeker.io/agent/ws";
+export declare const ENDPOINT_BUILD_ENV = "AGENT_PUBLIC_WS_URL";
+export declare const NOT_ROOT_EXIT_CODE = 2;
+export declare const INSTALL_USAGE: string;
+export declare class InstallArgumentError extends Error {
+    constructor(message: string);
+}
+export interface InstallArgs {
+    readonly token: string;
+    readonly endpoint: string;
+    readonly user?: string | undefined;
+    readonly pm2Home?: string | undefined;
+    readonly addGroups: boolean;
+}
+export declare function parseInstallArgs(argv: readonly string[], env?: EnvironmentVariables): InstallArgs;
+export interface TargetArgs {
+    readonly user?: string | undefined;
+    readonly pm2Home?: string | undefined;
+}
+export declare function parseTargetArgs(argv: readonly string[]): TargetArgs;
+export declare function runInstall(argv: readonly string[], environment: InstallEnvironment): Promise<number>;
+export declare function runUninstall(argv: readonly string[], environment: InstallEnvironment): Promise<number>;
+export declare function runStatus(argv: readonly string[], environment: InstallEnvironment): Promise<number>;

package/dist/install/index.js

@@ -0,0 +1,169 @@
+import { dirname } from "node:path";
+import { CONFIG_DIR_MODE, systemConfigPath, userConfigPath } from "../config.js";
+import { detect, resolveUserIds } from "./detect.js";
+import { installLaunchd, statusLaunchd, uninstallLaunchd } from "./launchd.js";
+import { installSystemd, manualInstallCommands, SERVICE_NAME, statusSystemd, uninstallSystemd } from "./systemd.js";
+/** Baked at build time from `AGENT_PUBLIC_WS_URL`; `--endpoint` and the env var still win. */
+export const DEFAULT_AGENT_ENDPOINT = "wss://ingest.theseeker.io/agent/ws";
+export const ENDPOINT_BUILD_ENV = "AGENT_PUBLIC_WS_URL";
+export const NOT_ROOT_EXIT_CODE = 2;
+export const INSTALL_USAGE = [
+    `${SERVICE_NAME} install --token <sa_...> [options]`,
+    "",
+    "Install options:",
+    "  --token <sa_...>     agent token issued in the dashboard (required)",
+    `  --endpoint <url>     gateway websocket URL (default ${DEFAULT_AGENT_ENDPOINT})`,
+    "  --user <name>        service user (default $SUDO_USER, then $USER)",
+    "  --pm2-home <path>    PM2_HOME of that user (default <user home>/.pm2)",
+    "  --add-groups         add SupplementaryGroups=adm systemd-journal to the systemd unit",
+].join("\n");
+export class InstallArgumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InstallArgumentError";
+    }
+}
+const VALUE_FLAGS = ["--token", "--endpoint", "--user", "--pm2-home"];
+function parseFlags(argv, allowed) {
+    const values = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index] ?? "";
+        const separator = argument.indexOf("=");
+        const name = separator === -1 ? argument : argument.slice(0, separator);
+        if (!allowed.includes(name))
+            throw new InstallArgumentError(`unknown option: ${argument}`);
+        if (name === "--add-groups") {
+            values.set(name, "true");
+            continue;
+        }
+        if (separator !== -1) {
+            values.set(name, argument.slice(separator + 1));
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next === undefined || next.startsWith("--"))
+            throw new InstallArgumentError(`${name} requires a value`);
+        values.set(name, next);
+        index += 1;
+    }
+    return values;
+}
+export function parseInstallArgs(argv, env = {}) {
+    const flags = parseFlags(argv, [...VALUE_FLAGS, "--add-groups"]);
+    const token = flags.get("--token")?.trim();
+    if (!token)
+        throw new InstallArgumentError("--token is required");
+    const endpoint = flags.get("--endpoint")?.trim() || env[ENDPOINT_BUILD_ENV]?.trim() || DEFAULT_AGENT_ENDPOINT;
+    return {
+        token,
+        endpoint,
+        user: flags.get("--user")?.trim() || undefined,
+        pm2Home: flags.get("--pm2-home")?.trim() || undefined,
+        addGroups: flags.has("--add-groups"),
+    };
+}
+export function parseTargetArgs(argv) {
+    const flags = parseFlags(argv, ["--user", "--pm2-home"]);
+    return { user: flags.get("--user")?.trim() || undefined, pm2Home: flags.get("--pm2-home")?.trim() || undefined };
+}
+function unsupportedPlatform(environment) {
+    if (environment.platform === "linux" || environment.platform === "darwin")
+        return false;
+    environment.print(`unsupported platform: ${environment.platform} (linux and darwin only)`);
+    return true;
+}
+async function applyOwnership(environment, detection, configPath) {
+    const ids = await resolveUserIds(environment, detection.user);
+    if (!ids) {
+        environment.print(`warning: user ${detection.user} not found, left ${configPath} owned by root`);
+        return;
+    }
+    const directory = dirname(configPath);
+    await environment.fs.chown(directory, ids.uid, ids.gid);
+    await environment.fs.chmod(directory, CONFIG_DIR_MODE);
+    await environment.fs.chown(configPath, ids.uid, ids.gid);
+    environment.print(`owner: ${detection.user} (${ids.uid}:${ids.gid}) on ${directory} (0750) and ${configPath} (0600)`);
+}
+async function removeConfigFiles(environment, detection) {
+    const candidates = environment.platform === "linux" ? [systemConfigPath(), userConfigPath(detection.userHome)] : [userConfigPath(detection.userHome)];
+    for (const candidate of candidates) {
+        if (!(await environment.fs.exists(candidate)))
+            continue;
+        await environment.fs.remove(candidate);
+        environment.print(`removed config: ${candidate}`);
+    }
+}
+export async function runInstall(argv, environment) {
+    let args;
+    try {
+        args = parseInstallArgs(argv, environment.env);
+    }
+    catch (error) {
+        environment.print(`${error instanceof Error ? error.message : "invalid arguments"}\n\n${INSTALL_USAGE}`);
+        return 1;
+    }
+    if (unsupportedPlatform(environment))
+        return 1;
+    const detection = await detect(environment, { user: args.user, pm2Home: args.pm2Home });
+    if (environment.platform === "linux") {
+        if (!detection.isRoot) {
+            for (const line of manualInstallCommands(args.endpoint, detection.user, args.addGroups))
+                environment.print(line);
+            return NOT_ROOT_EXIT_CODE;
+        }
+        if (!detection.hasSystemctl) {
+            environment.print("systemctl was not found: install the agent with your own supervisor and run `theseeker-agent run`.");
+            return 1;
+        }
+    }
+    const config = { endpoint: args.endpoint, token: args.token, pm2Home: detection.pm2Home, logLevel: "info" };
+    const configPath = await environment.writeConfig(config, { platform: environment.platform, home: detection.userHome });
+    environment.print(`wrote config: ${configPath} (0600)`);
+    environment.print(`endpoint: ${args.endpoint}`);
+    environment.print(`service user: ${detection.user} (${detection.group}), PM2_HOME=${detection.pm2Home}`);
+    if (detection.isRoot)
+        await applyOwnership(environment, detection, configPath);
+    if (environment.platform === "linux")
+        return installSystemd(environment, { detection, addGroups: args.addGroups, endpoint: args.endpoint });
+    return installLaunchd(environment, { detection });
+}
+export async function runUninstall(argv, environment) {
+    let args;
+    try {
+        args = parseTargetArgs(argv);
+    }
+    catch (error) {
+        environment.print(error instanceof Error ? error.message : "invalid arguments");
+        return 1;
+    }
+    if (unsupportedPlatform(environment))
+        return 1;
+    const detection = await detect(environment, { user: args.user, pm2Home: args.pm2Home });
+    if (environment.platform === "linux") {
+        if (!detection.isRoot) {
+            environment.print("uninstall requires root. Run:");
+            environment.print(`  sudo ${SERVICE_NAME} uninstall --user ${detection.user}`);
+            return NOT_ROOT_EXIT_CODE;
+        }
+        const code = await uninstallSystemd(environment);
+        await removeConfigFiles(environment, detection);
+        return code;
+    }
+    const code = await uninstallLaunchd(environment, detection);
+    await removeConfigFiles(environment, detection);
+    return code;
+}
+export async function runStatus(argv, environment) {
+    let args;
+    try {
+        args = parseTargetArgs(argv);
+    }
+    catch (error) {
+        environment.print(error instanceof Error ? error.message : "invalid arguments");
+        return 1;
+    }
+    if (unsupportedPlatform(environment))
+        return 1;
+    const detection = await detect(environment, { user: args.user, pm2Home: args.pm2Home });
+    return environment.platform === "linux" ? statusSystemd(environment) : statusLaunchd(environment, detection);
+}