@mininglamp-oss/octo-runtime 0.0.0-stage → 1.0.0

package/node_modules/@mininglamp-oss/octo-runtime-cross-service/dist/systemd.js

@@ -0,0 +1,278 @@
+/** Linux current-user service backend implemented with `systemctl --user`. */
+import { mkdir } from "node:fs/promises";
+import { dirname, join, posix } from "node:path";
+import { definitionDrift, normalizeServiceSpec, parseProperties, readDefinition, removeDefinition, runCommand, writeDefinition } from "./common.js";
+import { ServiceError } from "./errors.js";
+import { NodeCommandRunner } from "./runner.js";
+const UNIT_NAME = /^[A-Za-z0-9][A-Za-z0-9_.@-]{0,127}\.service$/;
+/**
+ * Manage a systemd user unit under the selected user's configuration home.
+ *
+ * Every manager command is scoped with `--user`. The backend neither writes a
+ * system unit nor enables lingering; setup/doctor must report when the user's
+ * systemd manager is unavailable after logout.
+ */
+export class SystemdUserBackend {
+    kind = "systemd-user";
+    #platform;
+    #runner;
+    #homeDirectory;
+    #environment;
+    #systemctl;
+    /** Build a backend for the current Linux user, with injectable dependencies for tests. */
+    constructor(options = {}) {
+        this.#platform = options.platform ?? process.platform;
+        this.#runner = options.runner ?? new NodeCommandRunner();
+        this.#homeDirectory = options.homeDirectory ?? process.env.HOME ?? "";
+        this.#environment = options.environment ?? process.env;
+        this.#systemctl = options.systemctlPath ?? "systemctl";
+    }
+    /** Report whether `systemctl --user` can reach this user's manager; no unit is written. */
+    async probe() {
+        if (this.#platform !== "linux")
+            return { supported: false, manager: this.kind, detail: "requires Linux" };
+        if (!this.#homeDirectory)
+            return { supported: false, manager: this.kind, detail: "current user home is unavailable" };
+        try {
+            const result = await runCommand(this.#runner, this.kind, this.#systemctl, ["--user", "show-environment"], {
+                checked: false,
+                env: this.#environment
+            });
+            return result.exitCode === 0
+                ? { supported: true, manager: this.kind }
+                : {
+                    supported: false,
+                    manager: this.kind,
+                    detail: (result.stderr || result.stdout).trim() || "systemd user manager is unavailable"
+                };
+        }
+        catch (error) {
+            return {
+                supported: false,
+                manager: this.kind,
+                detail: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    /** Return what systemd reports plus whether the installed unit bytes differ from `spec`. */
+    async inspect(spec) {
+        const normalized = this.#normalize(spec);
+        const unit = systemdUnit(normalized);
+        const definitionPath = this.#definitionPath(unit);
+        const actual = await readDefinition(definitionPath);
+        if (actual === undefined) {
+            return {
+                manager: this.kind,
+                state: "not_installed",
+                enabled: false,
+                definitionPath,
+                drift: ["definition_missing"]
+            };
+        }
+        const shown = await this.#show(unit);
+        if (shown.exitCode !== 0) {
+            return {
+                manager: this.kind,
+                state: "unknown",
+                enabled: false,
+                definitionPath,
+                drift: definitionDrift(actual, renderSystemdUnitNormalized(normalized)),
+                detail: (shown.stderr || shown.stdout).trim() || "systemctl show failed"
+            };
+        }
+        const properties = parseProperties(shown.stdout);
+        const pid = positiveInt(properties.MainPID);
+        const lastExitCode = optionalInt(properties.ExecMainStatus);
+        return {
+            manager: this.kind,
+            state: systemdState(properties.ActiveState, properties.SubState),
+            enabled: ["enabled", "enabled-runtime", "linked", "linked-runtime"].includes(properties.UnitFileState ?? ""),
+            pid,
+            lastExitCode,
+            definitionPath,
+            drift: definitionDrift(actual, renderSystemdUnitNormalized(normalized))
+        };
+    }
+    /**
+     * Leave the unit file and enablement matching `spec`.
+     * A stopped unit stays stopped; a running unit restarts only when its definition changed.
+     */
+    async install(spec) {
+        const normalized = this.#normalize(spec);
+        const unit = systemdUnit(normalized);
+        // Preserve the pre-reconcile process state so setup can repair configuration
+        // without accidentally starting a daemon the user intentionally stopped.
+        const previous = await this.inspect(spec);
+        await ensureOutputDirectories(normalized);
+        const changed = await writeDefinition(this.#definitionPath(unit), renderSystemdUnitNormalized(normalized));
+        // systemd must reload its unit cache before a changed file can be started.
+        if (changed)
+            await this.#command(["daemon-reload"]);
+        await this.#command([normalized.enabled ? "enable" : "disable", unit]);
+        // Apply new bytes to an existing running instance. Never use install as the
+        // first start, and never restart when the desired state is disabled.
+        if (changed && previous.state === "running" && normalized.enabled)
+            await this.#command(["restart", unit]);
+    }
+    /** Finish with the unit stopped, disabled, removed, and forgotten by the user manager. */
+    async uninstall(spec) {
+        const normalized = this.#normalize(spec);
+        const unit = systemdUnit(normalized);
+        await this.#command(["stop", unit], false);
+        await this.#command(["disable", unit], false);
+        await removeDefinition(this.#definitionPath(unit));
+        await this.#command(["daemon-reload"]);
+        await this.#command(["reset-failed", unit], false);
+    }
+    /** Add the default-target link for future user-manager activation; do not start now. */
+    async enable(spec) {
+        const unit = systemdUnit(await this.#installed(spec));
+        await this.#command(["enable", unit]);
+    }
+    /** Remove the default-target link; an already running process is deliberately left running. */
+    async disable(spec) {
+        const unit = systemdUnit(await this.#installed(spec));
+        await this.#command(["disable", unit]);
+    }
+    /** Finish with systemd reporting the unit active/starting, then let the CLI verify daemon readiness. */
+    async start(spec) {
+        const normalized = await this.#installed(spec);
+        const status = await this.inspect(spec);
+        if (!status.enabled) {
+            throw new ServiceError("SERVICE_DISABLED", "systemd service is disabled; call enable before start", { backend: this.kind });
+        }
+        if (status.state !== "running")
+            await this.#command(["start", systemdUnit(normalized)]);
+    }
+    /** Finish with no active process for the installed unit; keep the unit file and enablement. */
+    async stop(spec) {
+        const unit = systemdUnit(await this.#installed(spec));
+        await this.#command(["stop", unit]);
+    }
+    /** Finish with systemd having launched a replacement process; persistent Runtime data is unchanged. */
+    async restart(spec) {
+        const normalized = await this.#installed(spec);
+        const status = await this.inspect(spec);
+        if (!status.enabled) {
+            throw new ServiceError("SERVICE_DISABLED", "systemd service is disabled; call enable before restart", { backend: this.kind });
+        }
+        await this.#command(["restart", systemdUnit(normalized)]);
+    }
+    #normalize(spec) {
+        if (this.#platform !== "linux")
+            throw new ServiceError("UNSUPPORTED_PLATFORM", "systemd backend requires Linux");
+        if (!this.#homeDirectory)
+            throw new ServiceError("MANAGER_UNAVAILABLE", "current user home is unavailable");
+        return normalizeServiceSpec(spec, "linux");
+    }
+    async #installed(spec) {
+        const normalized = this.#normalize(spec);
+        if ((await readDefinition(this.#definitionPath(systemdUnit(normalized)))) === undefined) {
+            throw new ServiceError("NOT_INSTALLED", "systemd service is not installed", {
+                backend: this.kind
+            });
+        }
+        return normalized;
+    }
+    #definitionPath(unit) {
+        const xdg = this.#environment.XDG_CONFIG_HOME;
+        const configHome = xdg && posix.isAbsolute(xdg) ? xdg : join(this.#homeDirectory, ".config");
+        return join(configHome, "systemd", "user", unit);
+    }
+    #show(unit) {
+        return this.#command([
+            "show",
+            unit,
+            "--no-pager",
+            "--property=LoadState",
+            "--property=UnitFileState",
+            "--property=ActiveState",
+            "--property=SubState",
+            "--property=MainPID",
+            "--property=ExecMainStatus"
+        ], false);
+    }
+    #command(args, checked = true) {
+        return runCommand(this.#runner, this.kind, this.#systemctl, ["--user", ...args], {
+            checked,
+            env: this.#environment
+        });
+    }
+}
+/** Validate and render the deterministic systemd user unit for a portable spec. */
+export function renderSystemdUnit(spec) {
+    return renderSystemdUnitNormalized(normalizeServiceSpec(spec, "linux"));
+}
+function renderSystemdUnitNormalized(spec) {
+    const restart = spec.restart.policy === "never" ? "no" : spec.restart.policy;
+    const environment = Object.entries(spec.environment)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`)
+        .join("\n");
+    const output = spec.stdoutPath
+        ? `StandardOutput=${systemdQuote(`append:${spec.stdoutPath}`)}\n`
+        : "";
+    const error = spec.stderrPath
+        ? `StandardError=${systemdQuote(`append:${spec.stderrPath}`)}\n`
+        : "";
+    return `[Unit]
+Description=${escapeSystemdText(spec.description)}
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=60
+StartLimitBurst=${spec.restart.maxBurst}
+
+[Service]
+Type=simple
+ExecStart=:${[spec.command, ...spec.args].map(systemdQuote).join(" ")}
+WorkingDirectory=${systemdQuote(spec.workingDirectory)}
+${environment ? `${environment}\n` : ""}Restart=${restart}
+RestartSec=${spec.restart.delaySeconds}s
+TimeoutStopSec=${spec.timeoutStopSeconds}s
+${output}${error}
+[Install]
+WantedBy=default.target
+`;
+}
+function systemdUnit(spec) {
+    const configured = spec.names.systemdUnit;
+    const unit = configured ?? `${spec.id}.service`;
+    if (!UNIT_NAME.test(unit))
+        throw new ServiceError("INVALID_SPEC", "invalid systemd unit name");
+    return unit;
+}
+function systemdQuote(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
+}
+function escapeSystemdText(value) {
+    return value.replaceAll("%", "%%");
+}
+function systemdState(active, sub) {
+    if (active === "active")
+        return "running";
+    if (active === "activating")
+        return "starting";
+    if (active === "deactivating")
+        return "stopping";
+    if (active === "failed")
+        return "failed";
+    if (active === "inactive" || sub === "dead" || sub === "exited")
+        return "stopped";
+    return "unknown";
+}
+async function ensureOutputDirectories(spec) {
+    for (const path of [spec.stdoutPath, spec.stderrPath]) {
+        if (path)
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    }
+}
+function optionalInt(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function positiveInt(value) {
+    const parsed = optionalInt(value);
+    return parsed !== undefined && parsed > 0 ? parsed : undefined;
+}

package/node_modules/@mininglamp-oss/octo-runtime-cross-service/dist/types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Runtime-neutral contracts for managing one long-lived process with the
+ * current operating-system user's native service manager.
+ *
+ * The package deliberately models user services only. A backend never elevates
+ * privileges and a {@link ServiceSpec} must never carry enrollment credentials.
+ */
+/** Native user-service implementation selected for the current platform. */
+export type ServiceBackendKind = "launchd-user" | "systemd-user" | "windows-user-task";
+/** Manager-level process state. This does not imply daemon IPC or cloud readiness. */
+export type ServiceState = "not_installed" | "stopped" | "starting" | "running" | "stopping" | "failed" | "unknown";
+/** Portable restart modes accepted by the service contract. */
+export type ServiceRestartPolicy = "always" | "on-failure" | "never";
+/** Portable restart intent; a backend rejects policies it cannot represent faithfully. */
+export interface ServiceRestartSpec {
+    /** When the native manager should create a replacement process. */
+    policy: ServiceRestartPolicy;
+    /** Minimum delay before a restart attempt. Defaults to 5 seconds. */
+    delaySeconds?: number;
+    /** Maximum restart burst accepted by managers that expose rate limiting. Defaults to 5. */
+    maxBurst?: number;
+}
+/** Optional stable native names used instead of names derived from {@link ServiceSpec.id}. */
+export interface ServicePlatformNames {
+    /** launchd job label, without a file extension. */
+    launchdLabel?: string;
+    /** systemd user unit name, including the `.service` suffix. */
+    systemdUnit?: string;
+    /** Root Task Scheduler name, for example `\\OctoRuntime.daemon`. */
+    windowsTaskName?: string;
+}
+/**
+ * Desired portable definition of one user-owned background process.
+ *
+ * `command`, `args`, and `environment` become persistent native service
+ * configuration. Callers must pass only stable, non-sensitive values and let
+ * the daemon read credentials from its protected home at runtime.
+ */
+export interface ServiceSpec {
+    /** Stable logical identifier. It is not a display label or a credential. */
+    id: string;
+    /** Human-readable native service description. */
+    description?: string;
+    /** Absolute path to the stable Octo Runtime wrapper. */
+    command: string;
+    /** Exact argv passed to command. No shell parsing is performed. */
+    args?: readonly string[];
+    /** Absolute working directory visible to the service account. */
+    workingDirectory: string;
+    /** Non-sensitive values only. Windows user tasks do not support this field. */
+    environment?: Readonly<Record<string, string>>;
+    /** Native stdout/stderr capture where supported. The daemon remains responsible for application logs. */
+    stdoutPath?: string;
+    /** Native stderr capture path where supported. */
+    stderrPath?: string;
+    /** Whether the definition should start automatically for the user. Defaults to true. */
+    enabled?: boolean;
+    /** Native restart behavior. Defaults to `on-failure` with bounded retries. */
+    restart?: ServiceRestartSpec;
+    /** Grace period exposed to managers that support stop timeouts. Defaults to 45 seconds. */
+    timeoutStopSeconds?: number;
+    /** Explicit native identifiers; normally the portable `id` is sufficient. */
+    names?: ServicePlatformNames;
+}
+/** Result of checking whether a backend can operate in the current user session. */
+export interface ServiceProbe {
+    /** Whether the required native manager and user context are available. */
+    supported: boolean;
+    /** Backend that performed the probe, including when unsupported. */
+    manager: ServiceBackendKind;
+    /** Bounded diagnostic intended for doctor output, never a credential. */
+    detail?: string;
+}
+/** Snapshot of native service definition and process state. */
+export interface ServiceStatus {
+    /** Backend that produced the snapshot. */
+    manager: ServiceBackendKind;
+    /** Native manager state only; consumers must check IPC/cloud readiness separately. */
+    state: ServiceState;
+    /** Whether the native definition is configured for user login/boot activation. */
+    enabled: boolean;
+    /** Manager-reported main process ID when available. */
+    pid?: number;
+    /** Most recent native process exit code when available. */
+    lastExitCode?: number;
+    /** Absolute path of the managed plist, unit, or Task Scheduler XML sidecar. */
+    definitionPath?: string;
+    /** Stable drift identifiers comparing desired and installed definitions. */
+    drift: string[];
+    /** Bounded manager diagnostic when a complete snapshot cannot be produced. */
+    detail?: string;
+}
+/**
+ * Common lifecycle contract implemented by every native user-service backend.
+ *
+ * Lifecycle methods operate only on an already installed definition unless the
+ * method is explicitly {@link ServiceBackend.install}. None of them waits for
+ * application IPC or cloud readiness; the CLI owns those higher-level checks.
+ * A successful native operation therefore means "the OS manager accepted and
+ * reached the requested manager state", not "Octo Runtime is ready online".
+ */
+export interface ServiceBackend {
+    /** Stable backend discriminator. */
+    readonly kind: ServiceBackendKind;
+    /** Return whether this user can use the expected native manager, without changing any state. */
+    probe(): Promise<ServiceProbe>;
+    /** Return the installed/enabled/process snapshot and drift IDs, without repairing anything. */
+    inspect(spec: ServiceSpec): Promise<ServiceStatus>;
+    /**
+     * Make the native definition and autostart setting match `spec`.
+     * A previously stopped service stays stopped; a running service is replaced
+     * only when a changed definition must take effect.
+     */
+    install(spec: ServiceSpec): Promise<void>;
+    /**
+     * Leave no native job/task or managed definition behind.
+     * The managed process is stopped, while Runtime credentials, databases, and logs are preserved.
+     */
+    uninstall(spec: ServiceSpec): Promise<void>;
+    /** Configure an installed definition to start on the user's next login/manager activation; current process is unchanged. */
+    enable(spec: ServiceSpec): Promise<void>;
+    /** Prevent future login/manager activation; an already running process keeps running. */
+    disable(spec: ServiceSpec): Promise<void>;
+    /**
+     * Ensure the native manager has started the installed definition.
+     * Success does not prove that the daemon IPC socket or cloud Runtime is ready.
+     */
+    start(spec: ServiceSpec): Promise<void>;
+    /** Ensure the native manager no longer has a running instance; already stopped is a successful no-op. */
+    stop(spec: ServiceSpec): Promise<void>;
+    /**
+     * Ensure the manager has launched a replacement process (or started one if stopped).
+     * Success still requires a separate IPC readiness check by the caller.
+     */
+    restart(spec: ServiceSpec): Promise<void>;
+}
+/** Process-execution controls used by {@link CommandRunner}. */
+export interface CommandOptions {
+    /** Child working directory; normally omitted for native manager commands. */
+    cwd?: string;
+    /** Exact child environment. Defaults to the current process environment. */
+    env?: NodeJS.ProcessEnv;
+    /** Kill the child after this duration; zero disables the timeout. */
+    timeoutMs?: number;
+}
+/** Captured result of one native manager command. */
+export interface CommandResult {
+    /** Executable passed to the process launcher. */
+    command: string;
+    /** Exact argv passed without shell interpretation. */
+    args: readonly string[];
+    /** Numeric exit code; the default runner uses 124 for a timeout. */
+    exitCode: number;
+    /** Bounded tail of standard output. */
+    stdout: string;
+    /** Bounded tail of standard error. */
+    stderr: string;
+}
+/** Injectable shell-free process runner used by all service backends. */
+export interface CommandRunner {
+    /** Execute one command with an exact argv array and return its captured result. */
+    run(command: string, args: readonly string[], options?: CommandOptions): Promise<CommandResult>;
+}
+/**
+ * Backend construction options. Platform paths and identity fields are exposed
+ * primarily for hermetic tests and controlled packaging environments.
+ */
+export interface ServiceBackendOptions {
+    /** Platform override; defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /** Command executor override; defaults to {@link NodeCommandRunner}. */
+    runner?: CommandRunner;
+    /** Current OS user's home/profile directory. */
+    homeDirectory?: string;
+    /** Environment inherited by native manager commands. */
+    environment?: NodeJS.ProcessEnv;
+    /** macOS user id used to address the `gui/<uid>` launchd domain. */
+    uid?: number;
+    /** Windows account identity used by the task principal and logon trigger. */
+    windowsUserId?: string;
+    /** Absolute/custom launchctl executable path. */
+    launchctlPath?: string;
+    /** Absolute/custom systemctl executable path. */
+    systemctlPath?: string;
+    /** Absolute/custom schtasks executable path. */
+    schtasksPath?: string;
+    /** Absolute/custom Windows PowerShell executable path. */
+    powershellPath?: string;
+    /** Directory retaining desired Task Scheduler XML for drift inspection. */
+    windowsDefinitionDirectory?: string;
+}
+/** Validated, defaulted, immutable form consumed by platform renderers. */
+export interface NormalizedServiceSpec {
+    /** Validated portable identifier. */
+    id: string;
+    /** Non-empty description, defaulted from `id`. */
+    description: string;
+    /** Validated absolute executable path. */
+    command: string;
+    /** Frozen, credential-free argv. */
+    args: readonly string[];
+    /** Validated absolute working directory. */
+    workingDirectory: string;
+    /** Frozen, credential-free environment. */
+    environment: Readonly<Record<string, string>>;
+    /** Optional validated native stdout path. */
+    stdoutPath?: string;
+    /** Optional validated native stderr path. */
+    stderrPath?: string;
+    /** Resolved autostart state. */
+    enabled: boolean;
+    /** Restart settings with all defaults applied. */
+    restart: Required<ServiceRestartSpec>;
+    /** Resolved stop timeout in seconds. */
+    timeoutStopSeconds: number;
+    /** Frozen platform-specific naming overrides. */
+    names: ServicePlatformNames;
+}

package/node_modules/@mininglamp-oss/octo-runtime-cross-service/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Runtime-neutral contracts for managing one long-lived process with the
+ * current operating-system user's native service manager.
+ *
+ * The package deliberately models user services only. A backend never elevates
+ * privileges and a {@link ServiceSpec} must never carry enrollment credentials.
+ */
+export {};

package/node_modules/@mininglamp-oss/octo-runtime-cross-service/dist/windows-task.d.ts

@@ -0,0 +1,44 @@
+import type { ServiceBackend, ServiceBackendOptions, ServiceProbe, ServiceSpec, ServiceStatus } from "./types.js";
+/**
+ * Manage a least-privilege Task Scheduler task for the current Windows user.
+ *
+ * The task uses an `InteractiveToken` principal and a logon trigger, so it runs
+ * while that user is signed in (including while the session is locked). It is
+ * intentionally not a Windows SCM service and does not run before user logon.
+ * Desired XML is retained as a protected sidecar for deterministic drift checks.
+ */
+export declare class WindowsUserTaskBackend implements ServiceBackend {
+    #private;
+    readonly kind: "windows-user-task";
+    /** Build a backend for the current Windows user, with injectable dependencies for tests. */
+    constructor(options?: ServiceBackendOptions);
+    /** Report whether Task Scheduler and query cmdlets work for this user; no task is created. */
+    probe(): Promise<ServiceProbe>;
+    /** Return live scheduler state and exact drift from the desired XML/principal/action. */
+    inspect(spec: ServiceSpec): Promise<ServiceStatus>;
+    /**
+     * Leave the registered task and enabled setting matching `spec`.
+     * A stopped task stays stopped; a previously running task is relaunched only
+     * when the reconciled task remains enabled.
+     */
+    install(spec: ServiceSpec): Promise<void>;
+    /** Finish with no scheduled task or XML sidecar; Runtime credentials and data remain. */
+    uninstall(spec: ServiceSpec): Promise<void>;
+    /** Enable future logon/on-demand activation; do not launch the task now. */
+    enable(spec: ServiceSpec): Promise<void>;
+    /** Prevent future activation; an already running process is deliberately left running. */
+    disable(spec: ServiceSpec): Promise<void>;
+    /** Finish with Task Scheduler reporting a running/queued task, then let the CLI verify IPC. */
+    start(spec: ServiceSpec): Promise<void>;
+    /** Finish with no running task instance; keep the registered task and its logon trigger. */
+    stop(spec: ServiceSpec): Promise<void>;
+    /** Finish with a replacement task process; it continues through screen lock but not user sign-out. */
+    restart(spec: ServiceSpec): Promise<void>;
+}
+/** Validate and render deterministic Task Scheduler XML for one Windows user. */
+export declare function renderWindowsTaskXml(spec: ServiceSpec, userId: string): string;
+/**
+ * Quote one argv element with the Windows `CommandLineToArgvW` escaping rules.
+ * The returned string is suitable for Task Scheduler's single Arguments field.
+ */
+export declare function quoteWindowsArgument(value: string): string;