@phreshos/cli 0.1.31 → 0.1.33

package/README.md

@@ -10,8 +10,9 @@ active testing. The architecture's components will be released in stages as
 their contracts and integrations are verified.
 
 `@phreshos/cli` is not intended to be used independently of that architecture.
-Its Program commands depend on `@phreshos/core`, and its runtime operations
-require a compatible system installation.
+Its Program commands use `@phreshos/node`, whose `Project` model owns local
+project behavior and whose `System.connect()` provides the same Core contract
+used inside Server Programs. Runtime operations require a compatible System.
 
 ```bash
 phresh create app # create a complete new Program

package/dist/control-client.js

@@ -1,7 +1,44 @@
-import { requestSystem } from "./gateway.js";
+import { gatewayAddress, resolveHome } from "@phreshos/node";
+import { connect } from "node:net";
 /** Owner-local client for the authoritative running-System contract. */
 export default class LocalSystemControl {
-    execute(request, signal) {
-        return requestSystem(request, undefined, signal);
+    async execute(request, signal) {
+        const address = gatewayAddress(resolveHome());
+        return await new Promise((resolve, reject) => {
+            const socket = connect(address);
+            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", chunk => {
+                buffer += String(chunk);
+                const boundary = buffer.indexOf("\n");
+                if (boundary < 0)
+                    return;
+                try {
+                    const outcome = JSON.parse(buffer.slice(0, boundary));
+                    if (outcome.success)
+                        finish(() => resolve(outcome.result));
+                    else
+                        finish(() => reject(new Error(outcome.error)));
+                }
+                catch {
+                    finish(() => reject(new Error("The System returned an invalid response")));
+                }
+            });
+            socket.on("error", () => finish(() => reject(new Error(`No System is listening at ${address} — start PhreshOS first`))));
+            socket.on("close", () => finish(() => reject(new Error("The System closed the request without an answer"))));
+            if (signal?.aborted)
+                cancel();
+        });
     }
 }

package/dist/gateway.js

@@ -1,96 +1,5 @@
-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();
-    });
+import { gatewayAddress, resolveHome } from "@phreshos/node";
+/** Resolve the Gateway address while preserving the CLI's public helper. */
+export function gatewayPath(home = resolveHome(), platform = process.platform) {
+    return gatewayAddress(home, platform);
 }

package/dist/install.js

@@ -1,9 +1,7 @@
-import derive from "./derive.js";
-import { readConfig } from "./project.js";
+import { Project } from "@phreshos/node";
 import { dim, heading, line } from "./style.js";
 import installProgram, {} from "./program-installation.js";
 import { prepareOfficialProgram } from "./program-release.js";
-import build from "./build-command.js";
 /**
  * Lay this program out on this machine's system.
  *
@@ -26,7 +24,9 @@ export default async function install(options = {}) {
     const directory = options.directory ?? process.cwd();
     const prepared = options.name ? await prepareOfficialProgram(options.name) : null;
     try {
-        const program = prepared?.program ?? await localProgram(directory);
+        const program = prepared ? prepared.program : await Project.open(directory);
+        if (program instanceof Project && program.config.buildCommand)
+            line("build", program.config.buildCommand);
         const result = await installProgram(program, options);
         if (options.announce !== false) {
             const { name, identity, version } = result.program;
@@ -44,8 +44,3 @@ export default async function install(options = {}) {
         await prepared?.dispose();
     }
 }
-async function localProgram(directory) {
-    const config = await readConfig(directory);
-    await build(config, directory);
-    return derive(config, directory, "production");
-}

package/dist/launch.js

@@ -1,111 +1,56 @@
-import derive, {} from "./derive.js";
-import { readConfig } from "./project.js";
-import { dim, heading, line } from "./style.js";
+import { Project } from "@phreshos/node";
 import { relative } from "node:path";
-import attach from "./attach.js";
-import { assertClientDevelopmentUrlFree, commandFailure, startClientDevelopment, waitForClientDevelopment } from "./client-development.js";
-import build from "./build-command.js";
-/**
- * Run this program, without installing it, and stay with it.
- *
- * `phresh start` and `phresh dev` are the same act over the same
- * derivation, differing only in where each half is said to be — what the
- * build left, or where the source is.
- *
- * What the derivation produced is shown before it is sent, because it is
- * worth seeing rather than inferring from what happens next. Shown, not
- * dumped: the whole program.json is a wall of braces an author already
- * knows, and what they cannot know at a glance is which of their two
- * answers each half took. So each half says where it came from, and a
- * path is shortened back to the form they typed — the absolute one is
- * the machine's business, and they are standing in the directory it is
- * relative to.
- *
- * Nothing is installed. This local project is authoritative for attached
- * use of its declared identity: the system ends and forgets any runtime
- * Program already there, then registers this run as the sole uninstalled
- * occupant. Installed files and storage are not removed. Its root process
- * tethers the whole replacement to this command: when the process ends, the
- * registry record and any remaining processes go too.
- * **Attached means not installed; installed means persistent** — a
- * program meant to outlive a terminal is installed rather than run.
- *
- * A client development command belongs to this local authoring session,
- * never to the Program sent to the system. The declared client location
- * has to become reachable before that Program is launched, so the first
- * window does not open onto a destination already known to be absent.
- *
- * Its output arrives here because it has somewhere to arrive: the system
- * pipes a launched program only when someone is listening, and this is
- * the someone.
- */
-export default async function launch(which, directory = process.cwd(), options = {}) {
-    const config = await readConfig(directory);
-    if (which === "production")
-        await build(config, directory);
-    const program = derive(config, directory, which);
-    const clientDevelopmentConfig = which === "development" && program.client && (program.client.start ?? true)
-        ? config.client?.development
-        : undefined;
-    const clientStartCommand = clientDevelopmentConfig?.startCommand;
-    heading(`${program.name ?? program.identity}${program.version ? ` ${program.version}` : ""}`, which);
+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);
+    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(directory, program.server.location));
+        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", clientStartCommand ?? place(directory, program.client.location), clientStartCommand ? place(directory, program.client.location) : undefined);
-    line("storage", place(directory, String(program.storage)));
+        line("client", project.config.client?.development?.startCommand ?? place(project.directory, program.client.location));
+    line("storage", place(project.directory, String(program.storage)));
+    if (Object.keys(options).length)
+        line("options", Object.entries(options).map(([name, value]) => `${name}=${value}`).join("  "));
     console.log("");
-    if (clientStartCommand && program.client)
-        await assertClientDevelopmentUrlFree(program.client.location);
-    const clientDevelopment = clientDevelopmentConfig
-        ? startClientDevelopment(clientStartCommand, directory)
-        : null;
+    const system = await (await import("@phreshos/node")).System.connect();
     const controller = new AbortController();
-    let signalled = false;
-    const stopOnSignal = () => {
-        if (signalled)
+    let interrupted = false;
+    let ended = null;
+    const stop = () => {
+        if (interrupted)
             return;
-        signalled = true;
-        controller.abort();
-        void (clientDevelopment?.stop() ?? Promise.resolve()).finally(() => process.exit(130));
+        interrupted = true;
+        controller.abort(new Error("The local Program run was interrupted"));
     };
-    // A signal ends this command, and ending this command closes the
-    // socket, and closing the socket stops the program. A client development
-    // command is another child of the same session, so it is ended first.
     for (const signal of ["SIGINT", "SIGTERM"])
-        process.on(signal, stopOnSignal);
-    let status = 0;
+        process.on(signal, stop);
     try {
-        if (clientDevelopmentConfig && program.client)
-            await waitForClientDevelopment(program.client.location, clientDevelopment);
-        if (Object.keys(options).length)
-            line("options", Object.entries(options).map(([name, value]) => `${name}=${value}`).join("  "));
-        const attachment = attach(program, options, {
-            started: identity => console.log(`${clientDevelopment ? "\n" : ""}  ${dim("running as")} ${identity}\n`),
-            output: (stream, text) => (stream === "err" ? process.stderr : process.stdout).write(text)
-        }, undefined, controller.signal);
-        const ended = clientDevelopment ? await Promise.race([
-            attachment,
-            clientDevelopment.exited.then(exit => {
-                if (clientDevelopment.stopping)
-                    return new Promise(() => undefined);
-                controller.abort();
-                throw commandFailure(exit);
-            })
-        ]) : await attachment;
-        console.log(`\n  ${dim(ended.signal ? `ended on ${ended.signal}` : `ended with ${ended.code ?? 0}`)}\n`);
-        status = ended.signal ? 128 : ended.code ?? 0;
+        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 };
+    }
+    catch (error) {
+        if (!interrupted)
+            throw error;
     }
     finally {
         for (const signal of ["SIGINT", "SIGTERM"])
-            process.off(signal, stopOnSignal);
-        await clientDevelopment?.stop();
+            process.off(signal, stop);
+        await system.disconnect();
     }
-    // Its status is this command's status: whoever ran the program is
-    // owed what the program said on the way out.
-    process.exit(status);
+    if (interrupted)
+        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`);
+    process.exit(ended.signal ? 128 : ended.code ?? 0);
 }
-// A URL as written; a path as the author typed it.
-function place(directory, where) {
-    return /^https?:\/\//i.test(where) ? where : `./${relative(directory, where)}`;
+function place(directory, location) {
+    return /^https?:\/\//i.test(location) ? location : `./${relative(directory, location)}`;
 }

package/dist/pack.js

@@ -1,107 +1,11 @@
-import { readConfig, readManifest } from "./project.js";
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import AdmZip from "adm-zip";
-import build from "./build-command.js";
-/**
- * Package what is at each half's location.
- *
- * When the author config declares `buildCommand`, it completes before
- * any files are gathered. Pack remains an assembler rather than a
- * build tool: it invokes the author's command, then packages its result.
- *
- * The authoring tree and the installable form differ. A program may
- * leave its halves anywhere; the package always has them in the same
- * places, so the artifact's shape is the contract's rather than the
- * author's. The program.json names those canonical places explicitly:
- * a declared half always has a location, even when the system chose it.
- *
- * There is **no wrapping directory**. `program.json`, `server/`,
- * `client/`, optional `icon.png`, and optional `agent.md` sit at the package's
- * root, and the directory
- * the system installs into is named from the program's own `identity`.
- * The archive itself therefore needs no second naming layer.
- *
- * The files go into the archive directly rather than through a staging
- * directory: a copy of a build is a thing that can be stale. The generated
- * standalone program.json is also placed beside the archive for release
- * discovery; both declarations are made from the same bytes.
- */
+import { Project } from "@phreshos/node";
+import { line } from "./style.js";
+/** Package the current Project and present only its command-facing progress. */
 export default async function pack(directory = process.cwd()) {
-    const config = await readConfig(directory);
-    await build(config, directory);
-    const manifest = await readManifest(directory);
-    const version = config.version ?? manifest.version;
-    if (config.version && manifest.version && config.version !== manifest.version) {
-        console.log(`phresh: packing ${config.version}, though package.json says ${manifest.version}\n`);
-    }
-    const zip = new AdmZip();
-    if (config.server)
-        place(zip, directory, config.server.location, "server");
-    if (config.client) {
-        place(zip, directory, config.client.location, "client");
-        if (!zip.getEntry("client/index.html"))
-            throw new Error(`The client files have no index.html — ${config.client.location} is not where a client half is`);
-    }
-    if (config.icon)
-        file(zip, directory, config.icon, "icon.png", "Program icon");
-    if (config.agent)
-        file(zip, directory, config.agent, "agent.md", "Program agent documentation");
-    const declaration = Buffer.from(JSON.stringify(program(config, version), null, 4) + "\n");
-    zip.addFile("program.json", declaration);
-    // The standalone release declaration and the declaration inside the
-    // archive are the same bytes. There is no separately authored catalog
-    // description that can drift from the installable Program.
-    writeFileSync(resolve(directory, "program.json"), declaration);
-    const archive = `${config.identity}@${version ?? "0.0.0"}.zip`;
-    const bytes = zip.toBuffer();
-    writeFileSync(resolve(directory, archive), bytes);
-    const digest = createHash("sha256").update(bytes).digest("hex");
-    writeFileSync(resolve(directory, `${archive}.sha256`), `${digest}  ${archive}\n`);
-    console.log(`\nPacked ${archive}`);
-    return archive;
-}
-// The derivation, and the whole of it. What the config says about the
-// program passes through; what it says about the build does not. Half
-// locations are rewritten to the canonical places inside the package.
-function program(config, version) {
-    return {
-        identity: config.identity,
-        name: config.name,
-        version,
-        description: config.description,
-        icon: config.icon ? "icon.png" : undefined,
-        agent: config.agent ? "agent.md" : undefined,
-        categories: config.categories,
-        keywords: config.keywords,
-        website: config.website,
-        ...config.server && { server: {
-                location: "server",
-                start: config.server.start,
-                installCommand: config.server.installCommand,
-                uninstallCommand: config.server.uninstallCommand,
-                ...serverExecution(config.server)
-            } },
-        ...config.client && { client: { location: "client", start: config.client.start, title: config.client.title, size: config.client.size, position: config.client.position, layer: config.client.layer, minimize: config.client.minimize } }
-    };
-}
-function serverExecution(server) {
-    return server.startCommand !== undefined
-        ? { startCommand: server.startCommand }
-        : { entryFile: server.entryFile };
-}
-// What is at a half's location, where the package keeps it. A half that
-// was declared and is not there is the answer to whether it was built.
-function place(zip, directory, location, half) {
-    const from = resolve(directory, location);
-    if (!existsSync(from))
-        throw new Error(`The ${half} files are not at ${location} — nothing was built there`);
-    zip.addLocalFolder(from, half);
-}
-function file(zip, directory, location, target, label) {
-    const from = resolve(directory, location);
-    if (!existsSync(from) || !statSync(from).isFile())
-        throw new Error(`The ${label} is not at ${location}`);
-    zip.addFile(target, readFileSync(from));
+    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}`);
+    return packed.archive;
 }

package/dist/program-installation.js

@@ -1,57 +1,53 @@
-import { streamProgram } from "./gateway.js";
+import { Project } from "@phreshos/node";
 import writeProgramCommandOutput from "./program-command-output.js";
 /** Install one prepared Program and await every explicitly requested outcome. */
 export default async function installProgram(program, options = {}) {
-    let installedValue;
-    let replaced = false;
+    const system = await (await import("@phreshos/node")).System.connect();
+    const identity = program instanceof Project ? program.config.identity : program.identity;
+    const current = await system.program.find(identity);
+    const replaced = await current?.installed() ?? false;
+    let installed = null;
     let startupEnabled = false;
-    let processValue;
-    await streamProgram({
-        word: "install",
-        program,
-        run: options.run === true,
-        startup: options.startup === true
-    }, function (event) {
-        if (event.event === "output")
-            writeProgramCommandOutput(event);
-        else if (event.event === "installed") {
-            installedValue = event.program;
-            replaced = event.replaced === true;
+    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);
         }
-        else if (event.event === "startupEnabled")
+        installationFinished = true;
+        if (options.startup) {
+            await installed.startup.enable();
             startupEnabled = true;
-        else if (event.event === "running")
-            processValue = event.process;
-    });
-    if (installedValue === undefined)
+        }
+        if (options.run)
+            process = (await installed.process.create()).identity;
+    }
+    catch (error) {
+        if (installed && !installationFinished) {
+            try {
+                await installed.forget();
+            }
+            catch { /* Preserve the installation failure. */ }
+        }
+        throw error;
+    }
+    finally {
+        await system.disconnect();
+    }
+    if (!installed)
         throw new Error("The System ended Program installation without confirming it");
-    const installed = installedProgram(installedValue);
     if (options.startup && !startupEnabled)
         throw new Error("The System installed the Program without confirming startup");
-    const process = processValue === undefined ? null : processIdentity(processValue);
     if (options.run && !process)
         throw new Error("The System installed the Program without confirming that it is running");
     return {
-        program: installed,
+        program: { identity: installed.identity, name: installed.name, version: installed.version },
         replaced,
         startupEnabled,
         process
     };
 }
-function processIdentity(value) {
-    if (typeof value !== "string" || !value)
-        throw new Error("The System returned an invalid Process identity");
-    return value;
-}
-function installedProgram(value) {
-    if (!record(value)
-        || typeof value.identity !== "string"
-        || typeof value.name !== "string"
-        || value.version !== null && typeof value.version !== "string") {
-        throw new Error("The System returned an invalid installed Program");
-    }
-    return { identity: value.identity, name: value.name, version: value.version };
-}
-function record(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/dist/program-release.js

@@ -85,6 +85,7 @@ async function readProgram(directory, release) {
         throw new Error("A published Program package cannot choose its installed storage");
     return {
         ...value,
+        storage: join(directory, "storage"),
         ...pathField(value, directory, "icon", "icon.png"),
         ...pathField(value, directory, "agent", "agent.md"),
         ...half(value, directory, "server"),

package/dist/project.js

@@ -1,126 +1,11 @@
-import { isRelativeValue, layers } from "@phreshos/core";
+import { Project } from "@phreshos/node";
 import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { isAbsolute, normalize, resolve, sep } from "node:path";
-import { createJiti } from "jiti";
 export const configFile = "phresh.config.ts";
+/** Read the current Project through the reusable Node project model. */
 export async function readConfig(directory = process.cwd()) {
-    const path = resolve(directory, configFile);
-    if (!existsSync(path))
-        throw new Error(`There is no ${configFile} here — run: phresh init`);
-    // Program declarations remain typed authoring files independently of the
-    // Node version that happens to execute the CLI.
-    const config = await createJiti(import.meta.url).import(path, { default: true }).catch(function (error) {
-        throw new Error(`${configFile} could not be read (${error.message})`);
-    });
-    if (!config)
-        throw new Error(`${configFile} must export its config as the default export`);
-    coherent(config);
-    return config;
-}
-// Whether the words agree with each other. Nothing here touches a disk
-// or asks whether a build ran: it is the same question the system asks
-// of a program.json when it is constructed, asked earlier, where the
-// person who mistyped it is still standing.
-function coherent(config) {
-    // A name is the name of a directory before it is anything else, and
-    // the system checks it again where it makes one. Checked here too so
-    // the mistake is found by the CLI rather than at the runtime border.
-    if (typeof config.identity !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(config.identity))
-        throw new Error("A program's identity is kebab-case, because it is also the name of its directory");
-    if (!config.server && !config.client)
-        throw new Error("A program must have a server half, a client half, or both");
-    for (const field of ["name", "version", "description", "icon", "agent", "website"]) {
-        if (config[field] !== undefined && typeof config[field] !== "string")
-            throw new Error(`A program's ${field} must be text`);
-    }
-    if (config.agent !== undefined && config.agent.trim().length === 0)
-        throw new Error("A program's agent documentation must be a non-empty path");
-    if (config.website !== undefined) {
-        try {
-            new URL(config.website);
-        }
-        catch {
-            throw new Error("A program's website must be a valid URL");
-        }
-    }
-    for (const [field, maximum] of [["categories", 20], ["keywords", 50]]) {
-        const values = config[field];
-        if (values === undefined)
-            continue;
-        if (!Array.isArray(values) || values.length > maximum || values.some(value => typeof value !== "string" || value.trim().length === 0 || value.trim().length > 50)) {
-            throw new Error(`A program's ${field} must contain at most ${maximum} non-empty values of at most 50 characters`);
-        }
-    }
-    if (config.buildCommand !== undefined && (typeof config.buildCommand !== "string" || config.buildCommand.trim().length === 0))
-        throw new Error("A program's buildCommand must be non-empty text");
-    for (const half of ["server", "client"]) {
-        const declared = config[half];
-        if (declared === undefined)
-            continue;
-        if (typeof declared !== "object" || declared === null || Array.isArray(declared))
-            throw new Error(`A program's ${half} half must be a declaration`);
-        if (typeof declared.location !== "string")
-            throw new Error(`A declared ${half} half must have a location`);
-        if (declared.start !== undefined && typeof declared.start !== "boolean")
-            throw new Error(`A declared ${half} endpoint's start default must be true or false`);
-    }
-    if (!(config.server && (config.server.start ?? true)) && !(config.client && (config.client.start ?? true)))
-        throw new Error("A Program's default Process must start a server endpoint, a client endpoint, or both");
-    if (config.server)
-        execution(config.server, "A server half");
-    if (config.server?.installCommand !== undefined && typeof config.server.installCommand !== "string")
-        throw new Error("A server half's install command must be text");
-    if (config.server?.uninstallCommand !== undefined && typeof config.server.uninstallCommand !== "string")
-        throw new Error("A server half's uninstall command must be text");
-    if (config.client?.title !== undefined && typeof config.client.title !== "string")
-        throw new Error("A client half's title must be text");
-    if (config.client?.minimize !== undefined && typeof config.client.minimize !== "boolean")
-        throw new Error("A client half's minimize default must be true or false");
-    if (config.client && /^https?:\/\//i.test(config.client.location)) {
-        try {
-            new URL(config.client.location);
-        }
-        catch {
-            throw new Error("A client half's URL must be a valid HTTP or HTTPS URL");
-        }
-    }
-    // Said wrong is caught here, where the author is standing, rather
-    // than becoming a window in no layer at all.
-    if (config.client?.layer !== undefined && !layers.includes(config.client.layer))
-        throw new Error(`A client half's layer is one of ${layers.join(", ")} — not "${String(config.client.layer)}"`);
-    const serverDevelopment = config.server?.development;
-    if (serverDevelopment !== undefined && (typeof serverDevelopment !== "object" || serverDevelopment === null || Array.isArray(serverDevelopment)))
-        throw new Error("server.development must be a declaration");
-    if (serverDevelopment !== undefined)
-        execution(serverDevelopment, "server.development");
-    const clientDevelopment = config.client?.development;
-    if (clientDevelopment !== undefined && (typeof clientDevelopment !== "object" || clientDevelopment === null || Array.isArray(clientDevelopment)))
-        throw new Error("client.development must be a declaration");
-    if (clientDevelopment !== undefined && !httpUrl(clientDevelopment.url))
-        throw new Error("client.development.url must be a valid HTTP or HTTPS URL");
-    if (clientDevelopment?.startCommand !== undefined && (typeof clientDevelopment.startCommand !== "string" || clientDevelopment.startCommand.trim().length === 0))
-        throw new Error("client.development.startCommand must be non-empty text");
-    for (const [what, value] of [["size", config.client?.size], ["position", config.client?.position]]) {
-        if (value === undefined)
-            continue;
-        if (typeof value !== "object" || value === null || Array.isArray(value))
-            throw new Error(`A window's ${what} must name both of its values`);
-        const pair = what === "size" ? [value.width, value.height] : [value.x, value.y];
-        if (!pair.every(isRelativeValue))
-            throw new Error(`A window's ${what} is a finite pixel number or a relative expression such as "50% + 10"`);
-    }
-}
-function execution(value, owner) {
-    const command = typeof value.startCommand === "string" && value.startCommand.trim().length > 0;
-    const entry = typeof value.entryFile === "string" && value.entryFile.trim().length > 0;
-    if (value.startCommand !== undefined && !command)
-        throw new Error(`${owner}'s startCommand must be non-empty text`);
-    if (value.entryFile !== undefined && !entry)
-        throw new Error(`${owner}'s entryFile must be a non-empty path`);
-    if (command === entry)
-        throw new Error(`${owner} must declare exactly one non-empty startCommand or entryFile`);
-    if (entry && !containedServerEntry(value.entryFile))
-        throw new Error(`${owner}'s entryFile must remain inside its Server directory`);
+    return (await Project.open(directory)).config;
 }
 export function containedServerEntry(entry) {
     if (isAbsolute(entry))
@@ -128,23 +13,13 @@ export function containedServerEntry(entry) {
     const path = normalize(entry);
     return path !== ".." && !path.startsWith(`..${sep}`);
 }
-function httpUrl(value) {
-    if (typeof value !== "string" || value.trim().length === 0)
-        return false;
-    try {
-        const url = new URL(value);
-        return url.protocol === "http:" || url.protocol === "https:";
-    }
-    catch {
-        return false;
-    }
-}
 export async function readManifest(directory = process.cwd()) {
     const path = resolve(directory, "package.json");
     if (!existsSync(path))
         throw new Error("There is no package.json here");
-    const manifest = JSON.parse(await import("node:fs/promises").then(fs => fs.readFile(path, "utf-8")));
-    if (typeof manifest.name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(manifest.name))
+    const manifest = JSON.parse(await readFile(path, "utf8"));
+    if (typeof manifest.name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(manifest.name)) {
         throw new Error("package.json must have a kebab-case name");
+    }
     return manifest;
 }

package/dist/template/package.json

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

package/dist/uninstall.js

@@ -1,20 +1,24 @@
 import { readConfig } from "./project.js";
 import { dim, heading } from "./style.js";
-import { streamProgram } from "./gateway.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 = {}) {
     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;
+    const system = await (await import("@phreshos/node")).System.connect();
+    try {
+        const program = await system.program.find(identity);
+        if (!program)
+            throw new Error("The System does not know this Program");
+        for await (const chunk of program.uninstall(options.everything === true))
+            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`);
-    });
+    }
+    finally {
+        await system.disconnect();
+    }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.31",
+    "version": "0.1.33",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"
@@ -49,7 +49,8 @@
     "packageManager": "bun@1.3.14",
     "dependencies": {
         "@clack/prompts": "^1.7.0",
-        "@phreshos/core": "^0.1.20",
+        "@phreshos/core": "^0.1.22",
+        "@phreshos/node": "^0.1.1",
         "adm-zip": "^0.6.0",
         "commander": "^15.0.0",
         "jiti": "^2.7.0",

package/dist/attach.js

@@ -1,29 +0,0 @@
-import { gatewayPath, streamProgram } from "./gateway.js";
-/**
- * Run a program on this machine's system, and stay with it.
- *
- * **The connection is the tether, in both directions.** While it is open
- * the program runs; when it closes the system stops the program. So this
- * does not have to promise to clean up, and could not be trusted if it
- * did: a `kill -9`, a closed terminal and a dropped ssh session all end
- * this process without running a line of it, and every one of them still
- * closes the socket. The other direction is the same fact from the other
- * 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 = gatewayPath(), signal) {
-    let ended = null;
-    await streamProgram({ word: "run", program, options }, function (event) {
-        if (event.event === "started")
-            watching.started?.(String(event.process));
-        if (event.event === "output")
-            watching.output?.(event.stream === "err" ? "err" : "out", String(event.text));
-        if (event.event === "exited")
-            ended = { code: (event.code ?? null), signal: (event.signal ?? null) };
-    }, path, signal);
-    // Closed with no ending said: the system went away while the program
-    // was running, which is a different thing from the program ending.
-    if (!ended)
-        throw new Error("The system closed before the program ended");
-    return ended;
-}

package/dist/build-command.js

@@ -1,22 +0,0 @@
-import { line } from "./style.js";
-import { spawn } from "node:child_process";
-import commandEnvironment from "./command-environment.js";
-/** Run the optional build owned by `start`, `install`, and `pack`, never by the system. */
-export default async function build(config, directory) {
-    const command = config.buildCommand;
-    if (!command)
-        return;
-    line("build", command);
-    await new Promise(function (resolve, reject) {
-        const child = spawn(command, { cwd: directory, env: commandEnvironment(directory), shell: true, stdio: "inherit" });
-        child.once("error", error => reject(new Error(`Build command failed: ${error.message}`)));
-        child.once("exit", function (code, signal) {
-            if (signal)
-                reject(new Error(`Build command ended on ${signal}`));
-            else if (code !== 0)
-                reject(new Error(`Build command exited with ${code ?? 0}`));
-            else
-                resolve();
-        });
-    });
-}

package/dist/client-development.js

@@ -1,161 +0,0 @@
-import { spawn } from "node:child_process";
-import { connect } from "node:net";
-import { line } from "./style.js";
-import commandEnvironment from "./command-environment.js";
-const timeout = 15_000;
-const reportEvery = 2_000;
-const pollEvery = 200;
-const clientOrigin = "null";
-/** Refuse to start an owned command over a URL already served by something else. */
-export async function assertClientDevelopmentUrlFree(url) {
-    if (!await occupied(url))
-        return;
-    throw new Error(`Client development URL is already in use: ${url}`);
-}
-function occupied(url) {
-    const location = new URL(url);
-    const port = Number(location.port || (location.protocol === "https:" ? 443 : 80));
-    return new Promise(resolve => {
-        const socket = connect({ host: location.hostname, port });
-        let settled = false;
-        const settle = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            socket.destroy();
-            resolve(value);
-        };
-        socket.setTimeout(500);
-        socket.once("connect", () => settle(true));
-        socket.once("error", () => settle(false));
-        socket.once("timeout", () => settle(false));
-    });
-}
-/** Start the author's client tool without making it part of ProgramConfig. */
-export function startClientDevelopment(command, directory) {
-    if (!command)
-        return null;
-    const child = spawn(command, {
-        cwd: directory,
-        env: commandEnvironment(directory),
-        shell: true,
-        stdio: "inherit",
-        // The command and everything it starts are one owned tool. A Vite
-        // child must not survive after the shell that launched it is gone.
-        detached: true
-    });
-    let result = null;
-    let stopping = false;
-    let stoppingTask = null;
-    let settle = () => undefined;
-    const exited = new Promise(resolve => { settle = resolve; });
-    const finish = (exit) => {
-        if (result)
-            return;
-        result = exit;
-        settle(exit);
-    };
-    child.once("error", error => finish({ code: null, signal: null, error }));
-    child.once("exit", (code, signal) => finish({ code, signal, error: null }));
-    return {
-        exited,
-        get stopping() { return stopping; },
-        async stop() {
-            if (!stoppingTask) {
-                stopping = true;
-                stoppingTask = (async () => {
-                    if (!running(child))
-                        return;
-                    terminate(child, "SIGTERM");
-                    await waitUntilStopped(child, 1_000);
-                    if (running(child))
-                        terminate(child, "SIGKILL");
-                    await waitUntilStopped(child, 1_000);
-                })();
-            }
-            await stoppingTask;
-        }
-    };
-}
-/** Wait for the exact client URL that the derived Program will open. */
-export async function waitForClientDevelopment(url, command, waiting = timeout, reporting = reportEvery) {
-    const began = Date.now();
-    let nextReport = began + reporting;
-    const commandEnded = command?.exited.then(exit => { throw commandFailure(exit); });
-    while (Date.now() - began < waiting) {
-        const availability = await inspect(url, waiting - (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: ${url}`,
-                `Enable CORS so the response includes Access-Control-Allow-Origin: * (for Vite, use server: { cors: true }).`
-            ].join("\n"));
-        }
-        const now = Date.now();
-        if (now >= nextReport) {
-            line("waiting for", url);
-            while (nextReport <= now)
-                nextReport += reporting;
-        }
-        const remaining = waiting - (Date.now() - began);
-        if (remaining <= 0)
-            break;
-        await Promise.race([
-            pause(Math.min(pollEvery, remaining)),
-            ...(commandEnded ? [commandEnded] : [])
-        ]);
-    }
-    const seconds = waiting / 1_000;
-    throw new Error(`Client development URL did not respond within ${seconds} ${seconds === 1 ? "second" : "seconds"}: ${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}`);
-}
-async function inspect(url, remaining) {
-    try {
-        const response = await fetch(url, {
-            headers: { origin: clientOrigin },
-            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 === clientOrigin ? "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 pause(20);
-}
-function pause(milliseconds) {
-    return new Promise(resolve => setTimeout(resolve, milliseconds));
-}

package/dist/command-environment.js

@@ -1,10 +0,0 @@
-import { delimiter, join } from "node:path";
-/** Give author commands the same project-local binary resolution as scripts. */
-export default 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)
-    };
-}

package/dist/derive.js

@@ -1,98 +0,0 @@
-import { resolve } from "node:path";
-export default function derive(config, directory, which) {
-    const server = serverHalf(config.server, which);
-    const client = clientHalf(config.client, which);
-    if (which === "development" && !config.server?.development && !config.client?.development) {
-        // Where a `development` block is learned, now that nothing writes
-        // one for you. It shows each half's distinct shape because their
-        // development locations are deliberately not the same concept.
-        throw new Error([
-            "Nothing here says how this program is developed.",
-            "",
-            "Say how the server runs or where the client is served:",
-            "",
-            "    server: {",
-            "        …",
-            "        development: { startCommand: \"tsx source/server/main.ts\" }",
-            "        // or: development: { entryFile: \"source/server/main.js\" }",
-            "    }",
-            "",
-            "    client: {",
-            "        …",
-            "        development: { url: \"http://localhost:5173\", startCommand: \"bun run dev\" }",
-            "    }"
-        ].join("\n"));
-    }
-    return {
-        identity: config.identity,
-        name: config.name,
-        version: config.version,
-        description: config.description,
-        categories: config.categories,
-        keywords: config.keywords,
-        website: config.website,
-        // Where it already is. Unlike pack, which gives it its canonical
-        // name, this points into the authoring tree and leaves it alone.
-        icon: config.icon && resolve(directory, config.icon),
-        agent: config.agent && resolve(directory, config.agent),
-        // Beside the source, and said out loud. A program built from an
-        // object resolves what it leaves unsaid against the *system's*
-        // working directory — so silence here means a program keeps what
-        // it keeps wherever the system happened to be started, which is
-        // nobody's idea of its own place.
-        storage: resolve(directory, "storage"),
-        ...server && { server: {
-                location: resolve(directory, server.location),
-                start: server.start,
-                installCommand: config.server?.installCommand,
-                uninstallCommand: config.server?.uninstallCommand,
-                ...serverExecution(server)
-            } },
-        // A URL stands as written; a directory is made absolute. The
-        // contract reads both from the one field, and which it is is
-        // decided by the same test the system uses.
-        ...client && { client: {
-                location: /^https?:\/\//i.test(client.location) ? client.location : resolve(directory, client.location),
-                start: client.start,
-                title: config.client?.title,
-                size: config.client?.size,
-                position: config.client?.position,
-                layer: config.client?.layer,
-                minimize: config.client?.minimize
-            } }
-    };
-}
-// Only the fields each development shape owns are selected. Unknown
-// runtime values do not become program fields merely because they were
-// present in a JavaScript object.
-function serverHalf(half, which) {
-    if (!half)
-        return null;
-    const { development, startCommand, entryFile, ...description } = half;
-    if (which === "production" || !development)
-        return {
-            ...description,
-            ...serverExecution({ startCommand, entryFile })
-        };
-    return {
-        ...description,
-        location: ".",
-        ...serverExecution(development)
-    };
-}
-function serverExecution(server) {
-    return server.startCommand !== undefined
-        ? { startCommand: server.startCommand }
-        : { entryFile: server.entryFile };
-}
-function clientHalf(half, which) {
-    if (!half)
-        return null;
-    const { development, ...declared } = half;
-    if (which === "production" || !development)
-        return declared;
-    return {
-        ...declared,
-        location: development.url
-    };
-}