@phreshos/cli 0.1.0

package/README.md

@@ -0,0 +1,341 @@
+# @phreshos/cli
+
+The `phresh` command for creating, running, packaging, installing, and
+uninstalling Programs.
+
+## Package status
+
+This package is one component of a larger architecture that is still under
+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.
+
+```bash
+phresh init     # describe this program, once
+phresh pack     # run the optional build, then package its result
+phresh install  # lay this program out on this machine
+phresh uninstall # remove its installed form
+phresh start    # run what your build left, and stay with it
+phresh dev      # run from source, and stay with it
+```
+
+`phresh --help` lists them, `phresh <command> --help` explains one, and
+`phresh --version` says which CLI you have. Nothing is guessed: an
+unknown command, an unknown flag and a malformed option are each refused
+and named.
+
+**This tool acts on the current project, and the list ends there.** It is
+not the machine's control panel — it accepts no arbitrary program identity
+and has no word for a process, a window, a store or a setting. The system's
+local intake accepts exactly the Program this project declares, and so does
+this tool.
+
+## Saying something to a program you start
+
+```bash
+phresh dev --run-option-path=/notes.md --run-option-line=42
+```
+
+Read back by name, on either half:
+
+```ts
+const path = await current.option("path")
+```
+
+**Options are text, all of them.** An option must mean the same thing
+however the process was started, and a command line can only hand over
+text — a number made here would be a guess about your program's meaning
+by the one party with no way to know it. Is `--run-option-id=007` seven,
+or a string with two noughts in front? Only your program knows, so your
+program decides: `Number(...)`, once, where the meaning is.
+
+Which is what argv and the environment have always been, for the same
+reason. The prefix is long because these share a line with the tool's
+own flags, and a program wanting an option called `client` should not
+have to fight the CLI for the word.
+
+## phresh.config is not a program's configuration
+
+A program's configuration is **derived** from it — three times, and the
+derivations differ only in where each half is said to be. That is the
+rule everything else here follows from.
+
+It follows that every field which lands in a `program.json` is spelled
+the way the contract spells it and crosses untouched: `size`, not a
+width and a height; `startCommand`, not a command.
+
+An optional top-level `buildCommand` is authoring metadata. `phresh start`,
+`phresh install`, and `phresh pack` run it from this project before consuming
+the production files. It never crosses into `program.json` or the system.
+`phresh dev` uses the development declarations and does not build.
+
+Everything else is yours: where each half is left.
+
+```ts
+import { defineConfig } from "@phreshos/core"
+
+export default defineConfig({
+
+    identity: "file-manager",      // kebab-case: the program's stable address
+
+    name: "File Manager",          // what a person reads
+
+    version: "0.1.0",
+
+    description: "A file manager",
+
+    apiDocs: "api.md",
+
+    icons: "icons",
+
+    buildCommand: "bun run build",
+
+    server: {
+
+        location: "build/server",
+
+        installCommand: "npm ci",
+
+        startCommand: "node main.js",
+
+        development: {
+
+            startCommand: "tsx server/main.ts"
+        }
+    },
+
+    client: {
+
+        location: "dist",
+
+        size: { width: "1/2", height: 440 },
+
+        position: { x: 60, y: 40 },
+
+        development: {
+
+            url: "http://localhost:5173",
+
+            startCommand: "bun run dev"
+        }
+    }
+})
+```
+
+**`identity` identifies; `name` is read.** The identity is kebab-case
+because it is also the directory the system lays your program out in, so
+it is a path component before anything else. The name is free-form,
+identifies nothing, and absent means the identity serves for both.
+
+`identity`, `version` and `description` begin from your `package.json`
+during `init`; the readable `name` is asked for. They are written into
+the config rather than read from the manifest later. `pack` says so if
+the two versions have drifted apart.
+
+A window's `size` and `position` are finite pixel numbers or linear
+expressions. Fractions and percentages are equivalent relative terms, so
+`"1/2"` and `"50%"` mean the same thing; pixel offsets may be combined with
+them, as in `"50% + 10"`. Every value survives derivation unchanged.
+
+## development — what `phresh dev` needs
+
+`phresh init` offers to configure development for each declared half. It uses
+the project's `dev` script as a suggested command when one exists, but records
+nothing unless the author chooses it. If development is left unconfigured,
+`phresh dev` refuses and names the declarations it needs:
+
+```
+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" } }
+```
+
+Each half may carry a `development` block, but the two shapes are deliberately
+different. A server block requires `startCommand`; `phresh dev` runs it from the
+directory containing `phresh.config.ts`, and that directory becomes the derived
+server location. A client block requires an HTTP(S) `url`; development clients
+are never resolved from filesystem paths.
+
+The client development shape may also declare `startCommand`. `phresh dev`
+runs it from the project directory as a foreground development tool; the
+command is never derived into the Program sent to the system. The tool and
+the attached Program share one lifetime, so ending either ends the other.
+
+Before launching the Program, `phresh dev` waits up to 15 seconds for the client
+development URL to respond. While it remains unavailable, the URL is printed
+every two seconds. A command that exits first is reported immediately. This
+means the window is never deliberately opened onto a client that the authoring
+tool already knows is unavailable.
+
+## init
+
+`phresh init` turns an existing package into a Program project. It reads the
+identity, version, and description from `package.json`, ensures the project has
+the matching `@phreshos/core` development dependency, and writes the typed
+`phresh.config.ts` authoring description.
+
+In a terminal, `init` asks for the production locations and commands needed by
+`start` and `install`, including whether a package build should prepare those
+locations. It then offers the development command and URL needed by `dev`.
+Existing `build` and `dev` package scripts become editable suggestions, never
+silent assumptions.
+
+Outside a terminal it never waits for input; the same values are supplied as
+named options:
+
+```bash
+phresh init --client \
+    --client-location dist \
+    --build-command "bun run build" \
+    --client-development-url http://localhost:5173 \
+    --client-development-start-command "bun run dev"
+
+phresh init --server \
+    --server-location build/server \
+    --server-start-command "node main.js"
+```
+
+Use `phresh init --help` for the complete option list. An existing config is
+never replaced silently: a terminal asks, while automation must say `--force`.
+
+A program must have a server half, a client half, or both. Neither is
+refused during the interview rather than at the border, which is the
+earliest place it can be refused.
+
+The final `Next` line is derived from the resulting config. It always shows
+`phresh start` and `phresh install`; it shows `phresh dev` only when at least
+one half received a development declaration.
+
+Visual and advanced runtime defaults remain for the author to add deliberately:
+`icons`, `size`, `position`, `installCommand`, `start`, layers, and minimization
+are not guessed. An omitted `start` is `true`; only a default-off half needs to
+say `start: false`.
+
+## start and dev
+
+Both **run your program without installing it, and stay attached.** They
+print the `program.json` it will be declared as, hand that to the system
+through the socket it listens on — `~/.phreshos/intake.sock`, which only
+your account can open, so nothing is sent to prove anything — and then
+hold.
+
+**The connection is the tether, in both directions.** Ctrl-C and your
+program stops. Close the window it opened and the command returns, with
+your program's own exit status as its own. Its `stdout` and `stderr`
+arrive in your terminal as well as its system log. The system always
+drains a server process; attachment adds the terminal as an audience
+rather than changing how the process starts.
+
+Nothing has to promise to clean up, which is the point — a promise would
+not survive `kill -9`, a closed terminal, or a dropped ssh session. All
+three end the command without running a line of it, and all three still
+close the socket, which is what the system is watching.
+
+**Attached means not installed; installed means persistent.** A program
+meant to outlive your terminal is installed rather than run.
+
+The run is registered as an ordinary uninstalled Program under the identity
+declared by this project. Before registration, the system ends and forgets any
+runtime Program already using that identity, whether it was installed or
+uninstalled. Forgetting never uninstalls: installed files and storage remain
+untouched while the attached Program becomes the sole runtime occupant. Its
+root process tethers the whole Program to this command; when it exits, remaining
+processes end and the runtime record disappears. A later `phresh install` can
+replace the preserved installed files and immediately register the identity as
+installed again. If no system is listening, the intake says so plainly rather
+than exposing `ENOENT`.
+
+An attached Program still owns persistent project storage. The authoring tool
+declares `<project>/storage` explicitly, so `start` and `dev` keep the same
+database, store, data, cache, and logs as any other runtime form without
+inventing a path from the system's working directory. Installation changes
+where Program files are laid out; it does not change the logging contract.
+
+They are one derivation over one config, differing only in where each
+half is said to be:
+
+| | locations from | derived form |
+|---|---|---|
+| `pack` | `location` | none — the system lays an installed program out |
+| `start` | `location` | absolute |
+| `dev` | project root for a declared server development block; `development.url` for a declared client block | server absolute, client URL |
+
+Every derived filesystem path is absolute because relative paths resolve
+against the `program.json` they were read from, and a derived one does not live
+beside your source. A client development URL remains the URL the author wrote.
+
+## install
+
+**A program has two ways of being used: run it, or install it.**
+
+```bash
+phresh install   # this project, laid out on this machine
+```
+
+**It takes no package, and neither does the system.** What is sent is
+the description this directory derives, and the system copies what it
+names into place — your 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. `phresh pack` is for when you have
+somewhere to send a program; installing here is a different act.
+
+If `buildCommand` is declared, it completes successfully before anything is
+sent to the system. Without it, install uses the production files exactly as
+they stand.
+
+Installing is the persistent one — laid out under `~/.phreshos/programs/<identity>`,
+marked installed, and reconstructed after a restart. Running is the other one:
+`phresh start` / `phresh dev` register it under its declared identity and
+attach its whole lifetime to your terminal.
+
+The command installs through the machine's local intake. A running
+Program may also install itself through the server SDK; installation is not a
+client capability.
+
+That is also why it names **paths** rather than sending bytes: install
+used to want an upload because the installer was a browser, which has
+bytes and no path. You have the paths.
+
+## uninstall
+
+```bash
+phresh uninstall
+phresh uninstall --everything
+```
+
+Ordinary uninstall removes the installed Program files while preserving its
+running Processes, stored data, and runtime Program. `--everything` explicitly
+ends those Processes, removes everything the system owns for the Program, and
+forgets its runtime record.
+
+The identity comes from this project's `phresh.config.ts`; the command does not
+accept an arbitrary Program identity.
+
+## What pack produces
+
+`pack` takes what is at each half's `location` and writes
+`<identity>@<version>.zip`. Your program may leave its halves anywhere; the
+package always keeps them in the same places, so the artifact's shape
+belongs to the contract rather than to your project. That is why the
+`program.json` it writes names `server` and `client` explicitly — those
+are the canonical locations the package just created. An explicit
+`start: false` crosses with its half; an omitted value remains omitted
+and means `true`. At least one declared half must resolve to true.
+
+When `apiDocs` is declared, its Markdown file is copied to `api-docs.md` and
+the packaged description names that canonical entry point. A missing declared
+file is an error, not an undocumented Program.
+
+There is **no wrapping directory**: `program.json`, `server/`, `client/`
+`icons/`, and optional `api-docs.md` sit at the package's root, and the system names the
+directory it installs into from your program's `identity`.
+
+Nothing about the system moves because this exists. `program.json` is
+still the only thing the system reads, and a package assembled by hand
+is still a package. This just means you do not have to.

package/dist/attach.js

@@ -0,0 +1,29 @@
+import speak, { socketPath } from "./program-intake.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 = socketPath, signal) {
+    let ended = null;
+    await speak({ 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

@@ -0,0 +1,22 @@
+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/cli.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { bold, dim, heading } from "./style.js";
+import metadata from "../package.json" with { type: "json" };
+import install from "./install.js";
+import launch from "./launch.js";
+import init from "./init.js";
+import pack from "./pack.js";
+import uninstall from "./uninstall.js";
+const { version } = metadata;
+/**
+ * One command system.
+ *
+ * Every command declares its options beside its help and all of them pass
+ * through the same parser, error presentation, and exit rules. Interactive
+ * behavior belongs to the command that needs it; parsing never guesses.
+ */
+const commands = [
+    {
+        name: "init",
+        summary: "initialize an existing Program project",
+        detail: [
+            "Reads identity, version, and description from package.json, then",
+            "writes phresh.config.ts. In a terminal it asks only for the Program",
+            "shape and values package.json cannot provide.",
+            "",
+            "Without a terminal, declare at least one half with named options.",
+            "No prompt is opened and no input is awaited."
+        ],
+        options: [
+            { name: "name", value: "name", summary: "human-readable Program name" },
+            { name: "api-docs", value: "path", summary: "official Program API documentation" },
+            { name: "build-command", value: "command", summary: "prepare production files before use" },
+            { name: "server", summary: "include a server half" },
+            { name: "server-location", value: "path", summary: "production server directory" },
+            { name: "server-start-command", value: "command", summary: "production server command" },
+            { name: "server-development-start-command", value: "command", summary: "development server command" },
+            { name: "client", summary: "include a client half" },
+            { name: "client-location", value: "path", summary: "production client directory" },
+            { name: "client-development-url", value: "url", summary: "development client URL" },
+            { name: "client-development-start-command", value: "command", summary: "client development command" },
+            { name: "force", summary: "replace an existing phresh.config.ts" }
+        ],
+        run: options => init({
+            name: text(options, "name"),
+            apiDocs: text(options, "api-docs"),
+            buildCommand: text(options, "build-command"),
+            server: options.server === true || text(options, "server-location") !== undefined || text(options, "server-start-command") !== undefined,
+            serverLocation: text(options, "server-location"),
+            serverStartCommand: text(options, "server-start-command"),
+            serverDevelopmentStartCommand: text(options, "server-development-start-command"),
+            client: options.client === true || text(options, "client-location") !== undefined,
+            clientLocation: text(options, "client-location"),
+            clientDevelopmentUrl: text(options, "client-development-url"),
+            clientDevelopmentStartCommand: text(options, "client-development-start-command"),
+            force: options.force === true
+        }, process.cwd(), version)
+    },
+    {
+        name: "pack",
+        summary: "build and package this Program",
+        detail: [
+            "Runs an optional buildCommand, then assembles each half from where",
+            "the config says the production files are.",
+            "",
+            "A package carries a Program to another machine. Installing this",
+            "project takes no package because its description already names the",
+            "files on this machine."
+        ],
+        run: () => pack()
+    },
+    {
+        name: "install",
+        summary: "install this Program",
+        detail: [
+            "Builds and lays out the Program declared by this project.",
+            "",
+            "Running processes end before installed paths change. Program data is",
+            "preserved."
+        ],
+        run: () => install()
+    },
+    {
+        name: "uninstall",
+        summary: "uninstall this Program",
+        detail: [
+            "Removes the installed Program files. Its running processes, stored",
+            "data, and runtime Program remain available.",
+            "",
+            "--everything ends its processes, removes everything the system owns",
+            "for it, and forgets the runtime Program."
+        ],
+        options: [
+            { name: "everything", summary: "also remove processes, data, and runtime state" }
+        ],
+        run: options => uninstall(options.everything === true)
+    },
+    {
+        name: "start",
+        summary: "run the production Program without installing",
+        detail: [
+            "Runs this Program attached to the terminal. Its output arrives here,",
+            "and when this command ends the system stops the Program.",
+            "",
+            "An optional buildCommand runs before the production Program starts.",
+            "The Program's exit status becomes this command's exit status."
+        ],
+        runOptions: true,
+        run: options => launch("production", process.cwd(), options.run)
+    },
+    {
+        name: "dev",
+        summary: "run the development Program without installing",
+        detail: [
+            "Runs the same attached lifecycle as start, using each half's",
+            "development declaration.",
+            "",
+            "A declared client development command belongs to this session. Its",
+            "URL must respond within 15 seconds before the Program launches."
+        ],
+        runOptions: true,
+        run: options => launch("development", process.cwd(), options.run)
+    }
+];
+const runOptionPrefix = "--run-option-";
+const [asked = "", ...rest] = process.argv.slice(2);
+if (asked === "--version" || asked === "-v") {
+    console.log(version);
+    process.exit(0);
+}
+const wanted = commands.find(command => command.name === asked);
+if (!asked || asked === "--help" || asked === "-h") {
+    usage();
+    process.exit(0);
+}
+if (!wanted) {
+    console.error(`\n  phresh: no such command "${asked}"`);
+    usage();
+    process.exit(1);
+}
+if (rest.includes("--help") || rest.includes("-h")) {
+    about(wanted);
+    process.exit(0);
+}
+try {
+    await wanted.run(parse(wanted, rest));
+}
+catch (error) {
+    console.error(`\n  phresh: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+}
+function parse(command, args) {
+    const options = { run: {} };
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (command.runOptions && argument.startsWith(runOptionPrefix)) {
+            const said = argument.slice(runOptionPrefix.length);
+            const at = said.indexOf("=");
+            if (at < 1)
+                throw new Error(`"${argument}" says no value — write ${runOptionPrefix}<name>=<value>, and end with = for an empty value`);
+            const name = said.slice(0, at);
+            if (Object.hasOwn(options.run, name))
+                throw new Error(`The run option "${name}" was given more than once`);
+            options.run[name] = said.slice(at + 1);
+            continue;
+        }
+        if (!argument.startsWith("--"))
+            throw new Error(`${command.name} takes no positional arguments, and I was given "${argument}"`);
+        const at = argument.indexOf("=");
+        const name = argument.slice(2, at < 0 ? undefined : at);
+        const declared = command.options?.find(option => option.name === name);
+        if (!declared)
+            throw new Error(`${command.name} does not know the option "--${name}"`);
+        if (Object.hasOwn(options, name))
+            throw new Error(`The option "--${name}" was given more than once`);
+        if (!declared.value) {
+            if (at >= 0)
+                throw new Error(`--${name} does not take a value`);
+            options[name] = true;
+            continue;
+        }
+        const value = at >= 0 ? argument.slice(at + 1) : args[++index];
+        if (value === undefined || at < 0 && value.startsWith("--"))
+            throw new Error(`--${name} needs <${declared.value}>`);
+        options[name] = value;
+    }
+    return options;
+}
+function text(options, name) {
+    const value = options[name];
+    return typeof value === "string" ? value : undefined;
+}
+function usage() {
+    heading(`phresh ${version}`, "create and manage Programs");
+    for (const command of commands)
+        console.log(`  ${bold(command.name.padEnd(12))}${command.summary}`);
+    console.log("");
+    console.log(`  ${dim("phresh <command> --help".padEnd(32))}${dim("show one command in detail")}`);
+    console.log("");
+}
+function about(command) {
+    heading(`phresh ${command.name}${command.options?.length || command.runOptions ? " [options]" : ""}`, command.summary);
+    for (const said of command.detail)
+        console.log(said ? `  ${said}` : "");
+    if (command.options?.length || command.runOptions) {
+        console.log("");
+        console.log(`  ${bold("Options")}`);
+        console.log("");
+        const signatures = (command.options ?? []).map(option => `--${option.name}${option.value ? ` <${option.value}>` : ""}`);
+        if (command.runOptions)
+            signatures.push(runOptionPrefix + "<name>=<value>");
+        const width = Math.max(34, ...signatures.map(signature => signature.length + 2));
+        for (const option of command.options ?? []) {
+            const signature = `--${option.name}${option.value ? ` <${option.value}>` : ""}`;
+            console.log(`  ${signature.padEnd(width)}${dim(option.summary)}`);
+        }
+        if (command.runOptions)
+            console.log(`  ${(runOptionPrefix + "<name>=<value>").padEnd(width)}${dim("pass text to the launched Program")}`);
+    }
+    console.log("");
+}