@ebowwa/seedinstallation 0.2.4

package/dist/sudo.js

@@ -0,0 +1,235 @@
+/**
+ * Composable sudo command runner for local and remote (SSH) contexts.
+ * Supports arbitrary commands, package installs, file writes, and service management.
+ */
+import { spawn } from "child_process";
+// ---------------------------------------------------------------------------
+// Core: run a command with sudo
+// ---------------------------------------------------------------------------
+/** Run an arbitrary command with sudo. */
+export async function sudo(cmd, opts) {
+    const parts = Array.isArray(cmd) ? cmd : cmd.split(/\s+/);
+    const envPrefix = opts.env
+        ? Object.entries(opts.env).map(([k, v]) => `${k}=${shellEscape(v)}`)
+        : [];
+    const sudoCmd = ["sudo", ...envPrefix, ...parts];
+    return exec(sudoCmd, opts);
+}
+const installCmd = {
+    apt: ["apt-get", "install", "-y"],
+    dnf: ["dnf", "install", "-y"],
+    apk: ["apk", "add", "--no-cache"],
+};
+const updateCmd = {
+    apt: ["apt-get", "update", "-qq"],
+    dnf: ["dnf", "check-update"],
+    apk: ["apk", "update"],
+};
+/** Install one or more system packages. */
+export async function pkgInstall(packages, opts) {
+    const pm = opts.pm ?? "apt";
+    const envOverride = {
+        ...opts.env,
+        ...(opts.nonInteractive !== false ? { DEBIAN_FRONTEND: "noninteractive" } : {}),
+    };
+    // Update package index first
+    await sudo(updateCmd[pm], { ...opts, env: envOverride, quiet: true });
+    return sudo([...installCmd[pm], ...packages], {
+        ...opts,
+        env: envOverride,
+    });
+}
+/** Write content to a privileged file path using tee. */
+export async function writeFile(path, content, opts) {
+    const op = opts.append ? "-a" : "";
+    const teeCmd = `tee ${op} ${shellEscape(path)}`.trim();
+    // Pipe content through sudo tee
+    const result = await execPipe(content, ["sudo", teeCmd], opts);
+    if (result.ok && opts.mode) {
+        await sudo(["chmod", opts.mode, path], opts);
+    }
+    if (result.ok && opts.owner) {
+        await sudo(["chown", opts.owner, path], opts);
+    }
+    return result;
+}
+/** Manage a systemd service. */
+export async function service(name, action, opts) {
+    return sudo(["systemctl", action, name], opts);
+}
+/** Enable and start a service in one call. */
+export async function serviceEnable(name, opts) {
+    return sudo(["systemctl", "enable", "--now", name], opts);
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function buildSshPrefix(ctx) {
+    const parts = ["ssh", "-F", "/dev/null", "-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null"];
+    if (ctx.keyPath)
+        parts.push("-i", ctx.keyPath);
+    else if (ctx.key)
+        parts.push("-i", ctx.key);
+    if (ctx.port)
+        parts.push("-p", String(ctx.port));
+    parts.push(`${ctx.user ?? "root"}@${ctx.host}`);
+    return parts;
+}
+export async function exec(args, opts) {
+    const finalArgs = opts.context.type === "ssh"
+        ? [...buildSshPrefix(opts.context), args.map(shellEscape).join(" ")]
+        : args;
+    return new Promise((resolve, reject) => {
+        const timeout = opts.timeout ?? 30_000;
+        let timer;
+        const spawnArgs = finalArgs[0].includes(" ")
+            ? ["sh", "-c", finalArgs.join(" ")]
+            : finalArgs;
+        const proc = spawn(spawnArgs[0], spawnArgs.slice(1), {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout?.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr?.on("data", (data) => {
+            stderr += data.toString();
+        });
+        if (timeout) {
+            timer = setTimeout(() => {
+                proc.kill();
+                resolve({
+                    stdout: opts.quiet ? "" : stdout,
+                    stderr: stderr + "\nCommand timed out",
+                    exitCode: 124,
+                    ok: false,
+                });
+            }, timeout);
+        }
+        proc.on("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({
+                stdout: opts.quiet ? "" : stdout,
+                stderr,
+                exitCode: code ?? 0,
+                ok: code === 0,
+            });
+        });
+        proc.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(new Error(`Command failed: ${err.message}`));
+        });
+    });
+}
+async function execPipe(input, args, opts) {
+    if (opts.context.type === "ssh") {
+        // Over SSH: echo content | ssh user@host 'sudo tee /path'
+        const sshPrefix = buildSshPrefix(opts.context);
+        const remoteCmd = args.join(" ");
+        const fullArgs = [...sshPrefix, remoteCmd];
+        return new Promise((resolve, reject) => {
+            const timeout = opts.timeout ?? 30_000;
+            let timer;
+            const spawnArgs = fullArgs[0].includes(" ")
+                ? ["sh", "-c", fullArgs.join(" ")]
+                : fullArgs;
+            const proc = spawn(spawnArgs[0], spawnArgs.slice(1), {
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            // Write input to stdin
+            if (proc.stdin) {
+                proc.stdin.write(input);
+                proc.stdin.end();
+            }
+            let stdout = "";
+            let stderr = "";
+            proc.stdout?.on("data", (data) => {
+                stdout += data.toString();
+            });
+            proc.stderr?.on("data", (data) => {
+                stderr += data.toString();
+            });
+            if (timeout) {
+                timer = setTimeout(() => {
+                    proc.kill();
+                    resolve({
+                        stdout: opts.quiet ? "" : stdout,
+                        stderr: stderr + "\nCommand timed out",
+                        exitCode: 124,
+                        ok: false,
+                    });
+                }, timeout);
+            }
+            proc.on("close", (code) => {
+                if (timer)
+                    clearTimeout(timer);
+                resolve({
+                    stdout: opts.quiet ? "" : stdout,
+                    stderr,
+                    exitCode: code ?? 0,
+                    ok: code === 0,
+                });
+            });
+            proc.on("error", (err) => {
+                if (timer)
+                    clearTimeout(timer);
+                reject(new Error(`Command failed: ${err.message}`));
+            });
+        });
+    }
+    // Local: pipe through shell
+    return new Promise((resolve, reject) => {
+        const timeout = opts.timeout ?? 30_000;
+        let timer;
+        const proc = spawn("sh", ["-c", args.join(" ")], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        // Write input to stdin
+        if (proc.stdin) {
+            proc.stdin.write(input);
+            proc.stdin.end();
+        }
+        let stdout = "";
+        let stderr = "";
+        proc.stdout?.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr?.on("data", (data) => {
+            stderr += data.toString();
+        });
+        if (timeout) {
+            timer = setTimeout(() => {
+                proc.kill();
+                resolve({
+                    stdout: opts.quiet ? "" : stdout,
+                    stderr: stderr + "\nCommand timed out",
+                    exitCode: 124,
+                    ok: false,
+                });
+            }, timeout);
+        }
+        proc.on("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({
+                stdout: opts.quiet ? "" : stdout,
+                stderr,
+                exitCode: code ?? 0,
+                ok: code === 0,
+            });
+        });
+        proc.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(new Error(`Command failed: ${err.message}`));
+        });
+    });
+}
+function shellEscape(s) {
+    if (/^[a-zA-Z0-9._\-\/=:@]+$/.test(s))
+        return s;
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}

package/dist/systemd.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Systemd service unit creation and management.
+ * Works with both local and SSH contexts via ExecContext from sudo.ts.
+ */
+import type { SudoOptions, ExecResult } from "./sudo.js";
+export interface ServiceUnitOptions {
+    /** Service description */
+    description: string;
+    /** Services to start before this one */
+    after?: string[];
+    /** Services that this one wants */
+    wants?: string[];
+    /** Service type (default: "simple") */
+    type?: "simple" | "oneshot" | "exec" | "forking" | "notify" | "idle";
+    /** User to run as (default: "root") */
+    user?: string;
+    /** Group to run as */
+    group?: string;
+    /** Working directory */
+    workingDirectory: string;
+    /** Command to execute */
+    execStart: string;
+    /** Command to execute before start (oneshot type) */
+    execStartPre?: string[];
+    /** Command to execute after stop */
+    execStopPost?: string[];
+    /** Restart policy (default: "always") */
+    restart?: "no" | "always" | "on-success" | "on-failure" | "on-abnormal" | "on-abort" | "on-watchdog";
+    /** Seconds to wait before restart */
+    restartSec?: number;
+    /** Environment variables */
+    environment?: Record<string, string>;
+    /** Environment file to load */
+    environmentFile?: string;
+    /** Standard output mode (default: "journal") */
+    standardOutput?: "journal" | "syslog" | "null" | "append:path";
+    /** Standard error mode */
+    standardError?: "journal" | "syslog" | "null" | "inherit";
+    /** Nice level (-20 to 19) */
+    nice?: number;
+    /** Additional unit file sections (e.g. [Install], [Unit] extras) */
+    extras?: string;
+}
+export interface ServiceResult extends ExecResult {
+    /** Path to the unit file */
+    unitPath?: string;
+}
+/**
+ * Generate a systemd unit file content from options.
+ */
+export declare function generateServiceUnit(name: string, opts: ServiceUnitOptions): string;
+/**
+ * Create and install a systemd service unit file.
+ */
+export declare function createServiceUnit(name: string, opts: ServiceUnitOptions & SudoOptions): Promise<ServiceResult>;
+/**
+ * Enable a service to start on boot.
+ */
+export declare function enableService(name: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Disable a service from starting on boot.
+ */
+export declare function disableService(name: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Start a service.
+ */
+export declare function startService(name: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Stop a service.
+ */
+export declare function stopService(name: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Restart a service.
+ */
+export declare function restartService(name: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Reload a service (sends SIGHUP).
+ */
+export declare function reloadService(name: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Get service status.
+ */
+export declare function getServiceStatus(name: string, opts: SudoOptions): Promise<ServiceStatus>;
+export interface ServiceStatus {
+    /** Whether the unit file is loaded */
+    loaded: boolean;
+    /** Whether the service is active (running) */
+    active: boolean;
+    /** Sub-state (running, exited, failed, etc.) */
+    subState: string;
+    /** Main process PID */
+    mainPid: number;
+    /** Service description */
+    description: string;
+}
+/**
+ * Enable and start a service in one call.
+ */
+export declare function enableAndStartService(name: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Check if a service exists.
+ */
+export declare function serviceExists(name: string, opts: SudoOptions): Promise<boolean>;
+/**
+ * Get service logs via journalctl.
+ */
+export declare function getServiceLogs(name: string, opts: SudoOptions & {
+    /** Number of lines to show (default: 100) */
+    lines?: number;
+    /** Follow logs */
+    follow?: boolean;
+    /** Show logs since timestamp */
+    since?: string;
+}): Promise<string>;

package/dist/systemd.js

@@ -0,0 +1,186 @@
+/**
+ * Systemd service unit creation and management.
+ * Works with both local and SSH contexts via ExecContext from sudo.ts.
+ */
+// Re-export helpers
+async function exec(args, opts) {
+    const { sudo } = await import("./sudo.js");
+    return sudo(args, opts);
+}
+async function writeFile(path, content, opts) {
+    const { writeFile: wf } = await import("./sudo.js");
+    return wf(path, content, opts);
+}
+// ---------------------------------------------------------------------------
+// Service creation
+// ---------------------------------------------------------------------------
+/**
+ * Generate a systemd unit file content from options.
+ */
+export function generateServiceUnit(name, opts) {
+    const lines = [];
+    // [Unit] section
+    lines.push("[Unit]");
+    lines.push(`Description=${opts.description}`);
+    if (opts.after?.length) {
+        lines.push(`After=${opts.after.join(" ")}`);
+    }
+    if (opts.wants?.length) {
+        lines.push(`Wants=${opts.wants.join(" ")}`);
+    }
+    lines.push("");
+    // [Service] section
+    lines.push("[Service]");
+    if (opts.type)
+        lines.push(`Type=${opts.type}`);
+    lines.push(`User=${opts.user ?? "root"}`);
+    if (opts.group)
+        lines.push(`Group=${opts.group}`);
+    lines.push(`WorkingDirectory=${opts.workingDirectory}`);
+    lines.push(`ExecStart=${opts.execStart}`);
+    if (opts.execStartPre?.length) {
+        opts.execStartPre.forEach((cmd, i) => {
+            lines.push(`ExecStartPre${i > 0 ? `=${i}` : ""}=${cmd}`);
+        });
+    }
+    if (opts.execStopPost?.length) {
+        opts.execStopPost.forEach((cmd, i) => {
+            lines.push(`ExecStopPost${i > 0 ? `=${i}` : ""}=${cmd}`);
+        });
+    }
+    if (opts.restart)
+        lines.push(`Restart=${opts.restart}`);
+    if (opts.restartSec)
+        lines.push(`RestartSec=${opts.restartSec}`);
+    if (opts.environment) {
+        Object.entries(opts.environment).forEach(([k, v]) => {
+            lines.push(`Environment="${k}=${v}"`);
+        });
+    }
+    if (opts.environmentFile) {
+        lines.push(`EnvironmentFile=${opts.environmentFile}`);
+    }
+    if (opts.standardOutput)
+        lines.push(`StandardOutput=${opts.standardOutput}`);
+    if (opts.standardError)
+        lines.push(`StandardError=${opts.standardError}`);
+    if (opts.nice !== undefined)
+        lines.push(`Nice=${opts.nice}`);
+    // Extras
+    if (opts.extras) {
+        lines.push("");
+        lines.push(opts.extras);
+    }
+    return lines.join("\n");
+}
+/**
+ * Create and install a systemd service unit file.
+ */
+export async function createServiceUnit(name, opts) {
+    const unitPath = `/etc/systemd/system/${name}.service`;
+    const content = generateServiceUnit(name, opts);
+    // Write unit file
+    const writeResult = await writeFile(unitPath, content, {
+        context: opts.context,
+        mode: "644",
+    });
+    if (!writeResult.ok) {
+        return writeResult;
+    }
+    // Reload systemd
+    await exec(["systemctl", "daemon-reload"], opts);
+    return {
+        ...writeResult,
+        unitPath,
+    };
+}
+// ---------------------------------------------------------------------------
+// Service control
+// ---------------------------------------------------------------------------
+/**
+ * Enable a service to start on boot.
+ */
+export async function enableService(name, opts) {
+    return exec(["systemctl", "enable", name], opts);
+}
+/**
+ * Disable a service from starting on boot.
+ */
+export async function disableService(name, opts) {
+    return exec(["systemctl", "disable", name], opts);
+}
+/**
+ * Start a service.
+ */
+export async function startService(name, opts) {
+    return exec(["systemctl", "start", name], opts);
+}
+/**
+ * Stop a service.
+ */
+export async function stopService(name, opts) {
+    return exec(["systemctl", "stop", name], opts);
+}
+/**
+ * Restart a service.
+ */
+export async function restartService(name, opts) {
+    return exec(["systemctl", "restart", name], opts);
+}
+/**
+ * Reload a service (sends SIGHUP).
+ */
+export async function reloadService(name, opts) {
+    return exec(["systemctl", "reload", name], opts);
+}
+/**
+ * Get service status.
+ */
+export async function getServiceStatus(name, opts) {
+    const result = await exec(["systemctl", "show", name, "--property=LoadState,ActiveState,SubState,MainPID,Description"], {
+        ...opts,
+        quiet: true,
+    });
+    if (!result.ok) {
+        return { loaded: false, active: false, subState: "unknown", mainPid: 0, description: "" };
+    }
+    const parse = (key) => {
+        const match = result.stdout.match(new RegExp(`^${key}=(.+)$`, "m"));
+        return match?.[1]?.trim() ?? "";
+    };
+    return {
+        loaded: parse("LoadState") === "loaded",
+        active: parse("ActiveState") === "active",
+        subState: parse("SubState"),
+        mainPid: parseInt(parse("MainPID") || "0", 10),
+        description: parse("Description"),
+    };
+}
+/**
+ * Enable and start a service in one call.
+ */
+export async function enableAndStartService(name, opts) {
+    return exec(["systemctl", "enable", "--now", name], opts);
+}
+/**
+ * Check if a service exists.
+ */
+export async function serviceExists(name, opts) {
+    const result = await exec(["systemctl", "list-unit-files", name + ".service"], {
+        ...opts,
+        quiet: true,
+    });
+    return result.ok && result.stdout.includes(name);
+}
+/**
+ * Get service logs via journalctl.
+ */
+export async function getServiceLogs(name, opts) {
+    const args = ["journalctl", "-u", name, "-n", String(opts.lines ?? 100)];
+    if (opts.since)
+        args.push("--since", opts.since);
+    if (!opts.follow)
+        args.push("-n", String(opts.lines ?? 100));
+    const result = await exec(args, opts);
+    return result.stdout;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@ebowwa/seedinstallation",
+  "version": "0.2.4",
+  "description": "Composable server installation utilities for edge deployment automation",
+  "author": "Ebowwa Labs <labs@ebowwa.com>",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/cheapspaces/seedInstallation#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cheapspaces/seedInstallation.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cheapspaces/seedInstallation/issues"
+  },
+  "keywords": [
+    "server",
+    "installation",
+    "provisioning",
+    "systemd",
+    "ssh",
+    "automation",
+    "devops"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "tsx": "^4.19.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./clone": {
+      "types": "./dist/clone.d.ts",
+      "import": "./dist/clone.js"
+    },
+    "./sudo": {
+      "types": "./dist/sudo.d.ts",
+      "import": "./dist/sudo.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./systemd": {
+      "types": "./dist/systemd.d.ts",
+      "import": "./dist/systemd.js"
+    },
+    "./device-auth": {
+      "types": "./dist/device-auth.d.ts",
+      "import": "./dist/device-auth.js"
+    },
+    "./bootstrap": {
+      "types": "./dist/bootstrap.d.ts",
+      "import": "./dist/bootstrap.js"
+    }
+  }
+}