@phreshos/cli 0.1.5 → 0.1.7

package/dist/system/installation.js

@@ -0,0 +1,241 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { mkdir, mkdtemp, open, readFile, readdir, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { requireSuccess } from "./process.js";
+import AdmZip from "adm-zip";
+/** Owns immutable release directories and the one atomic active record. */
+export default class SystemInstallation {
+    paths;
+    dependencies;
+    constructor(paths, dependencies = installProductionDependencies) {
+        this.paths = paths;
+        this.dependencies = dependencies;
+    }
+    async current() {
+        let directory;
+        let value;
+        try {
+            directory = resolve(dirname(this.paths.current), await readlink(this.paths.current));
+            value = JSON.parse(await readFile(join(directory, ".release.json"), "utf8"));
+        }
+        catch (error) {
+            if (record(error) && error.code === "ENOENT")
+                return undefined;
+            throw new Error(`The System current release is invalid: ${this.paths.current}`);
+        }
+        const within = relative(this.paths.releases, directory);
+        if (!releaseRecord(value) || isAbsolute(within) || within.startsWith("..") || within === "") {
+            throw new Error(`The System current release is invalid: ${this.paths.current}`);
+        }
+        if (!existsSync(join(directory, "server", "main.js")))
+            throw new Error(`The installed System ${value.version} is incomplete`);
+        return { ...value, directory };
+    }
+    /** Serialize operations that can change files or native-service state. */
+    async exclusive(work) {
+        await mkdir(this.paths.root, { recursive: true });
+        const lock = join(this.paths.root, ".operation");
+        const owner = String(process.pid);
+        while (true) {
+            try {
+                const handle = await open(lock, "wx", 0o600);
+                try {
+                    await handle.writeFile(`${owner}\n`);
+                    return await work();
+                }
+                finally {
+                    await handle.close();
+                    await rm(lock, { force: true });
+                }
+            }
+            catch (error) {
+                if (!record(error) || error.code !== "EEXIST")
+                    throw error;
+                const pid = await lockOwner(lock);
+                if (pid !== undefined && processAlive(pid))
+                    throw new Error(`Another PhreshOS System operation is running (${pid})`);
+                const stale = `${lock}.stale-${randomUUID()}`;
+                try {
+                    await rename(lock, stale);
+                    await rm(stale, { force: true });
+                }
+                catch (replacement) {
+                    if (!record(replacement) || replacement.code !== "ENOENT")
+                        throw replacement;
+                }
+            }
+        }
+    }
+    async prepare(release) {
+        await mkdir(this.paths.releases, { recursive: true });
+        const directory = await mkdtemp(join(this.paths.releases, ".staging-"));
+        try {
+            extract(release.bytes, directory);
+            await validateDistribution(directory);
+            await this.dependencies(directory);
+            return { release, directory };
+        }
+        catch (error) {
+            await rm(directory, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    async abandon(prepared) {
+        await rm(prepared.directory, { recursive: true, force: true });
+    }
+    async activate(prepared, previous) {
+        const directory = join(this.paths.releases, prepared.release.version);
+        const backup = `${directory}.previous-${randomUUID()}`;
+        const hadDirectory = existsSync(directory);
+        const installedAt = new Date().toISOString();
+        if (hadDirectory)
+            await rename(directory, backup);
+        try {
+            await writeFile(join(prepared.directory, ".release.json"), `${JSON.stringify({
+                version: prepared.release.version,
+                digest: prepared.release.digest,
+                installedAt
+            }, null, 2)}\n`, { mode: 0o600 });
+            await rename(prepared.directory, directory);
+            await this.pointTo(directory);
+        }
+        catch (error) {
+            await rm(directory, { recursive: true, force: true });
+            if (hadDirectory)
+                await rename(backup, directory);
+            if (previous)
+                await this.pointTo(previous.directory);
+            throw error;
+        }
+        const installed = {
+            version: prepared.release.version,
+            digest: prepared.release.digest,
+            directory,
+            installedAt
+        };
+        let settled = false;
+        return {
+            installed,
+            commit: async () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (hadDirectory)
+                    await rm(backup, { recursive: true, force: true });
+                await this.removeOtherReleases(directory).catch(() => undefined);
+            },
+            rollback: async () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (previous)
+                    await this.pointTo(previous.directory);
+                else
+                    await rm(this.paths.current, { force: true });
+                await rm(directory, { recursive: true, force: true });
+                if (hadDirectory)
+                    await rename(backup, directory);
+            }
+        };
+    }
+    async remove() {
+        await rm(this.paths.root, { recursive: true, force: true });
+    }
+    async removeOtherReleases(current) {
+        for (const entry of await readdir(this.paths.releases, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const directory = join(this.paths.releases, entry.name);
+            if (directory !== current)
+                await rm(directory, { recursive: true, force: true });
+        }
+    }
+    async pointTo(directory) {
+        await mkdir(dirname(this.paths.current), { recursive: true });
+        const temporary = `${this.paths.current}.${randomUUID()}.tmp`;
+        try {
+            await symlink(relative(dirname(this.paths.current), directory), temporary, "dir");
+            await rename(temporary, this.paths.current);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+}
+async function validateDistribution(directory) {
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(join(directory, "package.json"), "utf8"));
+    }
+    catch {
+        throw new Error("The System release has no valid production package manifest");
+    }
+    if (!record(manifest) || manifest.type !== "module" || !record(manifest.scripts) || manifest.scripts.start !== "node server/main.js" || !record(manifest.dependencies)) {
+        throw new Error("The System release package manifest is invalid");
+    }
+    for (const path of ["server/main.js", "client/index.html"]) {
+        if (!existsSync(join(directory, path)))
+            throw new Error(`The System release is missing ${path}`);
+    }
+}
+function extract(bytes, directory) {
+    const archive = new AdmZip(bytes);
+    for (const entry of archive.getEntries()) {
+        const name = entry.entryName.replaceAll("\\", "/");
+        const destination = resolve(directory, name);
+        const within = relative(directory, destination);
+        if (!name || name.startsWith("/") || name.split("/").includes("..") || isAbsolute(within) || within.startsWith("..")) {
+            throw new Error(`The System release contains an unsafe path: ${entry.entryName}`);
+        }
+        if (entry.isDirectory) {
+            requireDirectory(destination);
+            continue;
+        }
+        requireDirectory(dirname(destination));
+        writeFileSync(destination, entry.getData(), { mode: 0o600 });
+    }
+}
+function requireDirectory(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+}
+async function installProductionDependencies(directory) {
+    const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+    await requireSuccess(npm, ["install", "--omit=dev", "--no-audit", "--no-fund", "--package-lock=false"], { cwd: directory });
+}
+function releaseRecord(value) {
+    return record(value)
+        && typeof value.version === "string"
+        && /^[0-9]+\.[0-9]+\.[0-9]+$/.test(value.version)
+        && typeof value.digest === "string"
+        && /^[a-f0-9]{64}$/.test(value.digest)
+        && typeof value.installedAt === "string";
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function lockOwner(path) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const value = (await readFile(path, "utf8")).trim();
+            if (/^[1-9][0-9]*$/.test(value))
+                return Number(value);
+        }
+        catch (error) {
+            if (!record(error) || error.code !== "ENOENT")
+                throw error;
+            return undefined;
+        }
+        await new Promise(settle => setTimeout(settle, 50));
+    }
+    return undefined;
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return record(error) && error.code === "EPERM";
+    }
+}

package/dist/system/lifecycle.js

@@ -0,0 +1,176 @@
+import SystemInstallation from "./installation.js";
+import { downloadSystemRelease, resolveSystemRelease } from "./release.js";
+import { intakeReady, waitForIntake } from "./readiness.js";
+import systemPaths from "./paths.js";
+import systemService from "./service/index.js";
+import nodeExecutable from "./node.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/** Coordinates acquisition, immutable files, and the native service as one transaction. */
+export default class SystemLifecycle {
+    dependencies;
+    constructor(dependencies) {
+        const paths = systemPaths();
+        const service = dependencies?.service ?? systemService();
+        this.dependencies = {
+            installation: dependencies?.installation ?? new SystemInstallation(paths),
+            service,
+            resolveRelease: dependencies?.resolveRelease ?? resolveSystemRelease,
+            downloadRelease: dependencies?.downloadRelease ?? downloadSystemRelease,
+            ready: dependencies?.ready ?? intakeReady,
+            wait: dependencies?.wait ?? waitForIntake
+        };
+    }
+    async install() {
+        return await this.dependencies.installation.exclusive(() => this.installExclusive());
+    }
+    async installExclusive() {
+        const { installation, service } = this.dependencies;
+        const previous = await installation.current();
+        const previousService = await service.inspect();
+        const executable = await nodeExecutable();
+        const release = await this.dependencies.resolveRelease();
+        const downloaded = await this.dependencies.downloadRelease(release);
+        const prepared = await installation.prepare(downloaded);
+        const activation = await this.activate(prepared, previous, previousService);
+        try {
+            await service.register(definition(installation, executable));
+            await service.enable();
+            await service.start();
+            await this.waitUntilReady();
+            await activation.commit();
+            return await this.status();
+        }
+        catch (error) {
+            await service.stop().catch(() => undefined);
+            await activation.rollback();
+            return await this.restoredFailure(error, previous, previousService);
+        }
+    }
+    async uninstall() {
+        return await this.dependencies.installation.exclusive(() => this.uninstallExclusive());
+    }
+    async uninstallExclusive() {
+        const { installation, service } = this.dependencies;
+        const state = await service.inspect();
+        if (state.running)
+            await service.stop();
+        if (state.enabled)
+            await service.disable();
+        if (state.registered)
+            await service.unregister();
+        await installation.remove();
+    }
+    async start() {
+        return await this.dependencies.installation.exclusive(() => this.startExclusive());
+    }
+    async startExclusive() {
+        await this.requireInstalledService();
+        await this.dependencies.service.start();
+        await this.waitUntilReady();
+        return await this.status();
+    }
+    async stop() {
+        return await this.dependencies.installation.exclusive(() => this.stopExclusive());
+    }
+    async stopExclusive() {
+        await this.requireInstalledService();
+        await this.dependencies.service.stop();
+        return await this.status();
+    }
+    async enable() {
+        return await this.dependencies.installation.exclusive(() => this.enableExclusive());
+    }
+    async enableExclusive() {
+        await this.requireInstalledService();
+        await this.dependencies.service.enable();
+        return await this.status();
+    }
+    async disable() {
+        return await this.dependencies.installation.exclusive(() => this.disableExclusive());
+    }
+    async disableExclusive() {
+        await this.requireInstalledService();
+        await this.dependencies.service.disable();
+        return await this.status();
+    }
+    async status() {
+        const { installation, service } = this.dependencies;
+        const [installed, state] = await Promise.all([installation.current(), service.inspect()]);
+        const ready = state.running && await this.dependencies.ready(installation.paths.intake);
+        return {
+            ...(installed ? { installed } : {}),
+            ...state,
+            ready,
+            root: installation.paths.root,
+            intake: installation.paths.intake,
+            log: installation.paths.log
+        };
+    }
+    async requireInstalledService() {
+        const [installed, state] = await Promise.all([
+            this.dependencies.installation.current(),
+            this.dependencies.service.inspect()
+        ]);
+        if (!installed)
+            throw new Error("PhreshOS System is not installed — run phresh system install");
+        if (!state.registered)
+            throw new Error("The PhreshOS System service is not registered — run phresh system install");
+    }
+    async waitUntilReady() {
+        const { installation, service } = this.dependencies;
+        try {
+            await this.dependencies.wait(installation.paths.intake, async () => (await service.inspect()).running);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const log = existsSync(installation.paths.log) ? `. Service log: ${installation.paths.log}` : "";
+            throw new Error(`${message}${log}`, { cause: error });
+        }
+    }
+    async activate(prepared, previous, state) {
+        const { installation, service } = this.dependencies;
+        try {
+            if (state.running)
+                await service.stop();
+            return await installation.activate(prepared, previous);
+        }
+        catch (error) {
+            await installation.abandon(prepared);
+            return await this.restoredFailure(error, previous, state);
+        }
+    }
+    async restore(previous, state) {
+        const { installation, service } = this.dependencies;
+        if (!previous) {
+            await service.unregister().catch(() => undefined);
+            return;
+        }
+        await service.register(definition(installation, await nodeExecutable()));
+        if (state.enabled)
+            await service.enable();
+        else
+            await service.disable();
+        if (state.running) {
+            await service.start();
+            await this.waitUntilReady();
+        }
+    }
+    async restoredFailure(error, previous, state) {
+        try {
+            await this.restore(previous, state);
+        }
+        catch (restoration) {
+            throw new AggregateError([error, restoration], "The System update failed and its previous service could not be restored");
+        }
+        throw error;
+    }
+}
+function definition(installation, executable) {
+    return {
+        executable,
+        entry: join(installation.paths.current, "server", "main.js"),
+        directory: installation.paths.current,
+        output: installation.paths.log
+    };
+}

package/dist/system/node.js

@@ -0,0 +1,13 @@
+import { isAbsolute } from "node:path";
+import { requireSuccess } from "./process.js";
+/** Resolve the real Node executable even when another runtime invoked the CLI. */
+export default async function nodeExecutable() {
+    if (!process.versions.bun && process.release.name === "node" && isAbsolute(process.execPath))
+        return process.execPath;
+    const command = process.platform === "win32" ? "node.exe" : "node";
+    const result = await requireSuccess(command, ["-p", "process.execPath"]);
+    const executable = result.stdout.trim();
+    if (!isAbsolute(executable))
+        throw new Error("A real Node.js executable is required to run the PhreshOS System service");
+    return executable;
+}

package/dist/system/paths.js

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+/** The installation is separate from the persistent state it operates on. */
+export default function systemPaths(platform = process.platform, userHome = homedir(), variables = process.env) {
+    const storage = join(userHome, ".phreshos");
+    const root = platform === "darwin"
+        ? join(userHome, "Library", "Application Support", "PhreshOS", "System")
+        : platform === "linux"
+            ? join(absoluteOr(variables.XDG_DATA_HOME, join(userHome, ".local", "share"), "XDG_DATA_HOME"), "phreshos", "system")
+            : platform === "win32"
+                ? join(absoluteOr(variables.LOCALAPPDATA, join(userHome, "AppData", "Local"), "LOCALAPPDATA"), "PhreshOS", "System")
+                : join(userHome, ".local", "share", "phreshos", "system");
+    return {
+        root,
+        releases: join(root, "releases"),
+        current: join(root, "current"),
+        storage,
+        intake: join(storage, "intake.sock"),
+        log: join(storage, "service.log")
+    };
+}
+function absoluteOr(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!isAbsolute(value))
+        throw new Error(`${name} must be an absolute filesystem path`);
+    return value;
+}

package/dist/system/process.js

@@ -0,0 +1,23 @@
+import { spawn } from "node:child_process";
+/** Execute one exact program without involving a command shell. */
+export function execute(command, args, options = {}) {
+    return new Promise(function (settle, refuse) {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8").on("data", chunk => stdout += chunk);
+        child.stderr.setEncoding("utf8").on("data", chunk => stderr += chunk);
+        child.once("error", refuse);
+        child.once("close", code => settle({ code: code ?? 1, stdout, stderr }));
+    });
+}
+export async function requireSuccess(command, args, options) {
+    const result = await execute(command, args, options);
+    if (result.code !== 0)
+        throw new Error(result.stderr.trim() || result.stdout.trim() || `${command} exited with code ${result.code}`);
+    return result;
+}

package/dist/system/readiness.js

@@ -0,0 +1,29 @@
+import { connect } from "node:net";
+export async function intakeReady(path) {
+    return await new Promise(function (settle) {
+        const socket = connect(path);
+        const timeout = setTimeout(() => finish(false), 500);
+        let finished = false;
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+        function finish(ready) {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timeout);
+            socket.destroy();
+            settle(ready);
+        }
+    });
+}
+export async function waitForIntake(path, running, timeout = 15_000) {
+    const until = Date.now() + timeout;
+    while (Date.now() < until) {
+        if (await intakeReady(path))
+            return;
+        if (!await running())
+            throw new Error("The PhreshOS System stopped before its intake became ready");
+        await new Promise(settle => setTimeout(settle, 100));
+    }
+    throw new Error(`The PhreshOS System did not become ready within ${Math.ceil(timeout / 1000)} seconds`);
+}

package/dist/system/release.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+const releases = "https://api.github.com/repos/PhreshOS/system/releases?per_page=100";
+const compatible = { major: 0, minor: 1 };
+/** Resolve the newest stable release in the System line supported by this CLI. */
+export async function resolveSystemRelease(fetcher = fetch) {
+    const response = await fetcher(releases, {
+        headers: {
+            Accept: "application/vnd.github+json",
+            "User-Agent": "@phreshos/cli"
+        },
+        signal: AbortSignal.timeout(30_000)
+    });
+    if (!response.ok)
+        throw new Error(`The System release list could not be read (${response.status} ${response.statusText})`);
+    return selectSystemRelease(await response.json());
+}
+export function selectSystemRelease(value) {
+    if (!Array.isArray(value))
+        throw new Error("The System release list is invalid");
+    const candidates = value.flatMap(function (item) {
+        if (!record(item) || item.draft === true || item.prerelease === true || typeof item.tag_name !== "string" || !Array.isArray(item.assets))
+            return [];
+        const version = parseVersion(item.tag_name);
+        if (!version || version.major !== compatible.major || version.minor !== compatible.minor)
+            return [];
+        const archiveName = `phreshos@${version.value}.zip`;
+        const checksumName = `${archiveName}.sha256`;
+        const archive = asset(item.assets, archiveName);
+        const checksum = asset(item.assets, checksumName);
+        return archive && checksum ? [{ version: version.value, archive, checksum }] : [];
+    });
+    candidates.sort((left, right) => compare(right.version, left.version));
+    const selected = candidates[0];
+    if (!selected)
+        throw new Error(`No compatible PhreshOS System ${compatible.major}.${compatible.minor}.x release is available`);
+    return selected;
+}
+/** Download both release assets and refuse any byte not named by the checksum. */
+export async function downloadSystemRelease(release, fetcher = fetch) {
+    const [archive, checksum] = await Promise.all([
+        fetchAsset(release.archive, fetcher),
+        fetchAsset(release.checksum, fetcher)
+    ]);
+    const bytes = Buffer.from(await archive.arrayBuffer());
+    const said = (await checksum.text()).trim();
+    const name = `phreshos@${release.version}.zip`;
+    const match = /^([a-f0-9]{64})\s+(.+)$/i.exec(said);
+    if (!match || match[2] !== name)
+        throw new Error(`The checksum for ${name} is invalid`);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== match[1]?.toLowerCase())
+        throw new Error(`The downloaded ${name} does not match its SHA-256 checksum`);
+    return { ...release, bytes, digest };
+}
+async function fetchAsset(url, fetcher) {
+    const response = await fetcher(url, {
+        headers: { "User-Agent": "@phreshos/cli" },
+        signal: AbortSignal.timeout(120_000)
+    });
+    if (!response.ok)
+        throw new Error(`A System release asset could not be downloaded (${response.status} ${response.statusText})`);
+    return response;
+}
+function asset(assets, name) {
+    const found = assets.find(item => record(item) && item.name === name && typeof item.browser_download_url === "string");
+    return record(found) && typeof found.browser_download_url === "string" ? found.browser_download_url : undefined;
+}
+function parseVersion(tag) {
+    const match = /^v(\d+)\.(\d+)\.(\d+)$/.exec(tag);
+    if (!match)
+        return undefined;
+    return {
+        value: tag.slice(1),
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3])
+    };
+}
+function compare(left, right) {
+    const a = left.split(".").map(Number);
+    const b = right.split(".").map(Number);
+    return (a[0] ?? 0) - (b[0] ?? 0) || (a[1] ?? 0) - (b[1] ?? 0) || (a[2] ?? 0) - (b[2] ?? 0);
+}
+function record(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/system/service/index.js

@@ -0,0 +1,11 @@
+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. */
+export default function systemService(platform = process.platform, userHome = homedir()) {
+    if (platform === "darwin")
+        return new MacOSSystemService(userHome);
+    if (platform === "linux")
+        return new LinuxSystemService(userHome);
+    throw new Error(`PhreshOS System services are not supported on ${platform}`);
+}