@phreshos/cli 0.1.40 → 0.1.42

package/dist/cli.js

@@ -12,6 +12,7 @@ import systemCommands from "./system/command.js";
 import controlCommands from "./control/command.js";
 import describeCommands from "./describe-command.js";
 import { commandContract } from "./command-contract.js";
+import { blank, failure } from "./style.js";
 const metadata = createRequire(import.meta.url)("../package.json");
 const { version } = metadata;
 const coreRange = metadata.dependencies["@phreshos/core"];
@@ -96,13 +97,12 @@ describe(program.command("install")
     .description("install a local or official Program")
     .argument("[name]", "name of an official Program")
     .option("--run", "run the installed Program now")
-    .option("--startup", "run the Program when the System starts")
     .action(async function (name, options) {
-    await install({ name, run: options.run === true, startup: options.startup === true });
+    await install({ name, run: options.run === true });
 }), [
     "Without a name, builds and installs the Program declared by this project.",
     "A name installs its verified official production release. --run launches",
-    "it now; --startup persists the same default launch for future starts."
+    "the installed Program now."
 ]);
 describe(program.command("uninstall")
     .description("uninstall a local or installed Program")
@@ -129,7 +129,7 @@ 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("");
+blank();
 if (process.argv.length === 2)
     program.help();
 try {
@@ -141,7 +141,7 @@ catch (error) {
     else if (error instanceof ReportedFailure)
         process.exitCode = 1;
     else {
-        console.error(`\n  phresh: ${error instanceof Error ? error.message : String(error)}\n`);
+        failure(error instanceof Error ? error.message : String(error));
         process.exitCode = 1;
     }
 }

package/dist/control/endpoint.js

@@ -1,7 +1,7 @@
-import {} from "commander";
+import { Option } from "commander";
 import { commandContract } from "../command-contract.js";
-import { clientOverrideOptions, endpointOptions, outputOptions } from "./options.js";
-import { bounded, clientLaunch, connected, endpoint, endpointView, integer, output, payload, requireProcess, wait } from "./shared.js";
+import { clientOverrideOptions, endpointOptions, outputOptions, serverOverrideOptions } from "./options.js";
+import { bounded, clientLaunch, connected, endpoint, endpointView, integer, output, payload, requireProcess, serverLaunch, wait } from "./shared.js";
 export default function endpointCommands(root, connect) {
     const endpoints = commandContract(root.command("endpoint")
         .description("inspect, control, and communicate with Process Endpoints"));
@@ -10,16 +10,19 @@ export default function endpointCommands(root, connect) {
         .action(async (options) => withEndpoint(connect, options, async (process, name) => {
         output(await endpointView(process, name), options.compact);
     }));
-    outputOptions(clientOverrideOptions(endpointOptions(endpoints.command("start")
-        .description("start a fresh Endpoint incarnation"))))
+    outputOptions(serverOverrideOptions(clientOverrideOptions(endpointOptions(endpoints.command("start")
+        .description("start a fresh Endpoint incarnation")))))
         .action(async (options) => withEndpoint(connect, options, async (process, name) => {
-        const overrides = clientLaunch(options);
-        if (name === "server" && overrides !== undefined)
+        const client = clientLaunch(options);
+        const server = serverLaunch(options);
+        if (name === "server" && client !== undefined)
             throw new Error("Client overrides require --endpoint client");
+        if (name === "client" && server !== undefined)
+            throw new Error("Server overrides require --endpoint server");
         if (name === "client")
-            await process.client.start(typeof overrides === "object" ? overrides : undefined);
+            await process.client.start(typeof client === "object" ? client : undefined);
         else
-            await process.server.start();
+            await process.server.start(typeof server === "object" ? server : undefined);
         output(await endpointView(process, name), options.compact);
     }));
     outputOptions(endpointOptions(endpoints.command("stop")
@@ -38,6 +41,20 @@ export default function endpointCommands(root, connect) {
         await process.server.waitReady(timeout(options.timeout));
         output(await endpointView(process, "server"), options.compact);
     }));
+    outputOptions(endpointOptions(endpoints.command("waitLifecycle")
+        .alias("wait-lifecycle")
+        .description("wait for one lifecycle transition of an exact Endpoint")
+        .addOption(new Option("--event <event>", "Endpoint lifecycle event")
+        .choices(["start", "stop"])
+        .makeOptionMandatory())
+        .option("--timeout <milliseconds>", "maximum wait in milliseconds", integer)))
+        .action(async (options) => withEndpoint(connect, options, async (process, name) => {
+        await wait(endpoint(process, name).lifecycle, options.event, timeout(options.timeout));
+        output({
+            scope: `endpoint:${process.identity}:${name}:lifecycle`,
+            event: options.event
+        }, options.compact);
+    }));
     outputOptions(endpointOptions(endpoints.command("ask")
         .description("ask a Server event and return its answer")
         .requiredOption("--event <event>", "event name")

package/dist/control/options.js

@@ -19,6 +19,8 @@ export function clientOptions(command) {
 }
 export function clientOverrideOptions(command) {
     return command
+        .option("--client-service", "address this Client incarnation through system.service()")
+        .option("--no-client-service", "do not address this Client incarnation through system.service()")
         .option("--client-title <title>", "initial Window title")
         .option("--client-width <value>", "initial Window width")
         .option("--client-height <value>", "initial Window height")
@@ -28,8 +30,13 @@ export function clientOverrideOptions(command) {
         .option("--client-location <location>", "initial page beneath the Client location")
         .option("--client-minimized", "open the Window minimized");
 }
+export function serverOverrideOptions(command) {
+    return command
+        .option("--server-service", "address this Server incarnation through system.service()")
+        .option("--no-server-service", "do not address this Server incarnation through system.service()");
+}
 export function launchOptions(command) {
-    return clientOptions(command)
+    return serverOverrideOptions(clientOptions(command))
         .option("--name <name>", "stable Program-local Process name")
         .option("--server", "start the Server Endpoint")
         .option("--no-server", "do not start the Server Endpoint")

package/dist/control/process.js

@@ -49,7 +49,7 @@ export default function processCommands(root, connect) {
     outputOptions(process.command("wait")
         .description("wait for one Process lifecycle event")
         .addOption(new Option("--event <event>", "Process lifecycle event")
-        .choices(["endpointStart", "endpointStop", "create", "exit"])
+        .choices(["create", "exit"])
         .makeOptionMandatory())
         .option("--process <identity>", "scope the event to one Process")
         .option("--program <identity>", "scope the event to one Program")
@@ -75,14 +75,6 @@ export default function processCommands(root, connect) {
 async function eventView(event, message, scoped) {
     if (event === "create")
         return processView(message);
-    if (event === "endpointStart" || event === "endpointStop") {
-        const endpoint = message;
-        const process = await endpoint.process();
-        return {
-            process: process.identity,
-            endpoint: endpoint === process.server ? "server" : "client"
-        };
-    }
     const exit = message;
     const process = exit.process ?? scoped;
     return {

package/dist/control/program.js

@@ -48,15 +48,19 @@ export default function programCommands(root, connect) {
         output({
             scope: options.program ? `program:${options.program}` : "program",
             event: options.event,
-            payload: await eventView(options.event, message)
+            payload: await eventView(options.event, message, options.program ? target : undefined)
         }, options.compact);
     }));
 }
-async function eventView(event, message) {
+async function eventView(event, message, scoped) {
     if (event === "uninstall") {
+        if (scoped)
+            return { program: await programView(scoped), everything: message === true };
         const value = message;
-        return { program: await programView(value.program), everythingRemoved: value.everythingRemoved };
+        return { program: await programView(value.program), everything: value.everything };
     }
+    if (scoped)
+        return programView(scoped);
     return programView(message);
 }
 function timeout(value) {

package/dist/control/shared.js

@@ -1,4 +1,5 @@
 import { System } from "@phreshos/node";
+import { blank } from "../style.js";
 export const connectSystem = () => System.connect();
 export async function connected(connect, action) {
     const system = await connect();
@@ -39,14 +40,19 @@ export async function programView(program) {
     };
 }
 export async function processView(process) {
-    const [server, client] = await Promise.all([process.server.exists(), process.client.exists()]);
+    const [server, client, serverService, clientService] = await Promise.all([
+        process.server.exists(),
+        process.client.exists(),
+        process.server.isService(),
+        process.client.isService()
+    ]);
     return {
         identity: process.identity,
         name: process.name,
         program: process.program().identity,
         startedAt: process.startedAt.toISOString(),
-        server: { declared: process.program().server !== null, running: server },
-        client: { declared: process.program().client !== null, running: client }
+        server: { declared: process.program().server !== null, running: server, service: serverService },
+        client: { declared: process.program().client !== null, running: client, service: clientService }
     };
 }
 export async function endpointView(process, name) {
@@ -56,7 +62,8 @@ export async function endpointView(process, name) {
         program: program.identity,
         endpoint: name,
         declared: name === "server" ? program.server !== null : program.client !== null,
-        running: await endpoint(process, name).exists()
+        running: await endpoint(process, name).exists(),
+        service: await endpoint(process, name).isService()
     };
 }
 export async function windowView(process) {
@@ -74,6 +81,7 @@ export async function windowView(process) {
 }
 export function output(value, compact) {
     console.log(JSON.stringify(value ?? null, null, compact ? undefined : 2));
+    blank();
 }
 export function payload(value) {
     if (value === undefined)
@@ -118,12 +126,13 @@ export function page(values, search, offset = 0, limit = 30, text) {
 }
 export function launch(options, named = false) {
     const client = clientLaunch(options);
+    const server = serverLaunch(options);
     const values = entries(options.option);
     const result = {};
     if (options.name !== undefined)
         result.name = options.name;
-    if (options.server !== undefined)
-        result.server = options.server;
+    if (server !== undefined)
+        result.server = server;
     if (client !== undefined)
         result.client = client;
     if (Object.keys(values).length)
@@ -133,6 +142,7 @@ export function launch(options, named = false) {
     return result;
 }
 export function clientLaunch(options) {
+    const service = options.clientService;
     const configured = options.clientTitle !== undefined
         || options.clientWidth !== undefined
         || options.clientHeight !== undefined
@@ -140,7 +150,8 @@ export function clientLaunch(options) {
         || options.clientY !== undefined
         || options.clientLayer !== undefined
         || options.clientLocation !== undefined
-        || options.clientMinimized === true;
+        || options.clientMinimized === true
+        || service !== undefined;
     if (!configured)
         return options.client;
     if (options.client === false)
@@ -152,6 +163,7 @@ export function clientLaunch(options) {
         throw new Error("--client-x and --client-y must be supplied together");
     }
     return {
+        ...(service === undefined ? {} : { service }),
         ...(options.clientTitle === undefined ? {} : { title: options.clientTitle }),
         ...(options.clientWidth === undefined ? {} : { size: size(options.clientWidth, options.clientHeight) }),
         ...(options.clientX === undefined ? {} : { position: position(options.clientX, options.clientY) }),
@@ -160,6 +172,14 @@ export function clientLaunch(options) {
         ...(options.clientMinimized === true ? { minimize: true } : {})
     };
 }
+export function serverLaunch(options) {
+    const service = options.serverService;
+    if (service === undefined)
+        return options.server;
+    if (options.server === false)
+        throw new Error("Server overrides cannot be combined with --no-server");
+    return { service };
+}
 export function collect(value, previous = []) {
     return [...previous, value];
 }

package/dist/create.js

@@ -1,6 +1,6 @@
 import { installProjectDependencies, projectPackageManager, projectScript } from "./project-dependency.js";
 import prompts from "./prompts.js";
-import { accent, bold } from "./style.js";
+import { accent, blank, bold } from "./style.js";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, relative, resolve } from "node:path";
 /** Creates a complete Program from the bundled Phresh Program snapshot. */
@@ -60,7 +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("");
+    blank();
 }
 function template() {
     const candidates = [

package/dist/describe-command.js

@@ -1,4 +1,5 @@
 import { commandContract, readCommandContract } from "./command-contract.js";
+import { blank } from "./style.js";
 /** Add one machine-readable description entry point for the complete CLI tree. */
 export default function describeCommands(program) {
     commandContract(program.command("describe")
@@ -9,6 +10,7 @@ export default function describeCommands(program) {
         const command = resolveCommand(program, path);
         const description = describe(command, path);
         console.log(JSON.stringify(description, null, options.compact ? undefined : 2));
+        blank();
     }), { guidance: ["Omit the path to discover all top-level commands, then describe progressively deeper paths."] });
 }
 function resolveCommand(root, path) {

package/dist/install.js

@@ -1,5 +1,5 @@
 import { Project } from "@phreshos/node";
-import { dim, heading, line } from "./style.js";
+import { blank, dim, heading, line } from "./style.js";
 import installProgram, {} from "./program-installation.js";
 import { prepareOfficialProgram } from "./program-release.js";
 /**
@@ -15,10 +15,10 @@ 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.
  *
- * Installation remains distinct from execution unless `run` or `startup`
- * is explicitly requested. A run created here 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.
+ * Installation remains distinct from execution unless `run` is explicitly
+ * requested. A run created here 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.
  */
 export default async function install(options = {}) {
     const directory = options.directory ?? process.cwd();
@@ -32,11 +32,11 @@ 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")}\n`);
-            if (result.startupEnabled)
-                line("startup", "enabled");
+                console.log(`  ${dim("its storage was kept, and its previous processes were ended")}`);
             if (result.process)
                 line("process", result.process);
+            if (result.replaced || result.process)
+                blank();
         }
         return result;
     }

package/dist/launch.js

@@ -1,7 +1,7 @@
 import { Project } from "@phreshos/node";
 import { relative } from "node:path";
 import { assertAvailable, commandFailure, DevelopmentClient, waitForDevelopmentClient } from "./development-client.js";
-import { dim, heading, line } from "./style.js";
+import { blank, dim, heading, line } from "./style.js";
 /** Run the current project through one connected System. */
 export default async function launch(mode, directory = process.cwd(), options = {}) {
     const project = await Project.open(directory);
@@ -16,7 +16,7 @@ export default async function launch(mode, directory = process.cwd(), options =
     line("storage", place(project.directory, String(definition.storage)));
     if (Object.keys(options).length)
         line("options", Object.entries(options).map(([name, value]) => `${name}=${value}`).join("  "));
-    console.log("");
+    blank();
     const system = await (await import("@phreshos/node")).System.connect();
     const controller = new AbortController();
     const development = mode === "development" && definition.client && (definition.client.start ?? true)
@@ -70,7 +70,9 @@ export default async function launch(mode, directory = process.cwd(), options =
         process.exit(130);
     if (!ended)
         throw new Error("The System closed before the Program ended");
-    console.log(`\n  ${dim(ended.signal ? `ended on ${ended.signal}` : `ended with ${ended.code ?? 0}`)}\n`);
+    blank();
+    console.log(`  ${dim(ended.signal ? `ended on ${ended.signal}` : `ended with ${ended.code ?? 0}`)}`);
+    blank();
     process.exit(ended.signal ? 128 : ended.code ?? 0);
 }
 async function consume(lifecycle, client) {

package/dist/pack.js

@@ -1,11 +1,14 @@
 import { Project } from "@phreshos/node";
-import { line } from "./style.js";
+import { blank, line } from "./style.js";
 /** Package the current Project and present only its command-facing progress. */
 export default async function pack(directory = process.cwd()) {
     const project = await Project.open(directory);
     if (project.config.buildCommand)
         line("build", project.config.buildCommand);
     const packed = await project.pack();
-    console.log(`\nPacked ${packed.archive}`);
+    if (project.config.buildCommand)
+        blank();
+    console.log(`Packed ${packed.archive}`);
+    blank();
     return packed.archive;
 }

package/dist/program-installation.js

@@ -7,7 +7,6 @@ export default async function installProgram(program, options = {}) {
     const current = await system.program.find(identity);
     const replaced = await current?.installed() ?? false;
     let installed = null;
-    let startupEnabled = false;
     let process = null;
     let installationFinished = false;
     try {
@@ -20,10 +19,6 @@ export default async function installProgram(program, options = {}) {
         for await (const chunk of installed.install())
             writeProgramCommandOutput(chunk);
         installationFinished = true;
-        if (options.startup) {
-            await installed.startup.enable();
-            startupEnabled = true;
-        }
         if (options.run)
             process = (await installed.process.create()).identity;
     }
@@ -41,14 +36,11 @@ export default async function installProgram(program, options = {}) {
     }
     if (!installed)
         throw new Error("The System ended Program installation without confirming it");
-    if (options.startup && !startupEnabled)
-        throw new Error("The System installed the Program without confirming startup");
     if (options.run && !process)
         throw new Error("The System installed the Program without confirming that it is running");
     return {
         program: { identity: installed.identity, name: installed.name, version: installed.version },
         replaced,
-        startupEnabled,
         process
     };
 }

package/dist/project-dependency.js

@@ -1,4 +1,4 @@
-import { line } from "./style.js";
+import { blank, line } from "./style.js";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -33,7 +33,7 @@ export default async function ensureProjectDependency(name, range, directory = p
     const manager = projectPackageManager(directory, manifest.packageManager);
     line("dependency", name, `${manager.name}, ${range}`);
     await run(manager.name, [...manager.addArgs(section), `${name}@${range}`], directory);
-    console.log("");
+    blank();
 }
 function run(command, args, directory, output = "inherit") {
     return new Promise(function (settle, refuse) {

package/dist/prompts.js

@@ -1,6 +1,6 @@
 import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
 import colors from "picocolors";
-import { caution, column, ending, line, section } from "./style.js";
+import { blank, caution, column, ending, line, section } from "./style.js";
 /** Signals an ordinary interactive cancellation rather than an operation failure. */
 export class PromptCancelled extends Error {
 }
@@ -36,8 +36,10 @@ export default function prompts() {
     function message(value = "") {
         if (interactive)
             log.message(value, { spacing: 0 });
+        else if (value)
+            console.log(`  ${value}`);
         else
-            console.log(value ? `  ${value}` : "");
+            blank();
     }
     function warning(value) {
         if (interactive)

package/dist/style.js

@@ -6,6 +6,10 @@ export const accent = colors.cyan;
 export const positive = colors.green;
 export const caution = colors.yellow;
 export const negative = colors.red;
+/** Writes one intentional blank line between terminal report blocks. */
+export function blank() {
+    console.log("");
+}
 // 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.
 //
@@ -20,12 +24,17 @@ export function column(label) {
 }
 export function heading(title, note) {
     section(title, note);
-    console.log("");
+    blank();
 }
 export function section(title, note) {
     console.log(`  ${bold(title)}${note ? `  ${dim("·")}  ${dim(note)}` : ""}`);
 }
 export function ending(message) {
     console.log(`  ${bold(message)}`);
-    console.log("");
+    blank();
+}
+/** Writes one consistently indented command failure followed by closing space. */
+export function failure(message) {
+    console.error(`  phresh: ${message}`);
+    console.error("");
 }

package/dist/system/lifecycle.js

@@ -201,7 +201,7 @@ export default class SystemLifecycle {
     }
 }
 async function provisionSetup() {
-    await installProgram({ name: "setup", run: true, startup: true, announce: false });
+    await installProgram({ name: "setup", run: true, announce: false });
 }
 function definition(installation, executable) {
     return {

package/dist/template/package.json

@@ -1,7 +1,7 @@
 {
     "name": "phresh",
     "private": true,
-    "version": "0.1.23",
+    "version": "0.1.24",
     "description": "The official PhreshOS starter Program.",
     "type": "module",
     "scripts": {
@@ -14,15 +14,15 @@
         "starter"
     ],
     "dependencies": {
-        "@phreshos/client": "^0.1.26",
-        "@phreshos/core": "^0.1.26",
-        "@phreshos/react": "^0.1.14",
-        "@phreshos/server": "^0.1.27",
+        "@phreshos/client": "^0.1.27",
+        "@phreshos/core": "^0.1.28",
+        "@phreshos/react": "^0.1.15",
+        "@phreshos/server": "^0.1.28",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.40",
+        "@phreshos/cli": "^0.1.42",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

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.23",
+    version: "0.1.24",
     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.23",
-    "sha256": "055a84726198072f481b14bd2aabd0f155982238914aded7808008c4197c123f",
+    "version": "0.1.24",
+    "sha256": "eefb7d148a8d78669a2cd7572c095bc34965e8a7d787c1e1c7945b7fa8224be6",
     "development": true
 }

package/dist/uninstall.js

@@ -1,5 +1,5 @@
 import { readConfig } from "./project.js";
-import { dim, heading } from "./style.js";
+import { blank, dim, heading } from "./style.js";
 import writeProgramCommandOutput from "./program-command-output.js";
 /** Uninstall an installed Program by name or by the current project's identity. */
 export default async function uninstall(options = {}) {
@@ -15,8 +15,9 @@ export default async function uninstall(options = {}) {
             writeProgramCommandOutput(chunk);
         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`);
+            ? `  ${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();
     }
     finally {
         await system.disconnect();

package/package.json

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