@phreshos/cli 0.1.5 → 0.1.7

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,45 @@ 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 version
+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` 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
+`~/.phreshos`, including Programs and owner data. Windows remains unsupported
+until the System has an equally strong local-intake authorization model there.
 
 ## create
 
@@ -55,11 +90,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

@@ -1,22 +1,27 @@
 #!/usr/bin/env node
 import { Command, Option } from "commander";
 import metadata from "../package.json" with { type: "json" };
-import { PromptCancelled } from "./prompts.js";
+import { PromptCancelled, ReportedFailure } from "./prompts.js";
 import create from "./create.js";
 import install from "./install.js";
 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();
+    .showSuggestionAfterError()
+    .configureOutput({
+    writeOut: value => process.stdout.write(spaced(value)),
+    writeErr: value => process.stderr.write(spaced(value))
+});
 program.addHelpText("after", "\nRun phresh <command> --help for detailed command guidance.\n");
 describe(program.command("create")
     .description("create a new Program project")
@@ -106,6 +111,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("");
@@ -117,11 +123,18 @@ try {
 catch (error) {
     if (error instanceof PromptCancelled)
         process.exitCode = 0;
+    else if (error instanceof ReportedFailure)
+        process.exitCode = 1;
     else {
         console.error(`\n  phresh: ${error instanceof Error ? error.message : String(error)}\n`);
         process.exitCode = 1;
     }
 }
+function spaced(value) {
+    if (value.endsWith("\n\n"))
+        return value;
+    return value.endsWith("\n") ? `${value}\n` : `${value}\n\n`;
+}
 function attached(name, summary, detail, mode) {
     describe(program.command(name)
         .description(summary)

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
@@ -60,6 +60,7 @@ export default async function create(options = {}, directory = process.cwd()) {
     console.log(bold(`\n${bundled.development ? "Run Development Program" : "Run Program"}`));
     console.log(accent(script));
     console.log(bold("\nYou can now open the project and start building your Program"));
+    console.log("");
 }
 function template() {
     const candidates = [
@@ -79,7 +80,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 +94,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 +112,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/prompts.js

@@ -1,9 +1,12 @@
 import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
 import colors from "picocolors";
-import { column, heading, line } from "./style.js";
+import { caution, column, ending, line, section } from "./style.js";
 /** Signals an ordinary interactive cancellation rather than an operation failure. */
 export class PromptCancelled extends Error {
 }
+/** An unsuccessful command whose complete explanation has already been shown. */
+export class ReportedFailure extends Error {
+}
 /**
  * One interaction language shared by commands that can ask questions.
  *
@@ -16,26 +19,32 @@ export default function prompts() {
         if (interactive)
             intro(`${colors.bold(title)}${context ? ` ${colors.dim(`· ${context}`)}` : ""}`);
         else
-            heading(title, context);
+            section(title, context);
     }
     function finish(message) {
         if (interactive)
             outro(colors.bold(message));
         else
-            heading(message);
+            ending(message);
     }
     function detail(label, value, source) {
         if (interactive)
-            log.message(`${colors.dim(column(label))}${value}${source ? `  ${colors.dim(source)}` : ""}`);
+            log.message(`${colors.dim(column(label))}${value}${source ? `  ${colors.dim(source)}` : ""}`, { spacing: 0 });
         else
             line(label, value, source);
     }
     function message(value = "") {
         if (interactive)
-            log.message(value);
+            log.message(value, { spacing: 0 });
         else
             console.log(value ? `  ${value}` : "");
     }
+    function warning(value) {
+        if (interactive)
+            log.warning(value, { spacing: 0 });
+        else
+            line("warning", caution(value));
+    }
     async function progress(message, completed, work) {
         if (!interactive)
             return await work();
@@ -55,7 +64,7 @@ export default function prompts() {
     async function ask(explanation, question, fallback) {
         if (!interactive)
             throw new Error(`${question} Supply the corresponding option when no terminal is attached`);
-        log.message(colors.dim(explanation));
+        log.message(colors.dim(explanation), { spacing: 0 });
         const value = await text({
             message: question,
             placeholder: fallback,
@@ -68,7 +77,7 @@ export default function prompts() {
     async function yes(explanation, question, fallback) {
         if (!interactive)
             throw new Error(`${question} Supply the corresponding option when no terminal is attached`);
-        log.message(colors.dim(explanation));
+        log.message(colors.dim(explanation), { spacing: 0 });
         const value = await confirm({ message: question, initialValue: fallback });
         if (isCancel(value))
             stop();
@@ -77,7 +86,7 @@ export default function prompts() {
     async function choose(explanation, question, values, fallback) {
         if (!interactive)
             throw new Error(`${question} Supply the corresponding option when no terminal is attached`);
-        log.message(colors.dim(explanation));
+        log.message(colors.dim(explanation), { spacing: 0 });
         const value = await select({
             message: question,
             options: values.map(value => ({ value, label: value })),
@@ -97,6 +106,7 @@ export default function prompts() {
         finish,
         detail,
         message,
+        warning,
         progress,
         ask,
         yes,

package/dist/style.js

@@ -3,6 +3,9 @@ import colors from "picocolors";
 export const dim = colors.dim;
 export const bold = colors.bold;
 export const accent = colors.cyan;
+export const positive = colors.green;
+export const caution = colors.yellow;
+export const negative = colors.red;
 // A label, what it says, and where that came from. The label is quiet
 // and the value is not, because the value is the thing being reported.
 //
@@ -17,6 +20,13 @@ export function column(label) {
 }
 export function heading(title, note) {
     console.log("");
+    section(title, note);
+    console.log("");
+}
+export function section(title, note) {
     console.log(`  ${bold(title)}${note ? `  ${dim("·")}  ${dim(note)}` : ""}`);
+}
+export function ending(message) {
+    console.log(`  ${bold(message)}`);
     console.log("");
 }

package/dist/system/command.js

@@ -0,0 +1,96 @@
+import SystemLifecycle from "./lifecycle.js";
+import prompts, { ReportedFailure } from "../prompts.js";
+import { accent, caution, dim, negative, positive } from "../style.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());
+        interaction.finish(`PhreshOS ${accent(status.installed?.version ?? "")} 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 the System version and operating state")
+        .action(async function () {
+        const status = await installed(current());
+        const interaction = prompts();
+        interaction.begin("System Status");
+        report(interaction, status);
+        interaction.finish(status.ready ? positive("System ready") : caution("System not ready"));
+    });
+    system.command("version")
+        .description("show the installed System version")
+        .action(async function () {
+        const status = await installed(current());
+        const interaction = prompts();
+        interaction.begin("System Version");
+        interaction.finish(`PhreshOS ${accent(status.installed.version)}`);
+    });
+    action(system, "start", "start the background service", current, lifecycle => lifecycle.start());
+    action(system, "stop", "stop the background service", current, lifecycle => lifecycle.stop());
+    action(system, "enable", "enable automatic startup", current, lifecycle => lifecycle.enable());
+    action(system, "disable", "disable automatic startup", current, lifecycle => lifecycle.disable());
+    return system;
+}
+function action(system, name, description, current, work) {
+    system.command(name)
+        .description(description)
+        .action(async function () {
+        const lifecycle = current();
+        await installed(lifecycle);
+        const interaction = prompts();
+        interaction.begin(`System ${title(name)}`);
+        await interaction.progress(`${title(name)}ing PhreshOS`, `PhreshOS ${past(name)}`, () => work(lifecycle));
+        interaction.finish(`System ${past(name)}`);
+    });
+}
+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"));
+}
+async function installed(lifecycle) {
+    const status = await lifecycle.status();
+    if (status.installed)
+        return { ...status, installed: status.installed };
+    const interaction = prompts();
+    interaction.begin("PhreshOS System");
+    interaction.warning("PhreshOS System is not installed");
+    interaction.finish(`${dim("Install it with")} ${accent("phresh system install")}`);
+    throw new ReportedFailure();
+}
+function service(status) {
+    if (status.ready)
+        return positive("ready");
+    if (status.running)
+        return caution("starting");
+    if (status.registered)
+        return caution("stopped");
+    return negative("not registered");
+}
+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";
+}