@phreshos/cli 0.1.7 → 0.1.8

package/README.md

@@ -57,12 +57,14 @@ native per-user service. The selected release and the service entry therefore
 cannot become two competing sources of truth if installation is interrupted.
 It never reads a source checkout and never requires Bun or TypeScript.
 
-The System runs under `launchd` on macOS and `systemd --user` on Linux. The
-native manager owns it after the CLI exits and restarts a failed active
-service. `start` and `stop` change current execution only; `enable` and
-`disable` change automatic startup only. `status` reports the installed version,
-service readiness, and automatic startup without changing them; `version`
-reports only the installed System release.
+The System runs under `launchd` on macOS and a real `systemd --user` manager on
+Linux. In Linux containers with no init manager, it runs as a detached
+user-owned background process that survives the terminal but ends with the
+container. Automatic startup is unavailable there rather than being reported
+as enabled. `start` and `stop` change current execution only; where a native
+manager exists, `enable` and `disable` change automatic startup only. `status`
+reports the installed version, service readiness, and automatic startup without
+changing them; `version` reports only the installed System release.
 
 Installation files and persistent System state have separate homes. Removing
 the System unregisters its service and removes its release files while keeping

package/dist/system/command.js

@@ -61,7 +61,7 @@ function action(system, name, description, current, work) {
 function report(interaction, status) {
     interaction.detail("version", accent(status.installed?.version ?? "unknown"));
     interaction.detail("service", service(status));
-    interaction.detail("startup", status.enabled ? positive("enabled") : dim("disabled"));
+    interaction.detail("startup", status.automaticStartup ? status.enabled ? positive("enabled") : dim("disabled") : dim("unavailable"));
 }
 async function installed(lifecycle) {
     const status = await lifecycle.status();

package/dist/system/lifecycle.js

@@ -35,7 +35,8 @@ export default class SystemLifecycle {
         const activation = await this.activate(prepared, previous, previousService);
         try {
             await service.register(definition(installation, executable));
-            await service.enable();
+            if ((await service.inspect()).automaticStartup)
+                await service.enable();
             await service.start();
             await this.waitUntilReady();
             await activation.commit();

package/dist/system/service/background.js

@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/**
+ * Owns the System for the lifetime of a Linux container with no init manager.
+ * Registration and the pid are user files; execution is a detached Node child.
+ */
+export default class BackgroundSystemService {
+    definition;
+    pid;
+    constructor(userHome) {
+        this.definition = join(userHome, ".config", "phreshos", "system-service.json");
+        this.pid = join(userHome, ".local", "state", "phreshos", "system.pid");
+    }
+    async inspect() {
+        const registered = existsSync(this.definition);
+        const pid = await this.readPid();
+        const running = pid !== undefined && await this.owns(pid);
+        if (pid !== undefined && !running)
+            await rm(this.pid, { force: true });
+        return {
+            registered,
+            automaticStartup: false,
+            enabled: false,
+            running,
+            ...(running ? { pid } : {})
+        };
+    }
+    async register(definition) {
+        await this.stop();
+        await atomic(this.definition, JSON.stringify(definition), 0o600);
+    }
+    async unregister() {
+        await this.stop();
+        await rm(this.definition, { force: true });
+    }
+    async start() {
+        const definition = await this.readDefinition();
+        if ((await this.inspect()).running)
+            return;
+        await mkdir(dirname(definition.output), { recursive: true });
+        const output = await open(definition.output, "a", 0o600);
+        try {
+            const child = spawn(definition.executable, [definition.entry], {
+                cwd: definition.directory,
+                detached: true,
+                stdio: ["ignore", output.fd, output.fd]
+            });
+            await new Promise(function (settle, refuse) {
+                child.once("spawn", settle);
+                child.once("error", refuse);
+            });
+            if (child.pid === undefined)
+                throw new Error("The PhreshOS System background process has no pid");
+            await atomic(this.pid, String(child.pid), 0o600);
+            child.unref();
+        }
+        finally {
+            await output.close();
+        }
+    }
+    async stop() {
+        const pid = await this.readPid();
+        if (pid === undefined)
+            return;
+        if (!await this.owns(pid)) {
+            await rm(this.pid, { force: true });
+            return;
+        }
+        process.kill(pid, "SIGTERM");
+        const until = Date.now() + 5_000;
+        while (Date.now() < until && await this.owns(pid))
+            await new Promise(settle => setTimeout(settle, 50));
+        if (await this.owns(pid))
+            process.kill(pid, "SIGKILL");
+        await rm(this.pid, { force: true });
+    }
+    async enable() {
+        throw new Error("Automatic System startup is unavailable because this Linux environment has no service manager");
+    }
+    async disable() {
+        throw new Error("Automatic System startup is unavailable because this Linux environment has no service manager");
+    }
+    async readDefinition() {
+        let value;
+        try {
+            value = JSON.parse(await readFile(this.definition, "utf8"));
+        }
+        catch {
+            throw new Error("The PhreshOS System service is not registered");
+        }
+        if (!definition(value))
+            throw new Error("The PhreshOS System service definition is invalid");
+        return value;
+    }
+    async readPid() {
+        try {
+            const value = (await readFile(this.pid, "utf8")).trim();
+            return /^[1-9][0-9]*$/.test(value) ? Number(value) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async owns(pid) {
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            return false;
+        }
+        if (process.platform !== "linux")
+            return true;
+        const definition = await this.readDefinition().catch(() => undefined);
+        if (!definition)
+            return false;
+        const command = await readFile(`/proc/${pid}/cmdline`, "utf8").catch(() => "");
+        return command.split("\0").includes(definition.entry);
+    }
+}
+async function atomic(path, content, mode) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, content, { mode });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function definition(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return ["executable", "entry", "directory", "output"].every(name => typeof candidate[name] === "string" && candidate[name] !== "");
+}

package/dist/system/service/index.js

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import LinuxSystemService from "./linux.js";
 import MacOSSystemService from "./macos.js";
-/** Select the native per-user service manager without changing its semantics. */
+/** Select the per-user service implementation available in this environment. */
 export default function systemService(platform = process.platform, userHome = homedir()) {
     if (platform === "darwin")
         return new MacOSSystemService(userHome);

package/dist/system/service/linux.js

@@ -1,99 +1,38 @@
 import { execute } from "../process.js";
-import { existsSync } from "node:fs";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { randomUUID } from "node:crypto";
+import BackgroundSystemService from "./background.js";
+import SystemdSystemService from "./systemd.js";
 const command = "systemctl";
-const unit = "phreshos.service";
+/** Selects systemd only after proving that its user manager is real. */
 export default class LinuxSystemService {
-    run;
-    file;
+    selected;
     constructor(userHome, run = execute) {
-        this.run = run;
-        this.file = join(userHome, ".config", "systemd", "user", unit);
+        this.selected = select(userHome, run);
     }
     async inspect() {
-        const registered = existsSync(this.file);
-        const active = await this.run(command, ["--user", "is-active", "--quiet", unit]);
-        const enabled = await this.run(command, ["--user", "is-enabled", "--quiet", unit]);
-        const pid = active.code === 0 ? await this.run(command, ["--user", "show", unit, "--property", "MainPID", "--value"]) : undefined;
-        const value = pid && /^[0-9]+$/.test(pid.stdout.trim()) ? Number(pid.stdout.trim()) : undefined;
-        return {
-            registered,
-            enabled: registered && enabled.code === 0,
-            running: registered && active.code === 0,
-            ...(value ? { pid: value } : {})
-        };
+        return await (await this.selected).inspect();
     }
     async register(definition) {
-        await this.stop();
-        await mkdir(dirname(this.file), { recursive: true });
-        await mkdir(dirname(definition.output), { recursive: true });
-        const temporary = `${this.file}.${randomUUID()}.tmp`;
-        try {
-            await writeFile(temporary, service(definition), { mode: 0o600 });
-            await rename(temporary, this.file);
-        }
-        finally {
-            await rm(temporary, { force: true });
-        }
-        await this.require(["--user", "daemon-reload"]);
+        await (await this.selected).register(definition);
     }
     async unregister() {
-        await this.stop();
-        await this.run(command, ["--user", "disable", unit]);
-        await rm(this.file, { force: true });
-        await this.require(["--user", "daemon-reload"]);
-        await this.run(command, ["--user", "reset-failed", unit]);
+        await (await this.selected).unregister();
     }
     async start() {
-        if (!existsSync(this.file))
-            throw new Error("The PhreshOS System service is not registered");
-        await this.require(["--user", "start", unit]);
+        await (await this.selected).start();
     }
     async stop() {
-        const state = await this.run(command, ["--user", "is-active", "--quiet", unit]);
-        if (state.code === 0)
-            await this.require(["--user", "stop", unit]);
+        await (await this.selected).stop();
     }
     async enable() {
-        if (!existsSync(this.file))
-            throw new Error("The PhreshOS System service is not registered");
-        await this.require(["--user", "enable", unit]);
+        await (await this.selected).enable();
     }
     async disable() {
-        if (!existsSync(this.file))
-            throw new Error("The PhreshOS System service is not registered");
-        await this.require(["--user", "disable", unit]);
+        await (await this.selected).disable();
     }
-    async require(args) {
-        const result = await this.run(command, args);
-        if (result.code !== 0)
-            throw new Error(result.stderr.trim() || result.stdout.trim() || `${command} exited with code ${result.code}`);
-    }
-}
-function service(definition) {
-    return `[Unit]
-Description=PhreshOS System
-
-[Service]
-Type=simple
-ExecStart=${quote(definition.executable)} ${quote(definition.entry)}
-WorkingDirectory=${setting(definition.directory)}
-Restart=on-failure
-RestartSec=2
-StandardOutput=append:${setting(definition.output)}
-StandardError=append:${setting(definition.output)}
-
-[Install]
-WantedBy=default.target
-`;
-}
-function quote(value) {
-    return JSON.stringify(value);
 }
-function setting(value) {
-    if (value.includes("\n") || value.includes("\r"))
-        throw new Error("A systemd service path cannot contain a line break");
-    return value.replaceAll("%", "%%");
+async function select(userHome, run) {
+    const result = await run(command, ["--user", "show-environment"]).catch(() => undefined);
+    const lines = result?.stdout.trim().split("\n").filter(Boolean) ?? [];
+    const systemd = result?.code === 0 && lines.length > 0 && lines.every(line => /^[a-zA-Z_][a-zA-Z0-9_]*=/.test(line));
+    return systemd ? new SystemdSystemService(userHome, run) : new BackgroundSystemService(userHome);
 }

package/dist/system/service/macos.js

@@ -29,6 +29,7 @@ export default class MacOSSystemService {
         const pid = /\bpid\s*=\s*(\d+)/.exec(service.stdout)?.[1];
         return {
             registered,
+            automaticStartup: true,
             enabled: registered && !explicitlyDisabled,
             running: service.code === 0 && /\bstate\s*=\s*running\b/.test(service.stdout),
             ...(pid ? { pid: Number(pid) } : {})

package/dist/system/service/systemd.js

@@ -0,0 +1,101 @@
+import { execute } from "../process.js";
+import { existsSync } from "node:fs";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+const command = "systemctl";
+const unit = "phreshos.service";
+/** A real systemd user manager, after Linux selection has proved it exists. */
+export default class SystemdSystemService {
+    run;
+    file;
+    constructor(userHome, run = execute) {
+        this.run = run;
+        this.file = join(userHome, ".config", "systemd", "user", unit);
+    }
+    async inspect() {
+        const registered = existsSync(this.file);
+        const active = await this.run(command, ["--user", "is-active", "--quiet", unit]);
+        const enabled = await this.run(command, ["--user", "is-enabled", "--quiet", unit]);
+        const pid = active.code === 0 ? await this.run(command, ["--user", "show", unit, "--property", "MainPID", "--value"]) : undefined;
+        const value = pid && /^[0-9]+$/.test(pid.stdout.trim()) ? Number(pid.stdout.trim()) : undefined;
+        return {
+            registered,
+            automaticStartup: true,
+            enabled: registered && enabled.code === 0,
+            running: registered && active.code === 0,
+            ...(value ? { pid: value } : {})
+        };
+    }
+    async register(definition) {
+        await this.stop();
+        await mkdir(dirname(this.file), { recursive: true });
+        await mkdir(dirname(definition.output), { recursive: true });
+        const temporary = `${this.file}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, service(definition), { mode: 0o600 });
+            await rename(temporary, this.file);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+        await this.require(["--user", "daemon-reload"]);
+    }
+    async unregister() {
+        await this.stop();
+        await this.run(command, ["--user", "disable", unit]);
+        await rm(this.file, { force: true });
+        await this.require(["--user", "daemon-reload"]);
+        await this.run(command, ["--user", "reset-failed", unit]);
+    }
+    async start() {
+        if (!existsSync(this.file))
+            throw new Error("The PhreshOS System service is not registered");
+        await this.require(["--user", "start", unit]);
+    }
+    async stop() {
+        const state = await this.run(command, ["--user", "is-active", "--quiet", unit]);
+        if (state.code === 0)
+            await this.require(["--user", "stop", unit]);
+    }
+    async enable() {
+        if (!existsSync(this.file))
+            throw new Error("The PhreshOS System service is not registered");
+        await this.require(["--user", "enable", unit]);
+    }
+    async disable() {
+        if (!existsSync(this.file))
+            throw new Error("The PhreshOS System service is not registered");
+        await this.require(["--user", "disable", unit]);
+    }
+    async require(args) {
+        const result = await this.run(command, args);
+        if (result.code !== 0)
+            throw new Error(result.stderr.trim() || result.stdout.trim() || `${command} exited with code ${result.code}`);
+    }
+}
+function service(definition) {
+    return `[Unit]
+Description=PhreshOS System
+
+[Service]
+Type=simple
+ExecStart=${quote(definition.executable)} ${quote(definition.entry)}
+WorkingDirectory=${setting(definition.directory)}
+Restart=on-failure
+RestartSec=2
+StandardOutput=append:${setting(definition.output)}
+StandardError=append:${setting(definition.output)}
+
+[Install]
+WantedBy=default.target
+`;
+}
+function quote(value) {
+    return JSON.stringify(value);
+}
+function setting(value) {
+    if (value.includes("\n") || value.includes("\r"))
+        throw new Error("A systemd service path cannot contain a line break");
+    return value.replaceAll("%", "%%");
+}

package/dist/template/package.json

@@ -16,7 +16,7 @@
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.7",
+        "@phreshos/cli": "^0.1.8",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.7",
+    "version": "0.1.8",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"