@phreshos/cli 0.1.21 → 0.1.23

package/README.md

@@ -22,21 +22,35 @@ 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 program list # inspect authoritative state in the running System
+phresh describe endpoint ask # read one capability's exact contract
 ```
 
 `phresh --help` lists them, `phresh <command> --help` explains one, and
-`phresh --version` says which CLI you have. Nothing is guessed: an
+`phresh --version` says which CLI you have. `phresh describe [path...]` exposes
+the same complete command tree as machine-readable contracts. Nothing is guessed: an
 unknown command, an unknown flag and a malformed option are each refused
 and named.
 
-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.
+Program authoring commands act on the current project when no Program name is
+provided. `install` and `uninstall` accept a direct Program name. Running-System
+capabilities live in the top-level `program`, `process`, `endpoint`, and `window`
+namespaces. System execution and native lifecycle remain isolated under
+`phresh system`.
 
 ## System lifecycle
 
+Run a System project or prepared release directly while selecting an independent
+absolute state home:
+
+```bash
+PHRESHOS_HOME=/absolute/state phresh system .
+```
+
+When `PHRESHOS_HOME` is omitted here, the CLI passes `~/.phreshos`. Running the
+System project itself without the CLI instead defaults to that project's
+`storage/` directory.
+
 ```bash
 phresh system install
 phresh system uninstall
@@ -70,7 +84,7 @@ 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. Local Program intake uses an
+`~/.phreshos`, including Programs and owner data. The owner-local gateway uses an
 owner-only socket file on POSIX and an owner-created duplex named pipe on
 Windows; neither becomes a network endpoint or introduces a bearer secret.
 
@@ -297,9 +311,9 @@ say `start: false`.
 Both **run your program without installing it, and stay attached.** They
 print the `program.json` it will be declared as, hand that to the system
 through the socket below the selected system home. With no override, that is
-`~/.phreshos/intake.sock`. Set `PHRESHOS_HOME` to an absolute system home to
+`~/.phreshos/gateway.sock`. Set `PHRESHOS_HOME` to an absolute system home to
 address another system instance; the CLI derives
-`<PHRESHOS_HOME>/intake.sock` from it. The socket is not selected
+`<PHRESHOS_HOME>/gateway.sock` from it. The socket is not selected
 separately from its instance. Only your account can open it, so nothing is
 sent to prove anything, and then the command holds.
 
@@ -326,7 +340,7 @@ untouched while the attached Program becomes the sole runtime occupant. Its
 root process tethers the whole Program to this command; when it exits, remaining
 processes end and the runtime record disappears. A later `phresh install` can
 replace the preserved installed files and immediately register the identity as
-installed again. If no system is listening, the intake says so plainly rather
+installed again. If no system is listening, the gateway says so plainly rather
 than exposing `ENOENT`.
 
 An attached Program still owns persistent project storage. The authoring tool
@@ -354,15 +368,19 @@ beside your source. A client development URL remains the URL the author wrote.
 
 ```bash
 phresh install   # this project, laid out on this machine
+phresh install flambo   # the official Flambo Program
 ```
 
-**It takes no package, and neither does the system.** What is sent is
+Without a name, what is sent is
 the description this directory derives, and the system copies what it
 names into place — your program's parts are already on this disk at the
 locations it names, so there is nothing an archive would carry that the
 description does not already point at. `phresh pack` is for when you have
 somewhere to send a program; installing here is a different act.
 
+With a name, the CLI resolves and verifies that official Program's production
+release directly; the current directory is irrelevant.
+
 If `buildCommand` is declared, it completes successfully before anything is
 sent to the system. Without it, install uses the production files exactly as
 they stand.
@@ -372,7 +390,7 @@ marked installed, and reconstructed after a restart. Running is the other one:
 `phresh start` / `phresh dev` register it under its declared identity and
 attach its whole lifetime to your terminal.
 
-The command installs through the machine's local intake. A running
+The command installs through the machine's local gateway. A running
 Program may also install itself through the server SDK; installation is not a
 client capability.
 
@@ -388,6 +406,7 @@ bytes and no path. You have the paths.
 
 ```bash
 phresh uninstall
+phresh uninstall flambo
 phresh uninstall --everything
 ```
 
@@ -401,8 +420,9 @@ that Server directory before removing files. `phresh uninstall` writes its
 ordered `stdout` and `stderr` chunks as they arrive. A failed cleanup command
 aborts removal and reports the failure.
 
-The identity comes from this project's `phresh.config.ts`; the command does not
-accept an arbitrary Program identity.
+Without a name, the identity comes from this project's `phresh.config.ts`.
+With a name, the installed Program is addressed directly and the current
+directory is irrelevant.
 
 ## What pack produces
 

package/dist/attach.js

@@ -1,4 +1,4 @@
-import speak, { socketPath } from "./program-intake.js";
+import { gatewayPath, streamProgram } from "./gateway.js";
 /**
  * Run a program on this machine's system, and stay with it.
  *
@@ -11,9 +11,9 @@ import speak, { socketPath } from "./program-intake.js";
  * end — when the program ends, the system says so and closes, and this
  * resolves with the program's own status.
  */
-export default async function attach(program, options = {}, watching = {}, path = socketPath, signal) {
+export default async function attach(program, options = {}, watching = {}, path = gatewayPath(), signal) {
     let ended = null;
-    await speak({ word: "run", program, options }, function (event) {
+    await streamProgram({ word: "run", program, options }, function (event) {
         if (event.event === "started")
             watching.started?.(String(event.process));
         if (event.event === "output")

package/dist/cli.js

@@ -9,6 +9,9 @@ import init from "./init.js";
 import pack from "./pack.js";
 import uninstall from "./uninstall.js";
 import systemCommands from "./system/command.js";
+import controlCommands from "./control-command.js";
+import describeCommands from "./describe-command.js";
+import { commandContract } from "./command-contract.js";
 const { version } = metadata;
 const coreRange = metadata.dependencies["@phreshos/core"];
 const runOptionPrefix = "--run-option-";
@@ -22,6 +25,7 @@ const program = new Command()
     writeOut: value => process.stdout.write(spaced(value)),
     writeErr: value => process.stderr.write(spaced(value))
 });
+commandContract(program);
 program.addHelpText("after", "\nRun phresh <command> --help for detailed command guidance.\n");
 describe(program.command("create")
     .description("create a new Program project")
@@ -96,12 +100,14 @@ describe(program.command("install")
     "it now; --startup persists the same default launch for future starts."
 ]);
 describe(program.command("uninstall")
-    .description("uninstall this Program")
+    .description("uninstall a local or installed Program")
+    .argument("[name]", "name of an installed Program")
     .option("--everything", "also remove Processes, data, and runtime state")
-    .action(async function (options) {
-    await uninstall(options.everything === true);
+    .action(async function (name, options) {
+    await uninstall({ name, everything: options.everything === true });
 }), [
-    "Removes the installed Program files while preserving its Processes, data,",
+    "Without a name, uses the Program declared by this project. Removes its",
+    "installed files while preserving its Processes, data,",
     "and runtime Program. --everything removes all system-owned state."
 ]);
 attached("start", "run the production Program without installing", [
@@ -114,6 +120,8 @@ attached("dev", "run the development Program without installing", [
     "declarations. A Client URL must respond within 15 seconds before launch."
 ], "development");
 systemCommands(program);
+controlCommands(program);
+describeCommands(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("");
@@ -148,6 +156,7 @@ function attached(name, summary, detail, mode) {
 }
 function describe(command, paragraphs) {
     command.addHelpText("after", `\n${paragraphs.map(line => line ? `  ${line}` : "").join("\n")}\n`);
+    commandContract(command, { guidance: paragraphs.filter(Boolean) });
     return command;
 }
 function runOptions(command, args) {

package/dist/command-contract.js

@@ -0,0 +1,12 @@
+const contracts = new WeakMap();
+/** Attach machine-readable policy to the same Commander node that owns syntax. */
+export function commandContract(command, contract = {}) {
+    contracts.set(command, Object.freeze({
+        ...contract,
+        ...(contract.guidance ? { guidance: Object.freeze([...contract.guidance]) } : {})
+    }));
+    return command;
+}
+export function readCommandContract(command) {
+    return contracts.get(command);
+}

package/dist/control-client.js

@@ -0,0 +1,7 @@
+import { requestSystem } from "./gateway.js";
+/** Owner-local client for the authoritative running-System contract. */
+export default class LocalSystemControl {
+    execute(request, signal) {
+        return requestSystem(request, undefined, signal);
+    }
+}

package/dist/control-command.js

@@ -0,0 +1,50 @@
+import { systemControl, systemControlOperation } from "@phreshos/core";
+import LocalSystemControl from "./control-client.js";
+import { commandContract } from "./command-contract.js";
+/** Build the top-level running-System commands from Core's authoritative catalog. */
+export default function controlCommands(program, provided) {
+    let client = provided;
+    const current = () => client ?? (client = new LocalSystemControl());
+    for (const [capabilityName, capability] of Object.entries(systemControl)) {
+        const group = commandContract(program.command(capabilityName)
+            .description(capability.description)
+            .addHelpText("after", `\nOperating guidance:\n${capability.guidance.map(item => `  - ${item}`).join("\n")}\n`), {
+            guidance: capability.guidance,
+            capability
+        });
+        for (const [operationName, operation] of Object.entries(capability.operations)) {
+            commandContract(group.command(operationName)
+                .description(operation.description)
+                .option("--input <json>", "operation input as one JSON object", "{}")
+                .option("--compact", "write machine-readable JSON on one line")
+                .addHelpText("after", operationHelp(capabilityName, operationName))
+                .action(async function (options) {
+                const input = parseInput(options.input);
+                const result = await current().execute({
+                    capability: capabilityName,
+                    operation: operationName,
+                    input
+                });
+                console.log(JSON.stringify(result ?? null, null, options.compact ? undefined : 2));
+            }), { capability: operation });
+        }
+    }
+}
+function operationHelp(capability, operation) {
+    const definition = systemControlOperation(capability, operation);
+    if (!definition)
+        return "";
+    return `\nInput schema:\n${JSON.stringify(definition.input, null, 2)}\n\nExamples:\n${definition.examples.map(example => `  phresh ${capability} ${operation} --input '${JSON.stringify(example)}'`).join("\n")}\n`;
+}
+function parseInput(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error("--input must be valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("--input must be one JSON object");
+    return parsed;
+}

package/dist/describe-command.js

@@ -0,0 +1,60 @@
+import { systemControl, systemControlOperation } from "@phreshos/core";
+import { commandContract, readCommandContract } from "./command-contract.js";
+/** Add one machine-readable description entry point for the complete CLI tree. */
+export default function describeCommands(program) {
+    commandContract(program.command("describe")
+        .description("describe any Phresh capability as machine-readable data")
+        .argument("[path...]", "command path to describe")
+        .option("--compact", "write JSON on one line")
+        .action(function (path, options) {
+        const command = resolveCommand(program, path);
+        const description = describe(command, path);
+        console.log(JSON.stringify(description, null, options.compact ? undefined : 2));
+    }), { guidance: ["Omit the path to discover all top-level commands, then describe progressively deeper paths."] });
+}
+function resolveCommand(root, path) {
+    let command = root;
+    for (const name of path) {
+        const child = command.commands.find(candidate => candidate.name() === name);
+        if (!child)
+            throw new Error(`Unknown command path "${path.join(" ")}"`);
+        command = child;
+    }
+    return command;
+}
+function describe(command, path) {
+    const registered = readCommandContract(command);
+    const capability = registered?.capability ?? (path.length === 1 && Object.hasOwn(systemControl, path[0] ?? "")
+        ? systemControl[path[0]]
+        : null);
+    const operation = path.length === 2 ? systemControlOperation(path[0] ?? "", path[1] ?? "") : null;
+    return {
+        path,
+        name: command.name(),
+        description: command.description(),
+        arguments: command.registeredArguments.map(argumentDescription),
+        options: command.options.map(optionDescription),
+        commands: command.commands.map(child => ({ name: child.name(), description: child.description() })),
+        ...(registered?.guidance ? { guidance: registered.guidance } : {}),
+        ...(operation ? { capability: operation } : capability ? { capability } : {})
+    };
+}
+function argumentDescription(argument) {
+    return {
+        name: argument.name(),
+        description: argument.description,
+        required: argument.required,
+        variadic: argument.variadic,
+        ...(argument.defaultValue === undefined ? {} : { default: argument.defaultValue })
+    };
+}
+function optionDescription(option) {
+    return {
+        flags: option.flags,
+        description: option.description,
+        value: option.required ? "required" : option.optional ? "optional" : "none",
+        variadic: option.variadic,
+        ...(option.defaultValue === undefined ? {} : { default: option.defaultValue }),
+        ...(option.argChoices === undefined ? {} : { choices: option.argChoices })
+    };
+}

package/dist/gateway.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import { connect } from "node:net";
+import { join } from "node:path";
+import phreshosHome from "./home.js";
+/** Resolve the one owner-local gateway address for the selected System home. */
+export function gatewayPath(home = phreshosHome(), platform = process.platform) {
+    if (platform !== "win32")
+        return join(home, "gateway.sock");
+    const owner = home.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
+    const identity = createHash("sha256").update(owner).digest("hex").slice(0, 32);
+    return `\\\\.\\pipe\\phreshos-${identity}-gateway`;
+}
+/** Stream one Program lifecycle request over the shared gateway. */
+export function streamProgram(request, heard, path = gatewayPath(), signal) {
+    return new Promise(function (resolve, reject) {
+        const socket = connect(path);
+        let buffer = "";
+        let failure = null;
+        let cancelled = false;
+        const cancel = () => {
+            cancelled = true;
+            socket.destroy();
+        };
+        if (signal?.aborted)
+            cancel();
+        else
+            signal?.addEventListener("abort", cancel, { once: true });
+        socket.on("connect", () => socket.write(`${JSON.stringify({ target: "program", request })}\n`));
+        socket.on("data", function (chunk) {
+            buffer += String(chunk);
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines)
+                if (line.trim()) {
+                    const event = JSON.parse(line);
+                    if (event.event === "error")
+                        failure = new Error(String(event.message));
+                    else
+                        heard(event);
+                }
+        });
+        socket.on("error", () => {
+            if (!cancelled)
+                reject(new Error(`No System gateway is listening at ${path} — start PhreshOS first`));
+        });
+        socket.on("close", () => {
+            signal?.removeEventListener("abort", cancel);
+            if (cancelled)
+                reject(new Error("The attached launch was stopped"));
+            else if (failure)
+                reject(failure);
+            else
+                resolve();
+        });
+    });
+}
+/** Execute one short request over the shared gateway. */
+export function requestSystem(request, path = gatewayPath(), signal) {
+    return new Promise((resolve, reject) => {
+        const socket = connect(path);
+        let buffer = "";
+        let settled = false;
+        const finish = (work) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", cancel);
+            socket.destroy();
+            work();
+        };
+        const cancel = () => finish(() => reject(signal?.reason instanceof Error ? signal.reason : new Error("The request was cancelled")));
+        signal?.addEventListener("abort", cancel, { once: true });
+        socket.on("connect", () => socket.write(`${JSON.stringify({ target: "system", request })}\n`));
+        socket.on("data", function (chunk) {
+            buffer += String(chunk);
+            const boundary = buffer.indexOf("\n");
+            if (boundary < 0)
+                return;
+            let outcome;
+            try {
+                outcome = JSON.parse(buffer.slice(0, boundary));
+            }
+            catch {
+                return finish(() => reject(new Error("The System returned an invalid gateway response")));
+            }
+            if (outcome.success)
+                finish(() => resolve(outcome.result));
+            else
+                finish(() => reject(new Error(outcome.error)));
+        });
+        socket.on("error", () => finish(() => reject(new Error(`No System gateway is listening at ${path} — start PhreshOS first`))));
+        socket.on("close", () => finish(() => reject(new Error("The System closed the gateway request without an answer"))));
+        if (signal?.aborted)
+            cancel();
+    });
+}

package/dist/home.js

@@ -0,0 +1,16 @@
+import { homedir } from "node:os";
+import { existsSync, realpathSync } from "node:fs";
+import { isAbsolute, join, normalize } from "node:path";
+/** Resolve the absolute PhreshOS home selected for this CLI invocation. */
+export default function phreshosHome(environment = process.env, userHome = homedir()) {
+    const selected = environment.PHRESHOS_HOME;
+    if (selected === undefined)
+        return canonical(join(userHome, ".phreshos"));
+    if (!isAbsolute(selected))
+        throw new Error("PHRESHOS_HOME must be an absolute filesystem path");
+    return canonical(selected);
+}
+function canonical(path) {
+    const normalized = normalize(path);
+    return existsSync(normalized) ? realpathSync(normalized) : normalized;
+}

package/dist/install.js

@@ -10,7 +10,7 @@ import build from "./build-command.js";
  * A local project is built and derived from its authoring declaration. An
  * official name resolves a verified production package and turns its
  * canonical paths into the same concrete description. From that point on,
- * both sources cross the exact same intake and the System performs the exact
+ * both sources cross the exact same gateway and the System performs the exact
  * same authoritative installation.
  *
  * When the author config declares `buildCommand`, it runs here before the

package/dist/program-installation.js

@@ -1,4 +1,4 @@
-import speak from "./program-intake.js";
+import { streamProgram } from "./gateway.js";
 import writeProgramCommandOutput from "./program-command-output.js";
 /** Install one prepared Program and await every explicitly requested outcome. */
 export default async function installProgram(program, options = {}) {
@@ -6,7 +6,7 @@ export default async function installProgram(program, options = {}) {
     let replaced = false;
     let startupEnabled = false;
     let processValue;
-    await speak({
+    await streamProgram({
         word: "install",
         program,
         run: options.run === true,

package/dist/system/command.js

@@ -1,11 +1,26 @@
 import SystemLifecycle from "./lifecycle.js";
 import prompts, { ReportedFailure } from "../prompts.js";
 import { accent, caution, dim, negative, positive } from "../style.js";
+import runSystem from "./run.js";
+import { commandContract } from "../command-contract.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");
+    const system = commandContract(program.command("system")
+        .description("run, install, and manage the PhreshOS System")
+        .argument("[source]", "System project or prepared release to run directly")
+        .action(async function (source) {
+        if (!source)
+            return system.help();
+        await runSystem(source);
+    }), {
+        guidance: [
+            "A source argument runs that System directly; it is resolved independently from PHRESHOS_HOME.",
+            "Without a source argument, choose one native lifecycle operation.",
+            "Running-System Programs, Processes, Endpoints, and Windows are top-level capabilities, not System subcommands."
+        ]
+    });
     system.command("install")
         .description("install or update the System and start its service")
         .action(async function () {

package/dist/system/{readiness.js → gateway-readiness.js}

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

package/dist/system/lifecycle.js

@@ -1,12 +1,15 @@
 import SystemInstallation from "./installation.js";
 import { downloadSystemRelease, resolveSystemRelease } from "./release.js";
-import { intakeReady, waitForIntake } from "./readiness.js";
+import { gatewayReady, waitForGateway } from "./gateway-readiness.js";
 import systemPaths from "./paths.js";
 import systemService from "./service/index.js";
 import nodeExecutable from "./node.js";
 import installProgram from "../install.js";
+import phreshosHome from "../home.js";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 /** Coordinates acquisition, immutable files, and the native service as one transaction. */
 export default class SystemLifecycle {
     dependencies;
@@ -18,8 +21,8 @@ export default class SystemLifecycle {
             service,
             resolveRelease: dependencies?.resolveRelease ?? resolveSystemRelease,
             downloadRelease: dependencies?.downloadRelease ?? downloadSystemRelease,
-            ready: dependencies?.ready ?? intakeReady,
-            wait: dependencies?.wait ?? waitForIntake,
+            ready: dependencies?.ready ?? gatewayReady,
+            wait: dependencies?.wait ?? waitForGateway,
             provisionSetup: dependencies?.provisionSetup ?? provisionSetup
         };
     }
@@ -39,7 +42,7 @@ export default class SystemLifecycle {
             await service.register(definition(installation, executable));
             if ((await service.inspect()).automaticStartup)
                 await service.enable();
-            await service.start();
+            await this.launchService();
             await this.waitUntilReady();
             await activation.commit();
         }
@@ -49,7 +52,7 @@ export default class SystemLifecycle {
             return await this.restoredFailure(error, previous, previousService);
         }
         // The System transaction is complete before a Program crosses its
-        // live intake. A provisioning failure therefore leaves a healthy
+        // live gateway. A provisioning failure therefore leaves a healthy
         // System available for a retry instead of rolling it back around a
         // separate Program installation that may already have succeeded.
         try {
@@ -80,7 +83,7 @@ export default class SystemLifecycle {
     }
     async startExclusive() {
         await this.requireInstalledService();
-        await this.dependencies.service.start();
+        await this.launchService();
         await this.waitUntilReady();
         return await this.status();
     }
@@ -111,14 +114,14 @@ export default class SystemLifecycle {
     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);
+        const ready = state.running && await this.dependencies.ready(installation.paths.gateway);
         return {
             ...(installed ? { installed } : {}),
             desktop: "http://localhost:4300",
             ...state,
             ready,
             root: installation.paths.root,
-            intake: installation.paths.intake,
+            gateway: installation.paths.gateway,
             log: installation.paths.log
         };
     }
@@ -135,7 +138,7 @@ export default class SystemLifecycle {
     async waitUntilReady() {
         const { installation, service } = this.dependencies;
         try {
-            await this.dependencies.wait(installation.paths.intake, async () => (await service.inspect()).running);
+            await this.dependencies.wait(installation.paths.gateway, async () => (await service.inspect()).running);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -167,7 +170,7 @@ export default class SystemLifecycle {
         else
             await service.disable();
         if (state.running) {
-            await service.start();
+            await this.launchService();
             await this.waitUntilReady();
         }
     }
@@ -180,6 +183,22 @@ export default class SystemLifecycle {
         }
         throw error;
     }
+    async launchService() {
+        const { installation, service } = this.dependencies;
+        const { homeRequest, transientHome } = installation.paths;
+        await rm(homeRequest, { force: true });
+        if (transientHome) {
+            await mkdir(dirname(homeRequest), { recursive: true });
+            await writeFile(homeRequest, transientHome, { mode: 0o600 });
+        }
+        try {
+            await service.start();
+        }
+        catch (error) {
+            await rm(homeRequest, { force: true });
+            throw error;
+        }
+    }
 }
 async function provisionSetup() {
     await installProgram({ name: "setup", run: true, startup: true, announce: false });
@@ -188,6 +207,12 @@ function definition(installation, executable) {
     return {
         executable,
         entry: join(installation.paths.current, "server", "main.js"),
+        arguments: [
+            "--default-home",
+            phreshosHome({}, homedir()),
+            "--home-request",
+            installation.paths.homeRequest
+        ],
         directory: installation.paths.current,
         output: installation.paths.log
     };

package/dist/system/paths.js

@@ -1,9 +1,10 @@
-import intakeAddress from "../intake-address.js";
+import { gatewayPath } from "../gateway.js";
+import phreshosHome from "../home.js";
 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 storage = phreshosHome(variables, userHome);
     const root = platform === "darwin"
         ? join(userHome, "Library", "Application Support", "PhreshOS", "System")
         : platform === "linux"
@@ -16,7 +17,9 @@ export default function systemPaths(platform = process.platform, userHome = home
         releases: join(root, "releases"),
         current: join(root, "current"),
         storage,
-        intake: intakeAddress(storage, platform),
+        gateway: gatewayPath(storage, platform),
+        homeRequest: join(root, "next-home"),
+        ...(variables.PHRESHOS_HOME === undefined ? {} : { transientHome: storage }),
         log: join(storage, "service.log")
     };
 }

package/dist/system/run.js

@@ -0,0 +1,37 @@
+import phreshosHome from "../home.js";
+import { existsSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+/** Run one System source directly with an explicit absolute state home. */
+export default async function runSystem(source, environment = process.env) {
+    const directory = resolve(source);
+    if (!existsSync(directory) || !statSync(directory).isDirectory())
+        throw new Error(`The System source does not exist: ${directory}`);
+    const entry = join(directory, "server", "main.js");
+    const command = existsSync(entry)
+        ? { file: process.execPath, args: [entry] }
+        : await projectCommand(directory);
+    const child = spawn(command.file, command.args, {
+        cwd: directory,
+        env: { ...environment, PHRESHOS_HOME: phreshosHome(environment) },
+        stdio: "inherit"
+    });
+    const result = await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("exit", (code, signal) => resolve({ code, signal }));
+    });
+    if (result.signal)
+        throw new Error(`The System stopped on ${result.signal}`);
+    if (result.code !== 0)
+        throw new Error(`The System exited with code ${result.code ?? 1}`);
+}
+async function projectCommand(directory) {
+    const path = join(directory, "package.json");
+    if (!existsSync(path))
+        throw new Error(`The System source has neither server/main.js nor package.json: ${directory}`);
+    const manifest = JSON.parse(await readFile(path, "utf8"));
+    if (typeof manifest.scripts?.start !== "string")
+        throw new Error(`The System source has no start command: ${directory}`);
+    return { file: process.execPath, args: ["--run", "start"] };
+}

package/dist/system/service/background.js

@@ -43,7 +43,7 @@ export default class BackgroundSystemService {
         await mkdir(dirname(definition.output), { recursive: true });
         const output = await open(definition.output, "a", 0o600);
         try {
-            const child = spawn(definition.executable, [definition.entry], {
+            const child = spawn(definition.executable, [definition.entry, ...definition.arguments], {
                 cwd: definition.directory,
                 detached: true,
                 stdio: ["ignore", output.fd, output.fd]
@@ -135,5 +135,7 @@ function definition(value) {
     if (!value || typeof value !== "object")
         return false;
     const candidate = value;
-    return ["executable", "entry", "directory", "output"].every(name => typeof candidate[name] === "string" && candidate[name] !== "");
+    return ["executable", "entry", "directory", "output"].every(name => typeof candidate[name] === "string" && candidate[name] !== "")
+        && Array.isArray(candidate.arguments)
+        && candidate.arguments.every(value => typeof value === "string");
 }

package/dist/system/service/macos.js

@@ -95,6 +95,7 @@ function plist(label, definition) {
     <array>
         <string>${xml(definition.executable)}</string>
         <string>${xml(definition.entry)}</string>
+${definition.arguments.map(argument => `        <string>${xml(argument)}</string>`).join("\n")}
     </array>
     <key>WorkingDirectory</key>
     <string>${xml(definition.directory)}</string>

package/dist/system/service/systemd.js

@@ -80,7 +80,7 @@ Description=PhreshOS System
 
 [Service]
 Type=simple
-ExecStart=${quote(definition.executable)} ${quote(definition.entry)}
+ExecStart=${[definition.executable, definition.entry, ...definition.arguments].map(quote).join(" ")}
 WorkingDirectory=${setting(definition.directory)}
 Restart=on-failure
 RestartSec=2

package/dist/system/service/windows-runner.js

@@ -3,7 +3,7 @@ import { open, writeFile } from "node:fs/promises";
 const payload = decode(process.argv[2]);
 const output = await open(payload.definition.output, "a", 0o600);
 try {
-    const child = spawn(payload.definition.executable, [payload.definition.entry], {
+    const child = spawn(payload.definition.executable, [payload.definition.entry, ...payload.definition.arguments], {
         cwd: payload.definition.directory,
         stdio: ["ignore", output.fd, output.fd]
     });
@@ -41,5 +41,7 @@ function definition(value) {
     if (!value || typeof value !== "object")
         return false;
     const candidate = value;
-    return ["executable", "entry", "directory", "output"].every(name => typeof candidate[name] === "string" && candidate[name] !== "");
+    return ["executable", "entry", "directory", "output"].every(name => typeof candidate[name] === "string" && candidate[name] !== "")
+        && Array.isArray(candidate.arguments)
+        && candidate.arguments.every(value => typeof value === "string");
 }

package/dist/template/gitignore

@@ -9,6 +9,7 @@ dist
 # Made by `phresh pack` in the project root.
 /*.zip
 /*.zip.sha256
+/program.json
 
 # Editor and machine residue.
 .vscode

package/dist/template/package.json

@@ -1,7 +1,7 @@
 {
     "name": "phresh",
     "private": true,
-    "version": "0.1.13",
+    "version": "0.1.15",
     "description": "The official PhreshOS starter Program.",
     "type": "module",
     "scripts": {
@@ -14,15 +14,15 @@
         "starter"
     ],
     "dependencies": {
-        "@phreshos/client": "^0.1.13",
-        "@phreshos/core": "^0.1.9",
+        "@phreshos/client": "^0.1.18",
+        "@phreshos/core": "^0.1.14",
         "@phreshos/react": "^0.1.7",
-        "@phreshos/server": "^0.1.11",
+        "@phreshos/server": "^0.1.17",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.21",
+        "@phreshos/cli": "^0.1.23",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/dist/template/phresh.config.ts

@@ -4,8 +4,11 @@ export default defineConfig({
     identity: "phresh",
     name: "Phresh Program",
     description: "A minimal counter with direct Client and Server endpoints.",
-    version: "0.1.13",
+    version: "0.1.15",
     icon: "icon.png",
+    categories: ["Development"],
+    keywords: ["example", "counter", "client", "server"],
+    website: "https://github.com/PhreshOS/phresh-program",
     buildCommand: "vite-node scripts/build.ts",
     server: {
         location: "dist/server",

package/dist/template.json

@@ -1,6 +1,6 @@
 {
     "repository": "PhreshOS/phresh-program",
-    "version": "0.1.13",
-    "sha256": "c55ff8129295c9c90b7a78fef8689fef6e0d180c7a284fdb180127700b74fcb0",
+    "version": "0.1.15",
+    "sha256": "33e7b8119bc75d3bd8d7c3413749dfbd001bff3f6a0a6392d1498c9f38cf0683",
     "development": true
 }

package/dist/uninstall.js

@@ -1,17 +1,19 @@
 import { readConfig } from "./project.js";
 import { dim, heading } from "./style.js";
-import speak from "./program-intake.js";
+import { streamProgram } from "./gateway.js";
 import writeProgramCommandOutput from "./program-command-output.js";
-/** Uninstall the Program declared by the current project. */
-export default async function uninstall(everything = false, directory = process.cwd()) {
-    const config = await readConfig(directory);
-    await speak({ word: "uninstall", identity: config.identity, everything }, function (event) {
+/** Uninstall an installed Program by name or by the current project's identity. */
+export default async function uninstall(options = {}) {
+    const identity = options.name ?? (await readConfig(options.directory ?? process.cwd())).identity;
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(identity))
+        throw new Error(`The Program name "${identity}" is invalid`);
+    await streamProgram({ word: "uninstall", identity, everything: options.everything === true }, function (event) {
         if (event.event === "output")
             return writeProgramCommandOutput(event);
         if (event.event !== "uninstalled")
             return;
-        heading(config.name ?? config.identity, "uninstalled");
-        console.log(everything
+        heading(identity, "uninstalled");
+        console.log(options.everything
             ? `  ${dim("Its processes, installed files, stored data, and runtime record were removed.")}\n`
             : `  ${dim("Its installed files were removed. Processes, stored data, and runtime state were kept.")}\n`);
     });

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-  "version": "0.1.21",
+  "version": "0.1.23",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"
@@ -49,7 +49,7 @@
     "packageManager": "bun@1.3.14",
     "dependencies": {
         "@clack/prompts": "^1.7.0",
-    "@phreshos/core": "^0.1.13",
+    "@phreshos/core": "^0.1.18",
         "adm-zip": "^0.6.0",
         "commander": "^15.0.0",
         "picocolors": "^1.1.1"

package/dist/intake-address.js

@@ -1,14 +0,0 @@
-import { createHash } from "node:crypto";
-import { join } from "node:path";
-/** Address the same owner-local intake without turning it into a network port. */
-export default function intakeAddress(storage, platform = process.platform) {
-    if (platform !== "win32")
-        return join(storage, "intake.sock");
-    // Windows pipe names share one machine-wide namespace. The storage root
-    // separates users and isolated instances while case folding follows the
-    // filesystem they came from. Access remains the pipe creator's default
-    // duplex ACL; the name is identity, not a secret or an authorization.
-    const owner = storage.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
-    const identity = createHash("sha256").update(owner).digest("hex").slice(0, 32);
-    return `\\\\.\\pipe\\phreshos-${identity}-intake`;
-}

package/dist/program-intake.js

@@ -1,75 +0,0 @@
-import { connect } from "node:net";
-import { homedir } from "node:os";
-import { isAbsolute, join } from "node:path";
-import intakeAddress from "./intake-address.js";
-/**
- * The local Program intake, from the CLI's side.
- *
- * An owner-local IPC address rather than a port: a mode-0600 socket file
- * on POSIX and an owner-created duplex named pipe on Windows. Only the
- * account that owns this machine can complete the channel, and that account
- * is exactly who may run and install programs on it. Nothing is sent to
- * prove anything, because being able to connect is the proof.
- *
- * A message is a line. Closing our own side to mark the end of a
- * question would make lifetime ambiguous. A line delimiter keeps the
- * connection available for the stream of events that follows a launch.
- *
- * One question, then events until the system closes. Installation confirms
- * each requested outcome — laid out, startup enabled, running — and then
- * ends. Uninstalling says one thing and ends; an attached run says how it
- * began, whatever the Program says, and how it ended. None pretends to be a
- * remote method returning through an unrelated transport.
- */
-export function programIntakePath(environment = process.env, userHome = homedir()) {
-    const instanceHome = environment.PHRESHOS_HOME;
-    if (instanceHome === undefined)
-        return intakeAddress(join(userHome, ".phreshos"));
-    if (!isAbsolute(instanceHome))
-        throw new Error("PHRESHOS_HOME must be an absolute filesystem path");
-    return intakeAddress(instanceHome);
-}
-export const socketPath = programIntakePath();
-export default function speak(question, heard, path = socketPath, signal) {
-    return new Promise(function (settle, refuse) {
-        const socket = connect(path);
-        let said = "";
-        let failed = null;
-        let aborted = false;
-        const abort = () => {
-            aborted = true;
-            socket.destroy();
-        };
-        if (signal?.aborted)
-            abort();
-        else
-            signal?.addEventListener("abort", abort, { once: true });
-        socket.on("connect", () => socket.write(JSON.stringify(question) + "\n"));
-        socket.on("data", function (chunk) {
-            said += String(chunk);
-            const lines = said.split("\n");
-            said = lines.pop() ?? "";
-            for (const line of lines)
-                if (line.trim()) {
-                    const event = JSON.parse(line);
-                    if (event.event === "error")
-                        failed = new Error(String(event.message));
-                    else
-                        heard(event);
-                }
-        });
-        // The system is not running, or is running as somebody else. Said
-        // plainly, because "ENOENT" is not what went wrong from here.
-        socket.on("error", () => { if (!aborted)
-            refuse(new Error(`No system is listening at ${path} — start one, or check that it is yours`)); });
-        socket.on("close", () => {
-            signal?.removeEventListener("abort", abort);
-            if (aborted)
-                refuse(new Error("The attached launch was stopped"));
-            else if (failed)
-                refuse(failed);
-            else
-                settle();
-        });
-    });
-}

package/dist/template/metadata.json

@@ -1,11 +0,0 @@
-{
-    "schema": 1,
-    "identity": "phresh",
-    "version": "0.1.13",
-    "name": "Phresh Program",
-    "description": "A minimal Client and Server Program for exploring PhreshOS development.",
-    "icon": "icon.png",
-    "categories": ["Development"],
-    "keywords": ["example", "counter", "client", "server"],
-    "website": "https://github.com/PhreshOS/phresh-program"
-}