@phreshos/cli 0.1.0

package/dist/pack.js

@@ -0,0 +1,84 @@
+import { readConfig, readManifest } from "./project.js";
+import { existsSync, readFileSync, statSync } 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/` and `icons/` 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, and there
+ * is nothing a staging directory was doing that the archive does not.
+ */
+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`);
+    }
+    // Icons are the program's own affair rather than either half's: a
+    // headless program is shown too. Packaged like a half, and like a
+    // half their place is not the program's to choose.
+    if (config.icons)
+        place(zip, directory, config.icons, "icons");
+    if (config.apiDocs)
+        document(zip, directory, config.apiDocs);
+    zip.addFile("program.json", Buffer.from(JSON.stringify(program(config, version), null, 4) + "\n"));
+    const archive = `${config.identity}@${version ?? "0.0.0"}.zip`;
+    zip.writeZip(resolve(directory, archive));
+    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,
+        apiDocs: config.apiDocs ? "api-docs.md" : undefined,
+        ...config.server && { server: { location: "server", start: config.server.start, installCommand: config.server.installCommand, startCommand: config.server.startCommand } },
+        ...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 } }
+    };
+}
+// 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 document(zip, directory, location) {
+    const from = resolve(directory, location);
+    if (!existsSync(from) || !statSync(from).isFile())
+        throw new Error(`The API documentation file is not at ${location}`);
+    zip.addFile("api-docs.md", readFileSync(from));
+}

package/dist/program-intake.js

@@ -0,0 +1,65 @@
+import { connect } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * The local Program intake, from the CLI's side.
+ *
+ * A socket file rather than a port, because the file's permissions are
+ * the authorization: only the account that owns this machine can open
+ * it, and that account is exactly who may run and install programs on
+ * it. Nothing is sent to prove anything, because being able to connect
+ * is the proof.
+ *
+ * A message is a line. Closing our own side to mark the end of a
+ * question would make lifetime ambiguous. A line delimiter keeps the
+ * connection available for the stream of events that follows a launch.
+ *
+ * One question, then events until the system closes. Installing and
+ * uninstalling say one thing and end; running says one thing, then whatever
+ * the Program says, then how it ended. None pretends to be a remote method
+ * returning through an unrelated transport.
+ */
+export const socketPath = join(homedir(), ".phreshos", "intake.sock");
+export default function speak(question, heard, path = socketPath, signal) {
+    return new Promise(function (settle, refuse) {
+        const socket = connect(path);
+        let said = "";
+        let failed = null;
+        let aborted = false;
+        const abort = () => {
+            aborted = true;
+            socket.destroy();
+        };
+        if (signal?.aborted)
+            abort();
+        else
+            signal?.addEventListener("abort", abort, { once: true });
+        socket.on("connect", () => socket.write(JSON.stringify(question) + "\n"));
+        socket.on("data", function (chunk) {
+            said += String(chunk);
+            const lines = said.split("\n");
+            said = lines.pop() ?? "";
+            for (const line of lines)
+                if (line.trim()) {
+                    const event = JSON.parse(line);
+                    if (event.event === "error")
+                        failed = new Error(String(event.message));
+                    else
+                        heard(event);
+                }
+        });
+        // The system is not running, or is running as somebody else. Said
+        // plainly, because "ENOENT" is not what went wrong from here.
+        socket.on("error", () => { if (!aborted)
+            refuse(new Error(`No system is listening at ${path} — start one, or check that it is yours`)); });
+        socket.on("close", () => {
+            signal?.removeEventListener("abort", abort);
+            if (aborted)
+                refuse(new Error("The attached launch was stopped"));
+            else if (failed)
+                refuse(failed);
+            else
+                settle();
+        });
+    });
+}

package/dist/project-dependency.js

@@ -0,0 +1,83 @@
+import { line } from "./style.js";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/** Returns the package-manager command that runs one project script. */
+export function projectScript(directory, declared, script) {
+    return `${packageManager(directory, declared).name} run ${script}`;
+}
+/**
+ * Ensures one development dependency using the source appropriate to this CLI.
+ *
+ * A CLI running from this repository uses its sibling dev-kit, so Program
+ * authoring can be exercised before anything is published. An installed CLI
+ * has no such sibling and names the matching registry version instead. This
+ * decision belongs here once for both `init` and the future `create` command.
+ */
+export default async function ensureProjectDependency(name, version, directory = process.cwd()) {
+    const manifestPath = resolve(directory, "package.json");
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    if (manifest.dependencies?.[name] || manifest.devDependencies?.[name])
+        return;
+    const manager = packageManager(directory, manifest.packageManager);
+    const source = packageSource(name, version);
+    line("dependency", name, `${manager.name}, ${source.local ? "local dev-kit" : `^${version}`}`);
+    await new Promise(function (settle, refuse) {
+        const child = spawn(manager.name, [...manager.args, source.specifier], {
+            cwd: directory,
+            stdio: "inherit",
+            shell: process.platform === "win32"
+        });
+        child.once("error", error => refuse(new Error(`Could not run ${manager.name}: ${error.message}`)));
+        child.once("exit", function (code, signal) {
+            if (signal)
+                refuse(new Error(`${manager.name} ended on ${signal}`));
+            else if (code !== 0)
+                refuse(new Error(`${manager.name} exited with ${code ?? 0}`));
+            else
+                settle();
+        });
+    });
+    console.log("");
+}
+function packageSource(name, version) {
+    const directory = resolve(import.meta.dirname, "..", "..", localDirectories[name]);
+    const manifest = manifestAt(directory);
+    if (manifest?.name === name && manifest.version === version)
+        return { specifier: directory, local: true };
+    return { specifier: `${name}@^${version}`, local: false };
+}
+function manifestAt(directory) {
+    const path = resolve(directory, "package.json");
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function packageManager(directory, declared) {
+    const named = declared?.split("@")[0];
+    if (named === "bun")
+        return { name: "bun", args: ["add", "--dev"] };
+    if (named === "pnpm")
+        return { name: "pnpm", args: ["add", "--save-dev"] };
+    if (named === "yarn")
+        return { name: "yarn", args: ["add", "--dev"] };
+    if (named === "npm")
+        return { name: "npm", args: ["install", "--save-dev", "--no-fund", "--no-audit"] };
+    if (existsSync(resolve(directory, "bun.lock")) || existsSync(resolve(directory, "bun.lockb")))
+        return { name: "bun", args: ["add", "--dev"] };
+    if (existsSync(resolve(directory, "pnpm-lock.yaml")))
+        return { name: "pnpm", args: ["add", "--save-dev"] };
+    if (existsSync(resolve(directory, "yarn.lock")))
+        return { name: "yarn", args: ["add", "--dev"] };
+    return { name: "npm", args: ["install", "--save-dev", "--no-fund", "--no-audit"] };
+}
+const localDirectories = {
+    "@phreshos/core": "core-sdk",
+    "@phreshos/client": "client-sdk",
+    "@phreshos/server": "server-sdk"
+};

package/dist/project.js

@@ -0,0 +1,125 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { layers } from "@phreshos/core";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isRelativeValue } from "./relative-value.js";
+export const configFile = "phresh.config.ts";
+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`);
+    // The supported Node runtime reads erasable TypeScript directly. Keeping
+    // this file typed gives an author editor assistance without another config
+    // format or a build step.
+    const loaded = await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)).catch(function (error) {
+        throw new Error(`${configFile} could not be read (${error.message})`);
+    });
+    const config = loaded.default;
+    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", "icons"]) {
+        if (config[field] !== undefined && typeof config[field] !== "string")
+            throw new Error(`A program's ${field} must be text`);
+    }
+    if (config.apiDocs !== undefined && (typeof config.apiDocs !== "string" || config.apiDocs.trim().length === 0))
+        throw new Error("A program's apiDocs must be a non-empty path");
+    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 && (typeof config.server.startCommand !== "string" || config.server.startCommand.length === 0))
+        throw new Error("A server half must say what starts it");
+    if (config.server?.installCommand !== undefined && typeof config.server.installCommand !== "string")
+        throw new Error("A server half's install 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 && (typeof serverDevelopment.startCommand !== "string" || serverDevelopment.startCommand.trim().length === 0))
+        throw new Error("server.development.startCommand must be non-empty text");
+    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 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))
+        throw new Error("package.json must have a kebab-case name");
+    return manifest;
+}

package/dist/relative-value.js

@@ -0,0 +1,118 @@
+/**
+ * Reduces a strict linear expression into `span * relative + pixels`.
+ *
+ * Numbers are absolute values. Percentages and `n/d` fractions are relative
+ * values. Addition and subtraction combine terms; multiplication and division
+ * scale the preceding term by a number. No arbitrary code or CSS is accepted.
+ */
+export function parseRelativeValue(input) {
+    if (typeof input === "number")
+        return Number.isFinite(input) ? { relative: 0, pixels: clean(input) } : null;
+    if (typeof input !== "string" || input.trim().length === 0)
+        return null;
+    return new Reader(input).parse();
+}
+/** Returns whether a value belongs to the linear relative-value grammar. */
+export function isRelativeValue(value) {
+    return parseRelativeValue(value) !== null;
+}
+class Reader {
+    position = 0;
+    source;
+    constructor(source) {
+        this.source = source;
+    }
+    parse() {
+        const value = { relative: 0, pixels: 0 };
+        let direction = this.sign();
+        while (this.position < this.source.length) {
+            const term = this.term();
+            if (!term)
+                return null;
+            value.relative += term.relative * direction;
+            value.pixels += term.pixels * direction;
+            if (!finite(value))
+                return null;
+            this.space();
+            if (this.position === this.source.length)
+                return { relative: clean(value.relative), pixels: clean(value.pixels) };
+            const operator = this.source[this.position];
+            if (operator !== "+" && operator !== "-")
+                return null;
+            this.position += 1;
+            direction = (operator === "+" ? 1 : -1) * this.sign();
+        }
+        return null;
+    }
+    term() {
+        const value = this.measurement();
+        if (!value)
+            return null;
+        while (true) {
+            this.space();
+            const operator = this.source[this.position];
+            if (operator !== "*" && operator !== "/")
+                return value;
+            this.position += 1;
+            const scalar = this.scalar();
+            if (scalar === null || operator === "/" && scalar === 0)
+                return null;
+            const factor = operator === "*" ? scalar : 1 / scalar;
+            value.relative *= factor;
+            value.pixels *= factor;
+            if (!finite(value))
+                return null;
+        }
+    }
+    measurement() {
+        this.space();
+        const remainder = this.source.slice(this.position);
+        const fraction = remainder.match(/^(\d+(?:\.\d+)?|\.\d+)\s*\/\s*(\d+(?:\.\d+)?|\.\d+)(?![\d.])/);
+        if (fraction) {
+            const denominator = Number(fraction[2]);
+            if (!denominator)
+                return null;
+            this.position += fraction[0].length;
+            return { relative: Number(fraction[1]) / denominator, pixels: 0 };
+        }
+        const percentage = remainder.match(/^(\d+(?:\.\d+)?|\.\d+)\s*%/);
+        if (percentage) {
+            this.position += percentage[0].length;
+            return { relative: Number(percentage[1]) / 100, pixels: 0 };
+        }
+        const number = this.number();
+        return number === null ? null : { relative: 0, pixels: number };
+    }
+    scalar() {
+        const direction = this.sign();
+        const value = this.number();
+        return value === null ? null : value * direction;
+    }
+    number() {
+        this.space();
+        const number = this.source.slice(this.position).match(/^(\d+(?:\.\d+)?|\.\d+)/)?.[0];
+        if (!number)
+            return null;
+        this.position += number.length;
+        return Number(number);
+    }
+    sign() {
+        this.space();
+        const sign = this.source[this.position];
+        if (sign !== "+" && sign !== "-")
+            return 1;
+        this.position += 1;
+        this.space();
+        return sign === "-" ? -1 : 1;
+    }
+    space() {
+        while (/\s/.test(this.source[this.position] ?? ""))
+            this.position += 1;
+    }
+}
+function finite(value) {
+    return Number.isFinite(value.relative) && Number.isFinite(value.pixels);
+}
+function clean(value) {
+    return Object.is(value, -0) ? 0 : value;
+}

package/dist/style.js

@@ -0,0 +1,27 @@
+/**
+ * How every command looks.
+ *
+ * Six escapes rather than a dependency, and nothing at all where a
+ * terminal would print them instead of obeying them. Shared because four
+ * commands speaking three visual languages is worse than any one of
+ * them: a person reading `phresh install` after `phresh init` should not
+ * have to work out that it is the same tool.
+ */
+const colour = process.stdout.isTTY && !process.env.NO_COLOR;
+const escape = String.fromCharCode(27);
+export const dim = (text) => colour ? `${escape}[2m${text}${escape}[22m` : text;
+export const bold = (text) => colour ? `${escape}[1m${text}${escape}[22m` : text;
+// A label, what it says, and where that came from. The label is quiet
+// and the value is not, because the value is the thing being reported.
+//
+// Wide enough for the longest label any command uses, and a space kept
+// even when one overruns: a label that runs into its value is worse than
+// a column that does not line up.
+export function line(label, value, note) {
+    console.log(`  ${dim(label.padEnd(12))}${value}${note ? `  ${dim(note)}` : ""}`);
+}
+export function heading(title, note) {
+    console.log("");
+    console.log(`  ${bold(title)}${note ? `  ${dim("·")}  ${dim(note)}` : ""}`);
+    console.log("");
+}

package/dist/uninstall.js

@@ -0,0 +1,15 @@
+import { readConfig } from "./project.js";
+import { dim, heading } from "./style.js";
+import speak from "./program-intake.js";
+/** Uninstall the Program declared by the current project. */
+export default async function uninstall(everything = false, directory = process.cwd()) {
+    const config = await readConfig(directory);
+    await speak({ word: "uninstall", identity: config.identity, everything }, function (event) {
+        if (event.event !== "uninstalled")
+            return;
+        heading(config.name ?? config.identity, "uninstalled");
+        console.log(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`);
+    });
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+    "name": "@phreshos/cli",
+    "type": "module",
+    "version": "0.1.0",
+    "description": "The Phresh command-line interface for Program projects and system management.",
+    "scripts": {
+        "build": "tsc --noEmit false --outDir dist --rootDir source --rewriteRelativeImportExtensions true --allowImportingTsExtensions true",
+        "prepack": "node --run build"
+    },
+    "bin": {
+        "phresh": "dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "dependencies": {
+        "@phreshos/core": "0.1.0",
+        "adm-zip": "^0.6.0"
+    },
+    "devDependencies": {
+        "@types/adm-zip": "^0.5.8",
+        "@types/node": "^25.9.5",
+        "typescript": "^6.0.3"
+    }
+}