@phreshos/cli 0.1.34 → 0.1.36

package/dist/development-client.js

@@ -0,0 +1,197 @@
+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");
+}

package/dist/install.js

@@ -7,7 +7,7 @@ import { prepareOfficialProgram } from "./program-release.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,
+ * canonical paths into the same concrete definition. From that point on,
  * both sources cross the exact same gateway and the System performs the exact
  * same authoritative installation.
  *

package/dist/launch.js

@@ -1,25 +1,32 @@
 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";
 /** Run the current project through one connected System. */
 export default async function launch(mode, directory = process.cwd(), options = {}) {
     const project = await Project.open(directory);
-    const program = project.description(mode);
-    heading(`${program.name ?? program.identity}${program.version ? ` ${program.version}` : ""}`, mode);
+    const definition = mode === "development" ? project.developmentDefinition() : project.productionDefinition();
+    heading(`${definition.name ?? definition.identity}${definition.version ? ` ${definition.version}` : ""}`, mode);
     if (mode === "production" && project.config.buildCommand)
         line("build", project.config.buildCommand);
-    if (program.server)
-        line(program.server.startCommand ? "server" : "server worker", String(program.server.startCommand ?? program.server.entryFile), place(project.directory, program.server.location));
-    if (program.client)
-        line("client", project.config.client?.development?.startCommand ?? place(project.directory, program.client.location));
-    line("storage", place(project.directory, String(program.storage)));
+    if (definition.server)
+        line(definition.server.startCommand ? "server" : "server worker", String(definition.server.startCommand ?? definition.server.entryFile), place(project.directory, definition.server.location));
+    if (definition.client)
+        line("client", project.config.client?.development?.startCommand ?? place(project.directory, definition.client.location));
+    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("");
     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;
     const stop = () => {
         if (interrupted)
             return;
@@ -29,20 +36,35 @@ export default async function launch(mode, directory = process.cwd(), options =
     for (const signal of ["SIGINT", "SIGTERM"])
         process.on(signal, stop);
     try {
-        const result = mode === "development"
-            ? await project.dev(system, { options, signal: controller.signal })
-            : await project.start(system, { options, signal: controller.signal });
-        console.log(`\n  ${dim("ran as")} ${result.process.identity}`);
-        ended = { code: result.exit.code, signal: result.exit.signal };
+        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);
     }
     catch (error) {
         if (!interrupted)
             throw error;
     }
     finally {
+        controller.abort(new Error("The local Program run ended"));
+        const cleanup = await Promise.allSettled([
+            client?.stop(),
+            program ? forget(program) : undefined
+        ]);
         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 (interrupted)
         process.exit(130);
@@ -51,6 +73,65 @@ export default async function launch(mode, directory = process.cwd(), options =
     console.log(`\n  ${dim(ended.signal ? `ended on ${ended.signal}` : `ended with ${ended.code ?? 0}`)}\n`);
     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();
+    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;
+        if (event.event === "started") {
+            process = event.process.identity;
+            line("process", process);
+        }
+        else if (event.event === "output")
+            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);
+}
+async function forget(program) {
+    try {
+        await program.forget();
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "The Program represented by this handle does not exist")
+            return;
+        throw error;
+    }
+}
 function place(directory, location) {
     return /^https?:\/\//i.test(location) ? location : `./${relative(directory, location)}`;
 }

package/dist/program-installation.js

@@ -11,13 +11,14 @@ export default async function installProgram(program, options = {}) {
     let process = null;
     let installationFinished = false;
     try {
-        if (program instanceof Project)
-            installed = await program.install(system);
-        else {
-            installed = await system.forceCreateProgram(program);
-            for await (const chunk of installed.install())
-                writeProgramCommandOutput(chunk);
+        if (program instanceof Project) {
+            await program.build();
+            installed = await system.forceCreateProgram(program.productionDefinition());
         }
+        else
+            installed = await system.forceCreateProgram(program);
+        for await (const chunk of installed.install())
+            writeProgramCommandOutput(chunk);
         installationFinished = true;
         if (options.startup) {
             await installed.startup.enable();

package/dist/system/service/macos.js

@@ -1,6 +1,6 @@
 import { execute } from "../process.js";
 import { existsSync } from "node:fs";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
 const command = "/bin/launchctl";
@@ -9,7 +9,8 @@ export default class MacOSSystemService {
     run;
     label;
     environment;
-    plist;
+    definition;
+    startup;
     domain;
     target;
     constructor(userHome, run = execute, label = defaultLabel, uid = process.getuid?.(), environment = process.env) {
@@ -18,52 +19,58 @@ export default class MacOSSystemService {
         this.environment = environment;
         if (uid === undefined)
             throw new Error("The current macOS user could not be identified");
-        this.plist = join(userHome, "Library", "LaunchAgents", `${this.label}.plist`);
+        this.definition = join(userHome, "Library", "Application Support", "PhreshOS", "System", `${this.label}.plist`);
+        this.startup = join(userHome, "Library", "LaunchAgents", `${this.label}.plist`);
         this.domain = `gui/${uid}`;
         this.target = `${this.domain}/${this.label}`;
     }
     async inspect() {
-        const registered = existsSync(this.plist);
+        await this.migrate();
+        const registered = existsSync(this.definition);
         const service = await this.run(command, ["print", this.target]);
-        const disabled = await this.run(command, ["print-disabled", this.domain]);
-        const explicitlyDisabled = new RegExp(`"${escapePattern(this.label)}"\\s*=>\\s*(?:true|disabled)`).test(disabled.stdout);
         const pid = /\bpid\s*=\s*(\d+)/.exec(service.stdout)?.[1];
         return {
             registered,
             automaticStartup: true,
-            enabled: registered && !explicitlyDisabled,
+            enabled: registered && existsSync(this.startup),
             running: service.code === 0 && /\bstate\s*=\s*running\b/.test(service.stdout),
             ...(pid ? { pid: Number(pid) } : {})
         };
     }
     async register(definition) {
+        await this.migrate();
         await this.stop();
-        await mkdir(dirname(this.plist), { recursive: true });
         await mkdir(dirname(definition.output), { recursive: true });
-        const temporary = `${this.plist}.${randomUUID()}.tmp`;
-        try {
-            await writeFile(temporary, plist(this.label, definition, this.environment), { mode: 0o600 });
-            await rename(temporary, this.plist);
-        }
-        finally {
-            await rm(temporary, { force: true });
-        }
+        const content = plist(this.label, definition, this.environment);
+        await atomic(this.definition, content);
+        if (existsSync(this.startup))
+            await atomic(this.startup, content);
     }
     async unregister() {
+        await this.migrate();
         await this.stop();
-        await rm(this.plist, { force: true });
+        await Promise.all([
+            rm(this.definition, { force: true }),
+            rm(this.startup, { force: true })
+        ]);
+        await this.run(command, ["enable", this.target]);
     }
     async start() {
-        if (!existsSync(this.plist))
+        await this.migrate();
+        if (!existsSync(this.definition))
             throw new Error("The PhreshOS System service is not registered");
         const state = await this.inspect();
         if (state.running)
             return;
+        // launchctl disable prevents manual execution as well as login startup.
+        // Automatic startup is represented by the LaunchAgents copy instead,
+        // leaving the canonical definition eligible for an explicit start.
+        await this.require(["enable", this.target]);
         const loaded = await this.run(command, ["print", this.target]);
         if (loaded.code === 0)
             await this.require(["kickstart", "-k", this.target]);
         else
-            await this.require(["bootstrap", this.domain, this.plist]);
+            await this.require(["bootstrap", this.domain, this.definition]);
     }
     async stop() {
         const loaded = await this.run(command, ["print", this.target]);
@@ -71,14 +78,30 @@ export default class MacOSSystemService {
             await this.require(["bootout", this.target]);
     }
     async enable() {
-        if (!existsSync(this.plist))
+        await this.migrate();
+        if (!existsSync(this.definition))
             throw new Error("The PhreshOS System service is not registered");
+        await atomic(this.startup, await readFile(this.definition, "utf8"));
         await this.require(["enable", this.target]);
     }
     async disable() {
-        if (!existsSync(this.plist))
+        await this.migrate();
+        if (!existsSync(this.definition))
             throw new Error("The PhreshOS System service is not registered");
-        await this.require(["disable", this.target]);
+        await rm(this.startup, { force: true });
+        await this.require(["enable", this.target]);
+    }
+    /** Convert the former launchctl-disabled representation without changing its setting. */
+    async migrate() {
+        if (existsSync(this.definition) || !existsSync(this.startup))
+            return;
+        const disabled = await this.run(command, ["print-disabled", this.domain]);
+        const automatic = !new RegExp(`"${escapePattern(this.label)}"\\s*=>\\s*(?:true|disabled)`).test(disabled.stdout);
+        await atomic(this.definition, await readFile(this.startup, "utf8"));
+        if (!automatic) {
+            await rm(this.startup, { force: true });
+            await this.require(["enable", this.target]);
+        }
     }
     async require(args) {
         const result = await this.run(command, args);
@@ -129,6 +152,17 @@ function environmentPath(environment) {
     const key = Object.keys(environment).find(name => name.toLowerCase() === "path");
     return key === undefined ? undefined : environment[key];
 }
+async function atomic(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, content, { mode: 0o600 });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
 function xml(value) {
     return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
 }

package/dist/template/package.json

@@ -22,7 +22,7 @@
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.34",
+        "@phreshos/cli": "^0.1.36",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.34",
+    "version": "0.1.36",
     "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.22",
-        "@phreshos/node": "^0.1.1",
+        "@phreshos/core": "^0.1.23",
+        "@phreshos/node": "^0.1.2",
         "adm-zip": "^0.6.0",
         "commander": "^15.0.0",
         "jiti": "^2.7.0",