@phreshos/cli 0.1.45 → 0.1.46

package/README.md

@@ -31,8 +31,8 @@ phresh pack
 ```
 
 `create` produces the official starter Program. The remaining commands operate
-on the current Program project, derive its concrete definition, and delegate
-runtime operations to the connected System.
+on the current Program project through the Node Project contract and present
+its build, development, installation, and runtime lifecycles.
 
 ## System
 
@@ -89,9 +89,10 @@ for the command model.
 
 ## Repository boundary
 
-This repository owns terminal interaction, project commands, packaging, System
-acquisition, and host service integration. Node owns the external JavaScript
-interface, Core owns shared contracts, and the System owns authoritative state.
+This repository owns terminal interaction, command routing, System acquisition,
+and host service integration. Node owns the external JavaScript interface and
+Project workflows, Core owns shared contracts, and the System owns authoritative
+state.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow and
 [SECURITY.md](SECURITY.md) for private vulnerability reporting.

package/dist/cli.js

@@ -61,7 +61,7 @@ describe(program.command("init")
     .option("--server-development-entry-file <path>", "development Server worker entry")
     .option("--client", "include a Client endpoint")
     .option("--client-location <path>", "production Client directory")
-    .option("--client-development-url <url>", "development Client URL")
+    .option("--client-development-url <url>", "fixed or external development Client URL")
     .option("--client-development-start-command <command>", "development Client command")
     .option("--force", "replace an existing phresh.config.ts")
     .action(async function (options) {
@@ -74,7 +74,10 @@ describe(program.command("init")
         serverEntryFile: options.serverEntryFile,
         serverDevelopmentStartCommand: options.serverDevelopmentStartCommand,
         serverDevelopmentEntryFile: options.serverDevelopmentEntryFile,
-        client: options.client === true || options.clientLocation !== undefined,
+        client: options.client === true
+            || options.clientLocation !== undefined
+            || options.clientDevelopmentUrl !== undefined
+            || options.clientDevelopmentStartCommand !== undefined,
         clientLocation: options.clientLocation,
         clientDevelopmentUrl: options.clientDevelopmentUrl,
         clientDevelopmentStartCommand: options.clientDevelopmentStartCommand,

package/dist/control/shared.js

@@ -30,6 +30,7 @@ export function endpoint(process, name) {
 export async function programView(program) {
     return {
         identity: program.identity,
+        assetId: program.assetId,
         name: program.name,
         version: program.version,
         description: program.description,

package/dist/init.js

@@ -83,24 +83,28 @@ export default async function init(options = {}, directory = process.cwd(), core
         if (interactive && developmentUrl === undefined && developmentStartCommand === undefined) {
             const suggested = manifest.scripts?.dev && projectScript(directory, manifest.packageManager, "dev");
             if (await yes("A development server can provide live updates instead of built Client files.", "Use a Client development server?", Boolean(suggested))) {
-                developmentUrl = await ask("The desktop opens this exact HTTP or HTTPS address during phresh dev.", "What URL serves the development Client?", "http://localhost:5173/");
-                if (await yes("The CLI can own the development server and stop it when the session ends.", "Should phresh dev start the Client server?", Boolean(suggested))) {
+                if (await yes("The Project can own the development server and stop it when the session ends.", "Should phresh dev start the Client server?", Boolean(suggested))) {
                     developmentStartCommand = await ask("This command remains attached to the phresh dev session.", "What command starts the Client development server?", suggested || undefined);
                 }
+                else
+                    developmentUrl = await ask("The System routes the Program asset path to this HTTP or HTTPS address during phresh dev.", "What URL serves the external development Client?", "http://localhost:5173/");
             }
         }
-        if (developmentStartCommand !== undefined && developmentUrl === undefined)
-            throw new Error("--client-development-url is required with --client-development-start-command");
         if (developmentUrl !== undefined && developmentUrl.trim().length === 0)
             throw new Error("A client development URL must not be empty");
         if (developmentUrl !== undefined && !httpUrl(developmentUrl))
             throw new Error("A client development URL must use HTTP or HTTPS");
         if (developmentStartCommand !== undefined && developmentStartCommand.trim().length === 0)
             throw new Error("A client development command must not be empty");
-        client = {
-            location,
-            ...developmentUrl && { development: { url: developmentUrl, ...developmentStartCommand && { startCommand: developmentStartCommand } } }
-        };
+        let development;
+        if (developmentStartCommand !== undefined)
+            development = {
+                startCommand: developmentStartCommand,
+                ...developmentUrl !== undefined && { url: developmentUrl }
+            };
+        else if (developmentUrl !== undefined)
+            development = { url: developmentUrl };
+        client = { location, ...development && { development } };
     }
     const described = {
         identity: manifest.name,
@@ -124,8 +128,6 @@ export default async function init(options = {}, directory = process.cwd(), core
     if (config.client) {
         interaction.message();
         interaction.detail("base URL", "./", "required for production assets");
-        if (config.client.development)
-            interaction.detail("CORS", "enabled", "required on the development server");
     }
     interaction.finish(`${configFile} created`);
 }

package/dist/launch.js

@@ -1,6 +1,5 @@
 import { Project } from "@phreshos/node";
 import { relative } from "node:path";
-import { assertAvailable, commandFailure, DevelopmentClient, waitForDevelopmentClient } from "./development-client.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 = {}) {
@@ -19,14 +18,9 @@ export default async function launch(mode, directory = process.cwd(), options =
     blank();
     const system = await (await import("@phreshos/node")).System.connect();
     const controller = new AbortController();
-    const development = mode === "development" && definition.client && (definition.client.start ?? true)
-        ? project.config.client?.development
-        : undefined;
-    const command = development?.startCommand;
-    let client;
     let interrupted = false;
     let ended = null;
-    let program = null;
+    let attached = false;
     const stop = () => {
         if (interrupted)
             return;
@@ -36,18 +30,11 @@ export default async function launch(mode, directory = process.cwd(), options =
     for (const signal of ["SIGINT", "SIGTERM"])
         process.on(signal, stop);
     try {
-        if (command && development) {
-            await assertAvailable(development.url);
-            client = new DevelopmentClient(command, project.directory);
-        }
-        if (development) {
-            for await (const event of waitForDevelopmentClient(development, client, controller.signal))
-                presentDevelopment(event);
-        }
-        if (mode === "production")
-            await project.build();
-        program = await system.forceCreateProgram(definition);
-        ended = await consume(program.process.run({ options }, { signal: controller.signal }), client);
+        const lifecycle = mode === "development"
+            ? await project.dev(system, { options, signal: controller.signal })
+            : await project.start(system, { options, signal: controller.signal });
+        attached = true;
+        ended = await consume(lifecycle);
     }
     catch (error) {
         if (!interrupted)
@@ -55,16 +42,25 @@ export default async function launch(mode, directory = process.cwd(), options =
     }
     finally {
         controller.abort(new Error("The local Program run ended"));
-        const cleanup = await Promise.allSettled([
-            client?.stop(),
-            program ? forget(program) : undefined
-        ]);
+        let cleanupFailure;
+        try {
+            const program = attached ? await system.program.find(definition.identity) : null;
+            if (program)
+                await forget(program);
+        }
+        catch (error) {
+            cleanupFailure = error;
+        }
+        try {
+            await system.disconnect();
+        }
+        catch (error) {
+            cleanupFailure ??= error;
+        }
         for (const signal of ["SIGINT", "SIGTERM"])
             process.off(signal, stop);
-        await system.disconnect();
-        const failure = cleanup.find(result => result.status === "rejected");
-        if (failure?.status === "rejected")
-            throw failure.reason;
+        if (cleanupFailure)
+            throw cleanupFailure;
     }
     if (interrupted)
         process.exit(130);
@@ -75,34 +71,10 @@ export default async function launch(mode, directory = process.cwd(), options =
     blank();
     process.exit(ended.signal ? 128 : ended.code ?? 0);
 }
-async function consume(lifecycle, client) {
-    const iterator = lifecycle[Symbol.asyncIterator]();
-    let next = iterator.next();
-    let developmentExit = client?.exited();
-    let developmentOutput = client?.outputAvailable();
+async function consume(lifecycle) {
     let process = null;
     let ending = null;
-    while (true) {
-        for (const event of client?.drain() ?? [])
-            presentDevelopment(event);
-        const outcome = await Promise.race([
-            next.then(result => ({ source: "system", result })),
-            ...(developmentExit ? [developmentExit.then(result => ({ source: "client", result }))] : []),
-            ...(developmentOutput ? [developmentOutput.then(() => ({ source: "output" }))] : [])
-        ]);
-        if (outcome.source === "output") {
-            developmentOutput = client?.outputAvailable();
-            continue;
-        }
-        if (outcome.source === "client") {
-            developmentExit = undefined;
-            if (!client?.endingWasRequested())
-                throw commandFailure(outcome.result);
-            continue;
-        }
-        if (outcome.result.done)
-            break;
-        const event = outcome.result.value;
+    for await (const event of lifecycle) {
         if (event.event === "started") {
             process = event.process.identity;
             line("process", process);
@@ -111,16 +83,11 @@ async function consume(lifecycle, client) {
             write(event.stream, event.text);
         else
             ending = { code: event.exit.code, signal: event.exit.signal };
-        next = iterator.next();
     }
     if (!process || !ending)
         throw new Error("The System ended the Program run without a complete Process lifecycle");
     return { process, ...ending };
 }
-function presentDevelopment(event) {
-    if (event.event === "output")
-        write(event.stream === "err" ? "stderr" : "stdout", event.text);
-}
 function write(stream, text) {
     (stream === "stderr" ? process.stderr : process.stdout).write(text);
 }

package/dist/system/lifecycle.js

@@ -7,7 +7,7 @@ import nodeExecutable from "./node.js";
 import installProgram from "../install.js";
 import phreshosHome from "../home.js";
 import { existsSync } from "node:fs";
-import { mkdir, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, 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. */
@@ -115,9 +115,10 @@ export default class SystemLifecycle {
         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.gateway);
+        const desktop = await desktopOrigin(installation.paths.storage);
         return {
             ...(installed ? { installed } : {}),
-            desktop: "http://localhost:4300",
+            desktop,
             ...state,
             ready,
             root: installation.paths.root,
@@ -185,17 +186,20 @@ export default class SystemLifecycle {
     }
     async launchService() {
         const { installation, service } = this.dependencies;
-        const { homeRequest, transientHome } = installation.paths;
-        await rm(homeRequest, { force: true });
-        if (transientHome) {
+        const { homeRequest, portRequest, transientHome, transientPorts } = installation.paths;
+        await Promise.all([rm(homeRequest, { force: true }), rm(portRequest, { force: true })]);
+        if (transientHome || transientPorts !== undefined) {
             await mkdir(dirname(homeRequest), { recursive: true });
-            await writeFile(homeRequest, transientHome, { mode: 0o600 });
+            await Promise.all([
+                ...transientHome ? [writeFile(homeRequest, transientHome, { mode: 0o600 })] : [],
+                ...transientPorts === undefined ? [] : [writeFile(portRequest, transientPorts, { mode: 0o600 })]
+            ]);
         }
         try {
             await service.start();
         }
         catch (error) {
-            await rm(homeRequest, { force: true });
+            await Promise.all([rm(homeRequest, { force: true }), rm(portRequest, { force: true })]);
             throw error;
         }
     }
@@ -211,9 +215,22 @@ function definition(installation, executable) {
             "--default-home",
             phreshosHome({}, homedir()),
             "--home-request",
-            installation.paths.homeRequest
+            installation.paths.homeRequest,
+            "--port-request",
+            installation.paths.portRequest
         ],
         directory: installation.paths.current,
         output: installation.paths.log
     };
 }
+async function desktopOrigin(storage) {
+    try {
+        const value = (await readFile(join(storage, "desktop"), "utf8")).trim();
+        return /^http:\/\/localhost:\d+$/.test(value) ? value : "http://localhost:4300";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "http://localhost:4300";
+        throw error;
+    }
+}

package/dist/system/paths.js

@@ -19,7 +19,9 @@ export default function systemPaths(platform = process.platform, userHome = home
         storage,
         gateway: gatewayPath(storage, platform),
         homeRequest: join(root, "next-home"),
+        portRequest: join(root, "next-port"),
         ...(variables.PHRESHOS_HOME === undefined ? {} : { transientHome: storage }),
+        ...(variables.PHRESHOS_PORT === undefined ? {} : { transientPorts: variables.PHRESHOS_PORT }),
         log: join(storage, "service.log")
     };
 }

package/dist/template/package.json

@@ -22,7 +22,7 @@
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.45",
+        "@phreshos/cli": "^0.1.46",
         "@types/node": "^26.4.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.5",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.45",
+  "version": "0.1.46",
     "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.36",
-        "@phreshos/node": "^0.1.12",
+    "@phreshos/core": "^0.1.37",
+    "@phreshos/node": "^0.1.13",
         "adm-zip": "^0.6.0",
         "commander": "^15.0.0",
         "picocolors": "^1.1.1"

package/dist/development-client.js

@@ -1,197 +0,0 @@
-import { spawn } from "node:child_process";
-import { connect } from "node:net";
-import { delimiter, join } from "node:path";
-const readinessTimeout = 15_000;
-const pollingInterval = 200;
-const reportingInterval = 2_000;
-const sandboxedClientOrigin = "null";
-/** One Client development server presented and supervised by the CLI. */
-export class DevelopmentClient {
-    child;
-    output = [];
-    stopped = false;
-    result = null;
-    outputWaiter = null;
-    completion;
-    constructor(command, directory) {
-        this.child = spawn(command, {
-            cwd: directory,
-            env: commandEnvironment(directory),
-            shell: true,
-            stdio: ["ignore", "pipe", "pipe"],
-            detached: true
-        });
-        this.child.stdout?.on("data", chunk => this.push(outputEvent("out", chunk)));
-        this.child.stderr?.on("data", chunk => this.push(outputEvent("err", chunk)));
-        this.completion = new Promise(resolve => {
-            const finish = (exit) => {
-                if (this.result)
-                    return;
-                this.result = exit;
-                this.outputWaiter?.();
-                this.outputWaiter = null;
-                resolve(exit);
-            };
-            this.child.once("error", error => finish({ code: null, signal: null, error }));
-            this.child.once("exit", (code, signal) => finish({ code, signal, error: null }));
-        });
-    }
-    drain() { return this.output.splice(0); }
-    exited() { return this.completion; }
-    exitResult() { return this.result; }
-    outputAvailable() {
-        if (this.output.length || this.result)
-            return Promise.resolve();
-        return new Promise(resolve => { this.outputWaiter = resolve; });
-    }
-    async stop() {
-        if (this.stopped)
-            return;
-        this.stopped = true;
-        if (!running(this.child))
-            return;
-        terminate(this.child, "SIGTERM");
-        await waitUntilStopped(this.child, 1_000);
-        if (running(this.child))
-            terminate(this.child, "SIGKILL");
-        await waitUntilStopped(this.child, 1_000);
-    }
-    endingWasRequested() { return this.stopped; }
-    push(event) {
-        this.output.push(event);
-        this.outputWaiter?.();
-        this.outputWaiter = null;
-    }
-}
-/** Refuse to claim a URL already served by an unrelated process. */
-export async function assertAvailable(url) {
-    if (!await occupied(url))
-        return;
-    throw new Error(`Client development URL is already in use: ${url}`);
-}
-/** Wait until a sandboxed Program iframe can load the development Client. */
-export async function* waitForDevelopmentClient(config, client, signal) {
-    const began = Date.now();
-    let nextReport = began + reportingInterval;
-    while (Date.now() - began < readinessTimeout) {
-        throwIfAborted(signal);
-        for (const event of client?.drain() ?? [])
-            yield event;
-        const exit = client?.exitResult();
-        if (exit && !client?.endingWasRequested())
-            throw commandFailure(exit);
-        const availability = await inspect(config.url, readinessTimeout - (Date.now() - began));
-        if (availability === "ready")
-            return;
-        if (availability === "cors-blocked") {
-            throw new Error([
-                `Client development URL responded, but does not allow the sandboxed Client origin: ${config.url}`,
-                "Enable CORS so the response includes Access-Control-Allow-Origin: *."
-            ].join("\n"));
-        }
-        const now = Date.now();
-        if (now >= nextReport) {
-            yield { event: "waiting", subject: "client", url: config.url };
-            while (nextReport <= now)
-                nextReport += reportingInterval;
-        }
-        await pause(Math.min(pollingInterval, readinessTimeout - (now - began)), signal);
-    }
-    throw new Error(`Client development URL did not respond within 15 seconds: ${config.url}`);
-}
-export function commandFailure(exit) {
-    if (exit.error)
-        return new Error(`Client development command failed: ${exit.error.message}`);
-    if (exit.signal)
-        return new Error(`Client development command ended on ${exit.signal}`);
-    return new Error(`Client development command exited with ${exit.code ?? 0}`);
-}
-function outputEvent(stream, chunk) {
-    return { event: "output", stream, text: String(chunk) };
-}
-function commandEnvironment(directory) {
-    const key = Object.keys(process.env).find(name => name.toLowerCase() === "path") ?? "PATH";
-    const inherited = process.env[key];
-    return { ...process.env, [key]: [join(directory, "node_modules", ".bin"), inherited].filter(Boolean).join(delimiter) };
-}
-async function occupied(url) {
-    const location = new URL(url);
-    const port = Number(location.port || (location.protocol === "https:" ? 443 : 80));
-    return await new Promise(resolve => {
-        const socket = connect({ host: location.hostname, port });
-        let done = false;
-        const finish = (value) => {
-            if (done)
-                return;
-            done = true;
-            socket.destroy();
-            resolve(value);
-        };
-        socket.setTimeout(500);
-        socket.once("connect", () => finish(true));
-        socket.once("error", () => finish(false));
-        socket.once("timeout", () => finish(false));
-    });
-}
-async function inspect(url, remaining) {
-    try {
-        const response = await fetch(url, {
-            headers: { origin: sandboxedClientOrigin },
-            signal: AbortSignal.timeout(Math.max(1, Math.min(500, remaining)))
-        });
-        const allowedOrigin = response.headers.get("access-control-allow-origin")?.trim();
-        await response.body?.cancel();
-        return allowedOrigin === "*" || allowedOrigin === sandboxedClientOrigin ? "ready" : "cors-blocked";
-    }
-    catch {
-        return "unavailable";
-    }
-}
-function terminate(child, signal) {
-    if (!child.pid)
-        return;
-    try {
-        process.kill(-child.pid, signal);
-    }
-    catch {
-        child.kill(signal);
-    }
-}
-function running(child) {
-    if (!child.pid)
-        return false;
-    try {
-        process.kill(-child.pid, 0);
-        return true;
-    }
-    catch {
-        return child.exitCode === null && child.signalCode === null;
-    }
-}
-async function waitUntilStopped(child, milliseconds) {
-    const deadline = Date.now() + milliseconds;
-    while (running(child) && Date.now() < deadline)
-        await new Promise(resolve => setTimeout(resolve, 20));
-}
-function pause(milliseconds, signal) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(finish, Math.max(0, milliseconds));
-        const cancel = () => {
-            cleanup();
-            reject(signal?.reason instanceof Error ? signal.reason : new Error("The operation was cancelled"));
-        };
-        const cleanup = () => {
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", cancel);
-        };
-        function finish() { cleanup(); resolve(); }
-        if (signal?.aborted)
-            cancel();
-        else
-            signal?.addEventListener("abort", cancel, { once: true });
-    });
-}
-function throwIfAborted(signal) {
-    if (signal?.aborted)
-        throw signal.reason instanceof Error ? signal.reason : new Error("The operation was cancelled");
-}