@phreshos/cli 0.1.56 → 0.1.57

package/dist/commands/input.js

@@ -1,3 +1,4 @@
+import { parseLaunch } from "@phreshos/core";
 export function payload(value) {
     if (value === undefined)
         return undefined;
@@ -46,6 +47,8 @@ export function launch(options, named = false) {
     const result = {};
     if (options.name !== undefined)
         result.name = options.name;
+    if (options.replace !== undefined)
+        result.replace = options.replace;
     if (server !== undefined)
         result.server = server;
     if (client !== undefined)
@@ -54,7 +57,7 @@ export function launch(options, named = false) {
         result.options = values;
     if (named && !result.name)
         throw new Error("--name is required");
-    return result;
+    return parseLaunch(result);
 }
 export function clientLaunch(options) {
     const service = options.clientService;

package/dist/commands/options.js

@@ -1,3 +1,4 @@
+import { layers } from "@phreshos/core";
 import { collect, integer } from "./input.js";
 export const jsonOption = option("--json", "write the result as machine-readable JSON on one line");
 export const processOptions = Object.freeze([
@@ -16,7 +17,7 @@ export const clientOverrideOptions = Object.freeze([
     option("--client-height <value>", "initial Window height"),
     option("--client-x <value>", "initial Window horizontal position"),
     option("--client-y <value>", "initial Window vertical position"),
-    option("--client-layer <layer>", "initial Window layer", { choices: ["window", "under", "over"] }),
+    option("--client-layer <layer>", "initial Window layer", { choices: layers }),
     option("--client-minimized", "open the Window minimized"),
     option("--client-maximized", "open the Window maximized")
 ]);
@@ -30,6 +31,7 @@ export const launchOptions = Object.freeze([
     option("--no-client", "do not start the Client Endpoint"),
     ...clientOverrideOptions,
     option("--name <name>", "stable Program-local Process name"),
+    option("--replace", "terminate and replace the Process with --name"),
     option("--server", "start the Server Endpoint"),
     option("--no-server", "do not start the Server Endpoint"),
     option("--option <name=value>", "immutable Process option; repeat for more values", {

package/dist/commands/program.js

@@ -80,9 +80,9 @@ export default function programCommands(root, connect) {
 async function eventView(event, message, scoped) {
     if (event === "uninstall") {
         if (scoped)
-            return { program: await programView(scoped), everything: message === true };
+            return { program: await programView(scoped), purge: message === true };
         const current = message;
-        return { program: await programView(current.program), everything: current.everything };
+        return { program: await programView(current.program), purge: current.purge };
     }
     if (scoped)
         return programView(scoped);

package/dist/commands/project.js

@@ -85,7 +85,7 @@ export default function projectCommands(program, coreRange) {
         name: "install",
         description: "install a local or official Program",
         arguments: [{ syntax: "[name]", description: "name of an official Program" }],
-        options: [option("--run", "run the installed Program now")],
+        options: [option("--run", "launch the installed Program before startup"), option("--purge", "delete existing installed Program storage")],
         guidance: [
             "Without a name, builds and installs the Program declared by this project.",
             "A name installs its verified official production release. --run launches the installed Program now."
@@ -94,22 +94,22 @@ export default function projectCommands(program, coreRange) {
         examples: ["phresh install", "phresh install terminal --run"],
         output: textOutput("Installed Program and optional Process identity")
     }, async ({ arguments: [name], options }) => {
-        await install({ name, run: options.run === true });
+        await install({ name, run: options.run === true, purge: options.purge === true });
     });
     defineCommand(program, {
         name: "uninstall",
         description: "uninstall a local or installed Program",
         arguments: [{ syntax: "[name]", description: "name of an installed Program" }],
-        options: [option("--everything", "also remove Processes, data, and runtime state")],
+        options: [option("--purge", "also remove Processes, data, and runtime state")],
         guidance: [
             "Without a name, uses the Program declared by this project.",
-            "Removes installed files while preserving Processes, data, and runtime Program state unless --everything is supplied."
+            "Removes installed files while preserving Processes, data, and runtime Program state unless --purge is supplied."
         ],
         requiresSystem: true,
-        examples: ["phresh uninstall", "phresh uninstall terminal --everything"],
+        examples: ["phresh uninstall", "phresh uninstall terminal --purge"],
         output: textOutput("Uninstalled Program state")
     }, async ({ arguments: [name], options }) => {
-        await uninstall({ name, everything: options.everything === true });
+        await uninstall({ name, purge: options.purge === true });
     });
     attached(program, "start", "run the production Program without installing", [
         "Runs this Program attached to the terminal. Output arrives here, and ending this command stops the Program.",

package/dist/commands/schemas.js

@@ -1,3 +1,4 @@
+import { layers } from "@phreshos/core";
 import { value } from "../contract/schema.js";
 const metric = {
     anyOf: [value.number("pixels"), value.string("workspace-relative expression")]
@@ -12,7 +13,7 @@ const clientDeclaration = value.nullable(value.object({
     title: value.nullable(value.string("default Window title")),
     size: value.nullable(value.object({ width: metric, height: metric }, ["width", "height"], "default Window size")),
     position: value.nullable(value.object({ x: metric, y: metric }, ["x", "y"], "default Window position")),
-    layer: value.nullable(value.enumeration(["window", "under", "over"], "default Window layer")),
+    layer: value.nullable(value.enumeration(layers, "default Window layer")),
     minimize: value.nullable(value.boolean("default minimized state")),
     maximize: value.nullable(value.boolean("default maximized state"))
 }, ["start", "service", "title", "size", "position", "layer", "minimize", "maximize"], "resolved Client Endpoint declaration"));
@@ -51,7 +52,7 @@ export const windowOutput = value.object({
     minimized: value.boolean("whether the Window is minimized"),
     maximized: value.boolean("whether the Window is maximized"),
     front: value.boolean("whether the Window is at the front of its layer"),
-    layer: value.enumeration(["window", "under", "over"], "Window layer")
+    layer: value.enumeration(layers, "Window layer")
 }, ["process", "title", "position", "size", "minimized", "maximized", "front", "layer"], "Window state");
 export const programPresentation = fields(["Identity", "identity"], ["Asset", "assetId"], ["Name", "name"], ["Version", "version"], ["Description", "description"], ["Installed", "installed"], ["Agent", "hasAgent"], ["Server", "server"], ["Client", "client"]);
 export const programListPresentation = table("data", "Program", "Programs", "No matching Programs", [

package/dist/install.js

@@ -15,8 +15,8 @@ import { prepareOfficialProgram } from "./program-release.js";
  * production Program is derived and sent. The command remains authoring
  * metadata and never becomes part of the installed Program.
  *
- * The System applies the Program's startup declaration during installation.
- * `run` explicitly requests an additional Process. A run created here belongs
+ * The System executes the Program's stored startup after installation.
+ * `run` requests an additional Process before startup, created by System. It belongs
  * to the installed Program and
  * therefore outlives this command; `phresh start` and `phresh dev` remain
  * attached authoring runs whose lifetime is the terminal's.
@@ -33,7 +33,7 @@ export default async function install(options = {}) {
             const { name, identity, version } = result.program;
             heading(`${name || identity}${version ? ` ${version}` : ""}`, result.replaced ? "reinstalled" : "installed");
             if (result.replaced)
-                console.log(`  ${dim("its storage was kept, and its previous processes were ended")}`);
+                console.log(`  ${dim(options.purge ? "its storage was deleted, and its previous processes were ended" : "its storage was kept, and its previous processes were ended")}`);
             if (result.process)
                 line("process", result.process);
             if (result.replaced || result.process)

package/dist/program-installation.js

@@ -9,6 +9,7 @@ export default async function installProgram(program, options = {}) {
     let installed = null;
     let process = null;
     let installationFinished = false;
+    let stopObserving;
     try {
         if (program instanceof Project) {
             await program.build();
@@ -16,22 +17,24 @@ export default async function installProgram(program, options = {}) {
         }
         else
             installed = await system.program.forceCreate(program);
-        for await (const chunk of installed.install())
+        if (options.run)
+            stopObserving = installed.process.subscribe("create", created => { process ??= created.identity; });
+        for await (const chunk of installed.install({ launch: options.run ? true : undefined, purge: options.purge }))
             writeProgramCommandOutput(chunk);
         installationFinished = true;
-        if (options.run)
-            process = (await installed.process.create()).identity;
     }
     catch (error) {
         if (installed && !installationFinished) {
             try {
-                await installed.forget();
+                if (!await installed.installed())
+                    await installed.forget();
             }
             catch { /* Preserve the installation failure. */ }
         }
         throw error;
     }
     finally {
+        stopObserving?.();
         await system.disconnect();
     }
     if (!installed)

package/dist/system/command.js

@@ -3,6 +3,7 @@ import prompts, { ReportedFailure } from "../prompts.js";
 import { accent, caution, dim, negative, positive } from "../style.js";
 import { defineCommand } from "../contract/command.js";
 import { textOutput } from "../commands/schemas.js";
+import { option } from "../commands/options.js";
 /** Attach the System lifecycle without mixing it with Program commands. */
 export default function systemCommands(program, provided) {
     let lifecycle = provided;
@@ -15,18 +16,26 @@ export default function systemCommands(program, provided) {
             "Running-System Programs, Processes, Endpoints, and Windows are top-level capabilities, not System subcommands."
         ]
     });
-    defineCommand(system, lifecycleContract("install", "install or update the System and start its service"), async function () {
+    defineCommand(system, {
+        ...lifecycleContract("install", "install or update the System and start its service"),
+        options: [option("--purge", "delete PHRESHOS_HOME before starting the installed System")]
+    }, async function ({ options }) {
         const interaction = prompts();
         interaction.begin("Install System", "official stable release");
-        const status = await interaction.progress("Installing PhreshOS", "PhreshOS installed", () => current().install());
+        const status = await interaction.progress("Installing PhreshOS", "PhreshOS installed", () => current().install(options));
+        if (options.purge)
+            interaction.message("Previous System data was deleted.");
         interaction.detail("desktop", accent(status.desktop));
         interaction.finish(`PhreshOS ${accent(status.installed?.version ?? "")} installed`);
     });
-    defineCommand(system, lifecycleContract("uninstall", "remove the System installation and service"), async function () {
+    defineCommand(system, {
+        ...lifecycleContract("uninstall", "remove the System installation and service"),
+        options: [option("--purge", "also delete PHRESHOS_HOME")]
+    }, async function ({ options }) {
         const interaction = prompts();
         interaction.begin("Uninstall System");
-        await interaction.progress("Removing PhreshOS", "PhreshOS removed", () => current().uninstall());
-        interaction.message("Persistent System data was kept.");
+        await interaction.progress("Removing PhreshOS", "PhreshOS removed", () => current().uninstall(options));
+        interaction.message(options.purge ? "Persistent System data was deleted." : "Persistent System data was kept.");
         interaction.finish("System uninstalled");
     });
     defineCommand(system, lifecycleContract("status", "show the System version and operating state"), async function () {

package/dist/system/installation.js

@@ -1,7 +1,8 @@
 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 { dirname, isAbsolute, join, parse, relative, resolve } from "node:path";
+import { homedir } from "node:os";
 import { requireSuccess } from "./process.js";
 import npmInvocation from "./npm.js";
 import { minimumSystemNodeVersion } from "./node.js";
@@ -144,6 +145,16 @@ export default class SystemInstallation {
     async remove() {
         await rm(this.paths.root, { recursive: true, force: true });
     }
+    /** Removes the selected System's persistent home, never a broad host directory. */
+    async purgeStorage() {
+        const storage = resolve(this.paths.storage);
+        const installation = relative(storage, resolve(this.paths.root));
+        if (storage === parse(storage).root || storage === resolve(homedir())
+            || installation === "" || (!installation.startsWith(`..`) && !isAbsolute(installation))) {
+            throw new Error("PHRESHOS_HOME cannot be purged because it contains host or System installation files");
+        }
+        await rm(storage, { recursive: true, force: true });
+    }
     async removeOtherReleases(current) {
         for (const entry of await readdir(this.paths.releases, { withFileTypes: true })) {
             if (!entry.isDirectory())

package/dist/system/lifecycle.js

@@ -24,10 +24,10 @@ export default class SystemLifecycle {
             provisionSetup: dependencies?.provisionSetup ?? provisionSetup
         };
     }
-    async install() {
-        return await this.dependencies.installation.exclusive(() => this.installExclusive());
+    async install(options = {}) {
+        return await this.dependencies.installation.exclusive(() => this.installExclusive(options.purge === true));
     }
-    async installExclusive() {
+    async installExclusive(purge) {
         const { installation, service } = this.dependencies;
         const previous = await installation.current();
         const previousService = await service.inspect();
@@ -35,7 +35,7 @@ export default class SystemLifecycle {
         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);
+        const activation = await this.activate(prepared, previous, previousService, purge);
         try {
             await service.register(definition(installation, executable));
             if ((await service.inspect()).automaticStartup)
@@ -62,10 +62,10 @@ export default class SystemLifecycle {
         }
         return await this.status();
     }
-    async uninstall() {
-        return await this.dependencies.installation.exclusive(() => this.uninstallExclusive());
+    async uninstall(options = {}) {
+        return await this.dependencies.installation.exclusive(() => this.uninstallExclusive(options.purge === true));
     }
-    async uninstallExclusive() {
+    async uninstallExclusive(purge) {
         const { installation, service } = this.dependencies;
         const state = await service.inspect();
         if (state.running)
@@ -74,6 +74,8 @@ export default class SystemLifecycle {
             await service.disable();
         if (state.registered)
             await service.unregister();
+        if (purge)
+            await installation.purgeStorage();
         await installation.remove();
     }
     async start() {
@@ -145,11 +147,13 @@ export default class SystemLifecycle {
             throw new Error(`${message}${log}`, { cause: error });
         }
     }
-    async activate(prepared, previous, state) {
+    async activate(prepared, previous, state, purge) {
         const { installation, service } = this.dependencies;
         try {
             if (state.running)
                 await service.stop();
+            if (purge)
+                await installation.purgeStorage();
             return await installation.activate(prepared, previous);
         }
         catch (error) {

package/dist/template/package.json

@@ -1,7 +1,7 @@
 {
     "name": "phresh",
     "private": true,
-    "version": "0.1.34",
+    "version": "0.1.35",
     "description": "The official PhreshOS starter Program.",
     "type": "module",
     "scripts": {
@@ -14,15 +14,15 @@
         "starter"
     ],
     "dependencies": {
-        "@phreshos/client": "^0.1.40",
-        "@phreshos/core": "^0.1.45",
-        "@phreshos/react": "^0.1.22",
-        "@phreshos/server": "^0.1.44",
+        "@phreshos/client": "^0.1.41",
+        "@phreshos/core": "^0.1.47",
+        "@phreshos/react": "^0.1.23",
+        "@phreshos/server": "^0.1.45",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.56",
+        "@phreshos/cli": "^0.1.57",
         "@types/node": "^26.4.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.5",

package/dist/template/phresh.config.ts

@@ -4,7 +4,7 @@ export default defineConfig({
     identity: "phresh",
     name: "Phresh Program",
     description: "A minimal counter with direct Client and Server endpoints.",
-    version: "0.1.34",
+    version: "0.1.35",
     icon: "icon.png",
     categories: ["Development"],
     keywords: ["example", "counter", "client", "server"],

package/dist/template.json

@@ -1,6 +1,6 @@
 {
     "repository": "PhreshOS/phresh-program",
-    "version": "0.1.34",
-    "sha256": "b4b743675ef96244be903e50f46bf4c7b5c51a8a726eb4e08a4d02cbc6d1aabb",
+    "version": "0.1.35",
+    "sha256": "8443820f5347137a6156de257b4971a7ee723827eceea664c6eeac5ee697bd6d",
     "development": true
 }

package/dist/uninstall.js

@@ -11,10 +11,10 @@ export default async function uninstall(options = {}) {
         const program = await system.program.find(identity);
         if (!program)
             throw new Error("The System does not know this Program");
-        for await (const chunk of program.uninstall(options.everything === true))
+        for await (const chunk of program.uninstall({ purge: options.purge }))
             writeProgramCommandOutput(chunk);
         heading(identity, "uninstalled");
-        console.log(options.everything
+        console.log(options.purge
             ? `  ${dim("Its processes, installed files, stored data, and runtime record were removed.")}`
             : `  ${dim("Its installed files were removed. Processes, stored data, and runtime state were kept.")}`);
         blank();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@phreshos/cli",
   "type": "module",
-  "version": "0.1.56",
+  "version": "0.1.57",
   "description": "The Phresh command-line interface for Program projects and system management.",
   "engines": {
     "node": ">=20.10"
@@ -47,8 +47,8 @@
   "packageManager": "bun@1.3.14",
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@phreshos/core": "^0.1.45",
-    "@phreshos/node": "^0.1.20",
+    "@phreshos/core": "^0.1.47",
+    "@phreshos/node": "^0.1.21",
     "adm-zip": "^0.6.0",
     "cli-table3": "^0.6.5",
     "commander": "^15.0.0",