@phreshos/cli 0.1.0

package/dist/client-development.js

@@ -0,0 +1,149 @@
+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;
+/** 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) {
+        if (await available(url, waiting - (Date.now() - began)))
+            return;
+        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 available(url, remaining) {
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(Math.max(1, Math.min(500, remaining))) });
+        await response.body?.cancel();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,89 @@
+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\" }",
+            "    }",
+            "",
+            "    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,
+        // Like icons, the document stays where the author put it for an
+        // attached run. Installation and packaging give it its canonical
+        // name; the runtime receives an absolute source path here because a
+        // derived description has no file beside which to resolve it.
+        apiDocs: config.apiDocs && resolve(directory, config.apiDocs),
+        // Where they already are. Unlike pack, which stages them, this
+        // points into the authoring tree and leaves it alone.
+        icons: config.icons && resolve(directory, config.icons),
+        // 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,
+                startCommand: server.startCommand
+            } },
+        // 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, ...declared } = half;
+    if (which === "production" || !development)
+        return declared;
+    return {
+        ...declared,
+        location: ".",
+        startCommand: development.startCommand
+    };
+}
+function clientHalf(half, which) {
+    if (!half)
+        return null;
+    const { development, ...declared } = half;
+    if (which === "production" || !development)
+        return declared;
+    return {
+        ...declared,
+        location: development.url
+    };
+}

package/dist/init.js

@@ -0,0 +1,201 @@
+import {} from "@phreshos/core";
+import { configFile, readManifest } from "./project.js";
+import { dim, heading, line } from "./style.js";
+import ensureProjectDependency, { projectScript } from "./project-dependency.js";
+import { createInterface } from "node:readline/promises";
+import { existsSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Initialize an existing project as a Program.
+ *
+ * A real terminal gets a short interview. Everywhere else, every choice is a
+ * named option and the command never waits for input. Both routes produce the
+ * same config and ensure the matching Core dependency through this one
+ * function.
+ */
+export default async function init(options = {}, directory = process.cwd(), coreVersion = "0.1.0") {
+    const manifest = await readManifest(directory);
+    const path = resolve(directory, configFile);
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const explicitShape = options.server === true || options.client === true;
+    if (existsSync(path) && options.force !== true && !interactive)
+        throw new Error(`${configFile} already exists — use --force to replace it`);
+    const readline = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+    async function ask(question, fallback) {
+        if (!readline)
+            throw new Error(`${question} Supply the corresponding option when no terminal is attached`);
+        const suffix = fallback === undefined ? "" : ` ${dim(`(${fallback})`)}`;
+        const said = (await readline.question(`  ${question}${suffix} `)).trim();
+        return said || fallback || "";
+    }
+    async function yes(question, fallback) {
+        return (await ask(question, fallback ? "Y/n" : "y/N")).toLowerCase().startsWith("y");
+    }
+    try {
+        if (existsSync(path) && options.force !== true) {
+            heading(configFile, "already initialized");
+            if (!await yes("Replace it?", false)) {
+                console.log(`\n  ${dim("No changes made.")}\n`);
+                return;
+            }
+        }
+        heading("Initialize Program", manifest.name);
+        line("identity", manifest.name, "package.json");
+        if (manifest.version)
+            line("version", manifest.version, "package.json");
+        if (manifest.description)
+            line("description", manifest.description, "package.json");
+        console.log("");
+        let serverSelected = options.server === true;
+        let clientSelected = options.client === true;
+        if (!explicitShape) {
+            if (!interactive)
+                throw new Error("Choose at least one half with --server, --client, or both");
+            serverSelected = await yes("Include a server half?", true);
+            clientSelected = !serverSelected || await yes("Include a client half?", true);
+        }
+        if (!serverSelected && !clientSelected)
+            throw new Error("A Program must have a server half, a client half, or both");
+        const name = options.name ?? (interactive ? await ask("What name should people see?", manifest.name) : undefined);
+        if (name !== undefined && name.trim().length === 0)
+            throw new Error("--name must not be empty");
+        let apiDocs = options.apiDocs;
+        if (interactive && apiDocs === undefined) {
+            const suggested = ["api-docs.md", "README.md"].find(file => existsSync(resolve(directory, file)));
+            if (await yes("Provide an API documentation entry point?", Boolean(suggested)))
+                apiDocs = await ask("Where is its Markdown file?", suggested);
+        }
+        if (apiDocs !== undefined && apiDocs.trim().length === 0)
+            throw new Error("An API documentation path must not be empty");
+        let buildCommand = options.buildCommand;
+        if (interactive && buildCommand === undefined) {
+            const suggested = manifest.scripts?.build && projectScript(directory, manifest.packageManager, "build");
+            const builds = await yes("Run a command before production start, install, and pack?", Boolean(suggested));
+            if (builds)
+                buildCommand = await ask("What builds the production files?", suggested || undefined);
+        }
+        if (buildCommand !== undefined && buildCommand.trim().length === 0)
+            throw new Error("A build command must not be empty");
+        let server;
+        if (serverSelected) {
+            const location = options.serverLocation ?? (interactive ? await ask("Where are the production server files?", "build/server") : "");
+            const startCommand = options.serverStartCommand ?? (interactive ? await ask("What starts the production server?", "node main.js") : "");
+            if (!location)
+                throw new Error("--server-location is required without a terminal");
+            if (!startCommand)
+                throw new Error("--server-start-command is required without a terminal");
+            let development = options.serverDevelopmentStartCommand;
+            if (interactive && development === undefined) {
+                const suggested = manifest.scripts?.dev && projectScript(directory, manifest.packageManager, "dev");
+                if (await yes("Develop the server from source?", Boolean(suggested && !clientSelected)))
+                    development = await ask("What starts the development server?", suggested || undefined);
+            }
+            if (development !== undefined && development.trim().length === 0)
+                throw new Error("A server development command must not be empty");
+            server = { location, startCommand, ...development && { development: { startCommand: development } } };
+        }
+        let client;
+        if (clientSelected) {
+            const location = options.clientLocation ?? (interactive ? await ask("Where are the production client files?", "dist") : "");
+            if (!location)
+                throw new Error("--client-location is required without a terminal");
+            let developmentUrl = options.clientDevelopmentUrl;
+            let developmentStartCommand = options.clientDevelopmentStartCommand;
+            if (interactive && developmentUrl === undefined && developmentStartCommand === undefined) {
+                const suggested = manifest.scripts?.dev && projectScript(directory, manifest.packageManager, "dev");
+                if (await yes("Use a client development server?", Boolean(suggested))) {
+                    developmentUrl = await ask("Where is the development client served?", "http://localhost:5173/");
+                    if (await yes("Should the CLI start that development server?", Boolean(suggested)))
+                        developmentStartCommand = await ask("What starts it?", suggested || undefined);
+                }
+            }
+            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 } } }
+            };
+        }
+        const described = {
+            identity: manifest.name,
+            name,
+            version: manifest.version,
+            description: manifest.description,
+            apiDocs,
+            buildCommand
+        };
+        const config = server
+            ? { ...described, server, ...client && { client } }
+            : { ...described, client: client };
+        await ensureProjectDependency("@phreshos/core", coreVersion, directory);
+        writeFileSync(path, compose(config));
+        heading(configFile, "created");
+        if (config.server)
+            line("server", config.server.startCommand, `./${config.server.location}`);
+        if (config.client)
+            line("client", `./${config.client.location}`);
+        console.log("");
+        const next = [config.server?.development || config.client?.development ? "phresh dev" : null, "phresh start", "phresh install"].filter(Boolean);
+        console.log(`  ${dim("Next:")} ${next.join(`  ${dim("or")}  `)}\n`);
+    }
+    finally {
+        readline?.close();
+    }
+}
+function compose(config) {
+    const blocks = [
+        field("identity", config.identity),
+        field("name", config.name),
+        field("version", config.version),
+        field("description", config.description),
+        field("apiDocs", config.apiDocs),
+        field("buildCommand", config.buildCommand),
+        half("server", config.server && {
+            location: config.server.location,
+            startCommand: config.server.startCommand,
+            ...config.server.development && { development: config.server.development }
+        }),
+        half("client", config.client && {
+            location: config.client.location,
+            ...config.client.development && { development: config.client.development }
+        })
+    ];
+    return [
+        `import { defineConfig } from "@phreshos/core"`,
+        "",
+        "export default defineConfig({",
+        "",
+        blocks.filter(Boolean).join(",\n\n"),
+        "})",
+        ""
+    ].join("\n");
+}
+function field(name, value) {
+    return value === undefined ? "" : `    ${name}: ${JSON.stringify(value)}`;
+}
+function half(name, values) {
+    if (!values)
+        return "";
+    const inside = Object.entries(values).map(function ([key, value]) {
+        if (typeof value === "string")
+            return `        ${key}: ${JSON.stringify(value)}`;
+        const nested = Object.entries(value).map(([nestedKey, nestedValue]) => `            ${nestedKey}: ${JSON.stringify(nestedValue)}`);
+        return `        ${key}: {\n\n${nested.join(",\n\n")}\n        }`;
+    });
+    return `    ${name}: {\n\n${inside.join(",\n\n")}\n    }`;
+}
+function httpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/install.js

@@ -0,0 +1,45 @@
+import derive from "./derive.js";
+import { readConfig } from "./project.js";
+import { dim, heading } from "./style.js";
+import speak from "./program-intake.js";
+import build from "./build-command.js";
+/**
+ * Lay this program out on this machine's system.
+ *
+ * What is sent is the description the config derives — the same one
+ * `phresh start` runs from — and the system copies what it names into
+ * place. A program's parts are already on this disk at the locations it
+ * names, so there is nothing an archive would carry that the description
+ * does not already point at.
+ *
+ * **Installing takes no package, and neither does the system.** A
+ * package is a way of *carrying* a program to another machine, which is
+ * a different act from laying one out — and installing programs at all
+ * is work for a program rather than for the core, so what a person
+ * installs *from* is not this command's business either. `phresh pack`
+ * makes a package when you have somewhere to send it, and stops there.
+ *
+ * When the author config declares `buildCommand`, it runs here before the
+ * production Program is derived and sent. The command remains authoring
+ * metadata and never becomes part of the installed Program.
+ *
+ * Installing is not running. A program laid out here stays until
+ * something removes it, and `phresh start` and `phresh dev` are for the
+ * other way a program is used — attached to the terminal that began it,
+ * and gone when that ends.
+ */
+export default async function install(directory = process.cwd()) {
+    const config = await readConfig(directory);
+    await build(config, directory);
+    const program = derive(config, directory, "production");
+    await speak({ word: "install", program }, function (event) {
+        if (event.event !== "installed")
+            return;
+        const said = event.program;
+        heading(`${said.name ?? String(said.identity)}${said.version ? ` ${said.version}` : ""}`, event.replaced ? "reinstalled" : "installed");
+        // What it kept. Every process ended before the installed paths
+        // changed, while storage stayed in its canonical place.
+        if (event.replaced)
+            console.log(`  ${dim("its storage was kept, and its previous processes were ended")}\n`);
+    });
+}

package/dist/launch.js

@@ -0,0 +1,111 @@
+import derive, {} from "./derive.js";
+import { readConfig } from "./project.js";
+import { dim, heading, line } from "./style.js";
+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);
+    if (program.server)
+        line("server", String(program.server.startCommand), place(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)));
+    console.log("");
+    if (clientStartCommand && program.client)
+        await assertClientDevelopmentUrlFree(program.client.location);
+    const clientDevelopment = clientDevelopmentConfig
+        ? startClientDevelopment(clientStartCommand, directory)
+        : null;
+    const controller = new AbortController();
+    let signalled = false;
+    const stopOnSignal = () => {
+        if (signalled)
+            return;
+        signalled = true;
+        controller.abort();
+        void (clientDevelopment?.stop() ?? Promise.resolve()).finally(() => process.exit(130));
+    };
+    // 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;
+    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(`  ${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;
+    }
+    finally {
+        for (const signal of ["SIGINT", "SIGTERM"])
+            process.off(signal, stopOnSignal);
+        await clientDevelopment?.stop();
+    }
+    // Its status is this command's status: whoever ran the program is
+    // owed what the program said on the way out.
+    process.exit(status);
+}
+// A URL as written; a path as the author typed it.
+function place(directory, where) {
+    return /^https?:\/\//i.test(where) ? where : `./${relative(directory, where)}`;
+}