@phreshos/cli 0.1.5 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zohayr SLILEH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,7 @@
 # @phreshos/cli
 
-The `phresh` command for creating, running, packaging, installing, and
-uninstalling Programs.
+The `phresh` command for creating and operating Programs, and for installing
+and managing the PhreshOS System on the current machine.
 
 ## Package status
 
@@ -21,6 +21,7 @@ phresh install  # lay this program out on this machine
 phresh uninstall # remove its installed form
 phresh start    # run what your build left, and stay with it
 phresh dev      # run from source, and stay with it
+phresh system status # inspect the local System and its background service
 ```
 
 `phresh --help` lists them, `phresh <command> --help` explains one, and
@@ -28,11 +29,44 @@ phresh dev      # run from source, and stay with it
 unknown command, an unknown flag and a malformed option are each refused
 and named.
 
-**This tool acts on the current project, and the list ends there.** It is
-not the machine's control panel — it accepts no arbitrary program identity
-and has no word for a process, a window, a store or a setting. The system's
-local intake accepts exactly the Program this project declares, and so does
-this tool.
+Every top-level Program command acts on the current project, and that list ends
+there. It accepts no arbitrary Program identity and has no word for a Process,
+Window, store, or setting. Machine lifecycle is isolated under `phresh system`;
+it manages the System installation and native service, not the state inside the
+System.
+
+## System lifecycle
+
+```bash
+phresh system install
+phresh system uninstall
+phresh system status
+phresh system start
+phresh system stop
+phresh system enable
+phresh system disable
+```
+
+`install` resolves the newest compatible stable release from the official
+[`PhreshOS/system`](https://github.com/PhreshOS/system) GitHub Releases. It
+downloads the production archive and adjacent checksum, verifies every byte,
+installs production dependencies into a staged version directory, atomically
+points the stable `current` path at it, then registers, enables, and starts the
+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` reads installation,
+registration, startup, process, and local-intake readiness without changing
+any of them.
+
+Installation files and persistent System state have separate homes. Removing
+the System unregisters its service and removes its release files while keeping
+`~/.phreshos`, including Programs and owner data. Windows remains unsupported
+until the System has an equally strong local-intake authorization model there.
 
 ## create
 
@@ -55,11 +89,9 @@ phresh create status-board \
 ```
 
 Dependencies are installed by default. `--no-install` creates the same valid
-project and leaves installation as the first reported next step. A project
-created inside this repository's workspace uses its sibling dev-kits through
-the workspace protocol. A standalone project, including one created by a
-distributed CLI, uses the published versions embedded in the template. Both
-choices pass through the same dependency resolver used by `init`.
+project and leaves installation as the first reported next step. Generated and
+initialized Programs always use the published package ranges embedded in the
+CLI; repository layout never changes dependency meaning.
 
 ## Saying something to a program you start
 

package/dist/cli.js

@@ -8,12 +8,13 @@ import launch from "./launch.js";
 import init from "./init.js";
 import pack from "./pack.js";
 import uninstall from "./uninstall.js";
+import systemCommands from "./system/command.js";
 const { version } = metadata;
 const coreRange = metadata.dependencies["@phreshos/core"];
 const runOptionPrefix = "--run-option-";
 const program = new Command()
     .name("phresh")
-    .description("Create and manage Programs")
+    .description("Create Programs and manage PhreshOS")
     .version(version, "-v, --version")
     .showHelpAfterError()
     .showSuggestionAfterError();
@@ -106,6 +107,7 @@ attached("dev", "run the development Program without installing", [
     "Runs the same attached lifecycle as start using the development",
     "declarations. A Client URL must respond within 15 seconds before launch."
 ], "development");
+systemCommands(program);
 // Every command begins with the same breathing room. Keep this at the entry
 // point so individual commands never need to manufacture their own opening.
 console.log("");

package/dist/create.js

@@ -1,4 +1,4 @@
-import { projectDependency, installProjectDependencies, projectPackageManager, projectScript } from "./project-dependency.js";
+import { installProjectDependencies, projectPackageManager, projectScript } from "./project-dependency.js";
 import prompts from "./prompts.js";
 import { accent, bold } from "./style.js";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
@@ -36,7 +36,7 @@ export default async function create(options = {}, directory = process.cwd()) {
     try {
         cpSync(bundled.directory, staging, { recursive: true });
         renameSync(resolve(staging, "gitignore"), resolve(staging, ".gitignore"));
-        customize(staging, target, identity, name, manager);
+        customize(staging, identity, name, manager);
         renameSync(staging, target);
         placed = true;
         // A project inside this repository becomes a real workspace member
@@ -79,7 +79,7 @@ function template() {
     }
     throw new Error("The CLI template has not been built — run its build command and try again");
 }
-function customize(directory, finalDirectory, identity, name, manager) {
+function customize(directory, identity, name, manager) {
     for (const path of textFiles(directory)) {
         let content = readFileSync(path, "utf-8");
         content = content.replaceAll("phresh-program", identity).replaceAll("Phresh Program", name);
@@ -93,15 +93,6 @@ function customize(directory, finalDirectory, identity, name, manager) {
     const manifestPath = resolve(directory, "package.json");
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
     manifest.name = identity;
-    for (const dependencies of [manifest.dependencies, manifest.devDependencies]) {
-        if (!dependencies)
-            continue;
-        for (const [dependency, range] of Object.entries(dependencies)) {
-            if (!isProjectPackage(dependency))
-                continue;
-            dependencies[dependency] = projectDependency(dependency, range, finalDirectory).manifestSpecifier;
-        }
-    }
     writeFileSync(manifestPath, JSON.stringify(manifest, null, 4) + "\n");
 }
 function textFiles(directory) {
@@ -120,13 +111,6 @@ function packageManager(value) {
         return value;
     throw new Error(`The package manager must be bun, npm, pnpm, or yarn; received "${value}"`);
 }
-function isProjectPackage(value) {
-    return value === "@phreshos/core"
-        || value === "@phreshos/client"
-        || value === "@phreshos/server"
-        || value === "@phreshos/react"
-        || value === "@phreshos/cli";
-}
 function title(identity) {
     return identity.split("-").map(word => word[0].toUpperCase() + word.slice(1)).join(" ");
 }

package/dist/project-dependency.js

@@ -1,37 +1,11 @@
 import { line } from "./style.js";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, relative, resolve } from "node:path";
+import { resolve } from "node:path";
 /** Returns the package-manager command that runs one project script. */
 export function projectScript(directory, declared, script) {
     return `${projectPackageManager(directory, declared).name} run ${script}`;
 }
-/**
- * Resolves an SDK through the one source policy shared by `init` and `create`.
- *
- * A Program inside this repository's workspace uses its sibling dev-kit. A
- * standalone project or distributed CLI keeps the published range embedded
- * in the generated template. Local packages therefore never leak their own
- * workspace-only development graph into an unrelated project.
- */
-export function projectDependency(name, range, directory) {
-    const workspaceDirectory = resolve(import.meta.dirname, "..", "..", "..");
-    const workspace = manifestAt(workspaceDirectory);
-    const sourceDirectory = resolve(import.meta.dirname, "..", "..", localDirectories[name]);
-    const manifest = manifestAt(sourceDirectory);
-    if (workspace?.name === "@phreshos/workspace" && workspaceIncludes(workspaceDirectory, directory, workspace.workspaces) && manifest?.name === name && manifest.version && accepts(range, manifest.version)) {
-        return {
-            installSpecifier: `${name}@workspace:*`,
-            manifestSpecifier: "workspace:*",
-            local: true
-        };
-    }
-    return {
-        installSpecifier: `${name}@${range}`,
-        manifestSpecifier: range,
-        local: false
-    };
-}
 /** Detects the package manager declared by, present in, or invoking a project. */
 export function projectPackageManager(directory, declared, preferred) {
     const named = preferred ?? packageManagerName(declared) ?? packageManagerFromLocks(directory) ?? packageManagerFromInvocation();
@@ -57,9 +31,8 @@ export default async function ensureProjectDependency(name, range, directory = p
     if (manifest.dependencies?.[name] || manifest.devDependencies?.[name])
         return;
     const manager = projectPackageManager(directory, manifest.packageManager);
-    const source = projectDependency(name, range, directory);
-    line("dependency", name, `${manager.name}, ${source.local ? "local dev-kit" : range}`);
-    await run(manager.name, [...manager.addArgs(section), source.installSpecifier], directory);
+    line("dependency", name, `${manager.name}, ${range}`);
+    await run(manager.name, [...manager.addArgs(section), `${name}@${range}`], directory);
     console.log("");
 }
 function run(command, args, directory, output = "inherit") {
@@ -85,21 +58,6 @@ function run(command, args, directory, output = "inherit") {
         });
     });
 }
-function accepts(range, version) {
-    return range === "workspace:*" || range === version || range === `^${version}` || range === `~${version}`;
-}
-function workspaceIncludes(root, directory, patterns) {
-    const local = relative(root, resolve(directory)).replaceAll("\\", "/");
-    if (!local || local === ".." || local.startsWith("../") || isAbsolute(local))
-        return false;
-    return patterns?.some(function (pattern) {
-        if (!pattern.endsWith("/*"))
-            return local === pattern;
-        const prefix = pattern.slice(0, -1);
-        const child = local.startsWith(prefix) ? local.slice(prefix.length) : "";
-        return Boolean(child) && !child.includes("/");
-    }) ?? false;
-}
 function manifestAt(directory) {
     const path = resolve(directory, "package.json");
     if (!existsSync(path))
@@ -132,13 +90,6 @@ function packageManagerFromInvocation() {
 function isPackageManager(value) {
     return value === "bun" || value === "npm" || value === "pnpm" || value === "yarn";
 }
-const localDirectories = {
-    "@phreshos/core": "core-sdk",
-    "@phreshos/client": "client-sdk",
-    "@phreshos/server": "server-sdk",
-    "@phreshos/react": "react-sdk",
-    "@phreshos/cli": "cli"
-};
 const managers = {
     bun: {
         name: "bun",

package/dist/system/command.js

@@ -0,0 +1,70 @@
+import SystemLifecycle from "./lifecycle.js";
+import prompts from "../prompts.js";
+/** Attach the System lifecycle without mixing it with Program commands. */
+export default function systemCommands(program, provided) {
+    let lifecycle = provided;
+    const current = () => lifecycle ?? (lifecycle = new SystemLifecycle());
+    const system = program.command("system").description("install and manage the PhreshOS System");
+    system.command("install")
+        .description("install or update the System and start its service")
+        .action(async function () {
+        const interaction = prompts();
+        interaction.begin("Install System", "official stable release");
+        const status = await interaction.progress("Installing PhreshOS", "PhreshOS installed", () => current().install());
+        report(interaction, status);
+        interaction.finish("System installed");
+    });
+    system.command("uninstall")
+        .description("remove the System installation and service")
+        .action(async function () {
+        const interaction = prompts();
+        interaction.begin("Uninstall System");
+        await interaction.progress("Removing PhreshOS", "PhreshOS removed", () => current().uninstall());
+        interaction.message("Persistent System data was kept.");
+        interaction.finish("System uninstalled");
+    });
+    system.command("status")
+        .description("show installation, service, and readiness state")
+        .action(async function () {
+        const interaction = prompts();
+        interaction.begin("System Status");
+        report(interaction, await current().status());
+    });
+    action(system, "start", "start the background service", () => current().start());
+    action(system, "stop", "stop the background service", () => current().stop());
+    action(system, "enable", "enable automatic startup", () => current().enable());
+    action(system, "disable", "disable automatic startup", () => current().disable());
+    return system;
+}
+function action(system, name, description, work) {
+    system.command(name)
+        .description(description)
+        .action(async function () {
+        const interaction = prompts();
+        interaction.begin(`System ${title(name)}`);
+        const status = await interaction.progress(`${title(name)}ing PhreshOS`, `PhreshOS ${past(name)}`, work);
+        report(interaction, status);
+        interaction.finish(`System ${past(name)}`);
+    });
+}
+function report(interaction, status) {
+    interaction.detail("installation", status.installed ? `installed · ${status.installed.version}` : "not installed");
+    interaction.detail("service", status.registered ? "registered" : "not registered");
+    interaction.detail("startup", status.enabled ? "enabled" : "disabled");
+    interaction.detail("process", status.running ? `running${status.pid ? ` · ${status.pid}` : ""}` : "stopped");
+    interaction.detail("intake", status.ready ? `ready · ${status.intake}` : "not ready");
+    interaction.detail("files", status.root);
+    interaction.detail("log", status.log);
+}
+function title(value) {
+    return `${value[0]?.toUpperCase()}${value.slice(1)}`;
+}
+function past(value) {
+    if (value === "stop")
+        return "stopped";
+    if (value === "enable")
+        return "enabled";
+    if (value === "disable")
+        return "disabled";
+    return "started";
+}

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,174 @@
+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 { 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);
+            throw new Error(`${message}. Service log: ${installation.paths.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}`);
+}

package/dist/system/service/linux.js

@@ -0,0 +1,94 @@
+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";
+export default class LinuxSystemService {
+    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,
+            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=${quote(definition.directory)}
+Restart=on-failure
+RestartSec=2
+StandardOutput=append:${quote(definition.output)}
+StandardError=append:${quote(definition.output)}
+
+[Install]
+WantedBy=default.target
+`;
+}
+function quote(value) {
+    return JSON.stringify(value);
+}

package/dist/system/service/macos.js

@@ -0,0 +1,123 @@
+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 = "/bin/launchctl";
+const defaultLabel = "com.phreshos.system";
+export default class MacOSSystemService {
+    run;
+    label;
+    plist;
+    domain;
+    target;
+    constructor(userHome, run = execute, label = defaultLabel) {
+        this.run = run;
+        this.label = label;
+        const uid = process.getuid?.();
+        if (uid === undefined)
+            throw new Error("The current macOS user could not be identified");
+        this.plist = join(userHome, "Library", "LaunchAgents", `${this.label}.plist`);
+        this.domain = `gui/${uid}`;
+        this.target = `${this.domain}/${this.label}`;
+    }
+    async inspect() {
+        const registered = existsSync(this.plist);
+        const service = await this.run(command, ["print", this.target]);
+        const disabled = await this.run(command, ["print-disabled", this.domain]);
+        const explicitlyDisabled = new RegExp(`"${escapePattern(this.label)}"\\s*=>\\s*(?:true|disabled)`).test(disabled.stdout);
+        const pid = /\bpid\s*=\s*(\d+)/.exec(service.stdout)?.[1];
+        return {
+            registered,
+            enabled: registered && !explicitlyDisabled,
+            running: service.code === 0 && /\bstate\s*=\s*running\b/.test(service.stdout),
+            ...(pid ? { pid: Number(pid) } : {})
+        };
+    }
+    async register(definition) {
+        await this.stop();
+        await mkdir(dirname(this.plist), { recursive: true });
+        await mkdir(dirname(definition.output), { recursive: true });
+        const temporary = `${this.plist}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, plist(this.label, definition), { mode: 0o600 });
+            await rename(temporary, this.plist);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    async unregister() {
+        await this.stop();
+        await rm(this.plist, { force: true });
+    }
+    async start() {
+        if (!existsSync(this.plist))
+            throw new Error("The PhreshOS System service is not registered");
+        const state = await this.inspect();
+        if (state.running)
+            return;
+        const loaded = await this.run(command, ["print", this.target]);
+        if (loaded.code === 0)
+            await this.require(["kickstart", "-k", this.target]);
+        else
+            await this.require(["bootstrap", this.domain, this.plist]);
+    }
+    async stop() {
+        const loaded = await this.run(command, ["print", this.target]);
+        if (loaded.code === 0)
+            await this.require(["bootout", this.target]);
+    }
+    async enable() {
+        if (!existsSync(this.plist))
+            throw new Error("The PhreshOS System service is not registered");
+        await this.require(["enable", this.target]);
+    }
+    async disable() {
+        if (!existsSync(this.plist))
+            throw new Error("The PhreshOS System service is not registered");
+        await this.require(["disable", this.target]);
+    }
+    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 plist(label, definition) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${xml(label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${xml(definition.executable)}</string>
+        <string>${xml(definition.entry)}</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${xml(definition.directory)}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>2</integer>
+    <key>StandardOutPath</key>
+    <string>${xml(definition.output)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xml(definition.output)}</string>
+</dict>
+</plist>
+`;
+}
+function xml(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+function escapePattern(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/template/package.json

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

package/package.json

@@ -1,12 +1,19 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.5",
+    "version": "0.1.6",
     "description": "The Phresh command-line interface for Program projects and system management.",
+    "engines": {
+        "node": ">=20.10"
+    },
     "scripts": {
         "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
         "compile": "tsc --noEmit false --outDir dist --rootDir source --rewriteRelativeImportExtensions true --allowImportingTsExtensions true",
         "build": "node --run clean && node --run compile && node dist/build-template.js",
+        "test": "node --run compile && node --test tests/*.test.mjs",
+        "verify": "node --run build && node --run test && node scripts/verify-package.mjs",
+        "verify:system-release": "node --run compile && node scripts/verify-system-release.mjs",
+        "verify:macos-service": "node --run compile && node scripts/verify-macos-service.mjs",
         "prepack": "node --run build"
     },
     "bin": {
@@ -14,8 +21,29 @@
     },
     "files": [
         "dist",
+        "LICENSE",
         "README.md"
     ],
+    "author": "Zohayr SLILEH",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/PhreshOS/cli.git"
+    },
+    "bugs": {
+        "url": "https://github.com/PhreshOS/cli/issues"
+    },
+    "homepage": "https://github.com/PhreshOS/cli#readme",
+    "keywords": [
+        "phreshos",
+        "cli",
+        "program"
+    ],
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "packageManager": "bun@1.3.14",
     "dependencies": {
         "@clack/prompts": "^1.7.0",
         "@phreshos/core": "^0.1.1",