@phreshos/cli 0.1.3 → 0.1.5

package/README.md

@@ -14,6 +14,7 @@ Its Program commands depend on `@phreshos/core`, and its runtime operations
 require a compatible system installation.
 
 ```bash
+phresh create app # create a complete new Program
 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
@@ -33,6 +34,33 @@ 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.
 
+## create
+
+`phresh create <directory>` creates a complete Server and Client Program from
+the maintained `PhreshOS/phresh-program` repository. The CLI build downloads
+one exact tagged source release, verifies its SHA-256 checksum, removes
+repository-only material, and bundles the resulting authoring project. The
+installed CLI therefore creates projects offline without reading a live branch
+or maintaining a second template by hand.
+
+The directory name becomes the stable kebab-case Program identity. In a
+terminal, `create` asks for the directory when it is omitted, the readable
+Program name, and the package manager. With no terminal, the directory is the
+first argument and every optional choice is named:
+
+```bash
+phresh create status-board \
+    --name "Status Board" \
+    --package-manager npm
+```
+
+Dependencies are installed by default. `--no-install` creates the same valid
+project and leaves installation as the first reported next step. A project
+created inside this repository's workspace uses its sibling dev-kits through
+the workspace protocol. A standalone project, including one created by a
+distributed CLI, uses the published versions embedded in the template. Both
+choices pass through the same dependency resolver used by `init`.
+
 ## Saying something to a program you start
 
 ```bash
@@ -89,7 +117,7 @@ export default defineConfig({
 
     apiDocs: "api.md",
 
-    icons: "icons",
+    icon: "icon.png",
 
     buildCommand: "bun run build",
 
@@ -184,7 +212,9 @@ 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.
+silent assumptions. A single Endpoint defaults to `dist`; when both Endpoints
+exist, their defaults are `dist/server` and `dist/client`. API documentation is
+opt-in and defaults to disabled even when a likely document already exists.
 
 Outside a terminal it never waits for input; the same values are supplied as
 named options:
@@ -197,7 +227,7 @@ phresh init --client \
     --client-development-start-command "bun run dev"
 
 phresh init --server \
-    --server-location build/server \
+    --server-location dist \
     --server-start-command "node main.js"
 ```
 
@@ -213,7 +243,7 @@ The final `Next` line is derived from the resulting config. It always shows
 one Endpoint received a development declaration.
 
 Visual and advanced runtime defaults remain for the author to add deliberately:
-`icons`, `size`, `position`, `installCommand`, `start`, layers, and minimization
+`icon`, `size`, `position`, `installCommand`, `start`, layers, and minimization
 are not guessed. An omitted `start` is `true`; only a default-off Endpoint needs to
 say `start: false`.
 
@@ -221,9 +251,12 @@ say `start: false`.
 
 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.
+through the socket below the selected system home. With no override, that is
+`~/.phreshos/intake.sock`. Set `PHRESHOS_HOME` to an absolute system home to
+address another system instance; the CLI derives
+`<PHRESHOS_HOME>/intake.sock` from it. The socket is not selected
+separately from its instance. Only your account can open it, so nothing is
+sent to prove anything, and then the command holds.
 
 **The connection is the tether, in both directions.** Ctrl-C and your
 program stops. Close the window it opened and the command returns, with
@@ -339,8 +372,8 @@ register a subscription. Those are system contracts documented once by the
 SDKs; `api-docs.md` supplies only the Program-specific meaning carried through
 them.
 
-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
+There is **no wrapping directory**: `program.json`, `server/`, `client/`,
+optional `icon.png`, 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

package/dist/build-template.js

@@ -0,0 +1,90 @@
+import metadata from "../package.json" with { type: "json" };
+import { createHash } from "node:crypto";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import AdmZip from "adm-zip";
+import { readConfig } from "./project.js";
+const repository = "PhreshOS/phresh-program";
+const release = {
+    version: "0.1.0",
+    sha256: "6e1a87a037a6ac5f82ff4c7d420757f972098387d73a8b4165aab2ef331cec36"
+};
+const archiveUrl = `https://github.com/${repository}/archive/refs/tags/v${release.version}.zip`;
+const output = resolve(import.meta.dirname, "template");
+const descriptionOutput = resolve(import.meta.dirname, "template.json");
+const excludedDirectories = new Set([".github", "dist", "node_modules", "scripts", "storage"]);
+const excludedRootFiles = new Set(["CONTRIBUTING.md", "LICENSE", "SECURITY.md"]);
+const excludedFiles = new Set([
+    ".DS_Store",
+    "bun.lock",
+    "bun.lockb",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock"
+]);
+const response = await fetch(archiveUrl);
+if (!response.ok)
+    throw new Error(`Could not download ${repository} v${release.version}: ${response.status} ${response.statusText}`);
+const bytes = Buffer.from(await response.arrayBuffer());
+const digest = createHash("sha256").update(bytes).digest("hex");
+if (digest !== release.sha256)
+    throw new Error(`The ${repository} v${release.version} source archive failed integrity verification`);
+const archive = new AdmZip(bytes);
+const entries = archive.getEntries();
+const roots = new Set(entries.map(entry => entry.entryName.split("/")[0]).filter(Boolean));
+if (roots.size !== 1)
+    throw new Error(`The ${repository} v${release.version} source archive has an invalid root`);
+const root = [...roots][0];
+rmSync(output, { recursive: true, force: true });
+rmSync(descriptionOutput, { force: true });
+for (const entry of entries) {
+    if (entry.isDirectory || !entry.entryName.startsWith(`${root}/`))
+        continue;
+    const local = entry.entryName.slice(root.length + 1);
+    if (!included(local))
+        continue;
+    const target = local === ".gitignore" ? "gitignore" : local;
+    const path = resolve(output, target);
+    if (!path.startsWith(`${output}${sep}`))
+        throw new Error(`The ${repository} source archive contains an unsafe path: ${local}`);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, entry.getData());
+}
+const manifestPath = resolve(output, "package.json");
+const manifestSource = archive.readFile(`${root}/package.json`);
+if (!manifestSource)
+    throw new Error(`The ${repository} v${release.version} source archive has no package.json`);
+const manifest = JSON.parse(manifestSource.toString("utf8"));
+manifest.scripts = select(manifest.scripts, ["dev", "start"]);
+manifest.devDependencies = {
+    ...manifest.devDependencies,
+    "@phreshos/cli": `^${metadata.version}`
+};
+delete manifest.author;
+delete manifest.license;
+delete manifest.repository;
+delete manifest.bugs;
+delete manifest.homepage;
+delete manifest.packageManager;
+writeFileSync(manifestPath, JSON.stringify(manifest, null, 4) + "\n");
+const config = await readConfig(output);
+if (config.identity !== "phresh-program" || config.name !== "Phresh Program")
+    throw new Error(`The ${repository} release is not Phresh Program`);
+writeFileSync(descriptionOutput, JSON.stringify({
+    repository,
+    version: release.version,
+    development: Boolean(config.server?.development || config.client?.development)
+}, null, 4) + "\n");
+function included(local) {
+    const parts = local.split("/");
+    if (parts.some(part => excludedDirectories.has(part)))
+        return false;
+    if (parts.length === 1 && excludedRootFiles.has(local))
+        return false;
+    if (excludedFiles.has(parts.at(-1)))
+        return false;
+    return !local.endsWith(".zip");
+}
+function select(source, names) {
+    return Object.fromEntries(names.flatMap(name => source?.[name] === undefined ? [] : [[name, source[name]]]));
+}

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
-import { bold, dim, heading } from "./style.js";
+import { Command, Option } from "commander";
 import metadata from "../package.json" with { type: "json" };
+import { PromptCancelled } from "./prompts.js";
+import create from "./create.js";
 import install from "./install.js";
 import launch from "./launch.js";
 import init from "./init.js";
@@ -8,214 +10,144 @@ import pack from "./pack.js";
 import uninstall from "./uninstall.js";
 const { version } = metadata;
 const coreRange = metadata.dependencies["@phreshos/core"];
-/**
- * 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(), coreRange)
-    },
-    {
-        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);
-}
+const program = new Command()
+    .name("phresh")
+    .description("Create and manage Programs")
+    .version(version, "-v, --version")
+    .showHelpAfterError()
+    .showSuggestionAfterError();
+program.addHelpText("after", "\nRun phresh <command> --help for detailed command guidance.\n");
+describe(program.command("create")
+    .description("create a new Program project")
+    .argument("[directory]", "directory for the new Program")
+    .option("--name <name>", "human-readable Program name")
+    .addOption(new Option("--package-manager <manager>", "package manager used to install dependencies").choices(["bun", "npm", "pnpm", "yarn"]))
+    .option("--no-install", "create files without installing dependencies")
+    .action(async function (directory, options) {
+    await create({
+        directory,
+        name: options.name,
+        packageManager: options.packageManager,
+        install: options.install
+    });
+}), [
+    "Creates a complete Server and Client project from the maintained",
+    "Phresh Program template bundled with this CLI.",
+    "",
+    "In a terminal, omitted values are collected interactively. Automation",
+    "supplies the directory and optional choices through named options."
+]);
+describe(program.command("init")
+    .description("initialize an existing Program project")
+    .option("--name <name>", "human-readable Program name")
+    .option("--api-docs <path>", "official Program API documentation")
+    .option("--build-command <command>", "prepare production files before use")
+    .option("--server", "include a Server endpoint")
+    .option("--server-location <path>", "production Server directory")
+    .option("--server-start-command <command>", "production Server command")
+    .option("--server-development-start-command <command>", "development Server command")
+    .option("--client", "include a Client endpoint")
+    .option("--client-location <path>", "production Client directory")
+    .option("--client-development-url <url>", "development Client URL")
+    .option("--client-development-start-command <command>", "development Client command")
+    .option("--force", "replace an existing phresh.config.ts")
+    .action(async function (options) {
+    await init({
+        name: options.name,
+        apiDocs: options.apiDocs,
+        buildCommand: options.buildCommand,
+        server: options.server === true || options.serverLocation !== undefined || options.serverStartCommand !== undefined,
+        serverLocation: options.serverLocation,
+        serverStartCommand: options.serverStartCommand,
+        serverDevelopmentStartCommand: options.serverDevelopmentStartCommand,
+        client: options.client === true || options.clientLocation !== undefined,
+        clientLocation: options.clientLocation,
+        clientDevelopmentUrl: options.clientDevelopmentUrl,
+        clientDevelopmentStartCommand: options.clientDevelopmentStartCommand,
+        force: options.force === true
+    }, process.cwd(), coreRange);
+}), [
+    "Reads identity, version, and description from package.json, then writes",
+    "phresh.config.ts. A terminal asks only for values the project cannot",
+    "provide. Without a terminal, declare at least one endpoint with options."
+]);
+describe(program.command("pack")
+    .description("build and package this Program")
+    .action(async function () {
+    await pack();
+}), [
+    "Runs an optional buildCommand, then packages the production files",
+    "declared for each endpoint."
+]);
+describe(program.command("install")
+    .description("install this Program")
+    .action(async function () {
+    await install();
+}), [
+    "Builds and installs the Program declared by this project. Running",
+    "Processes end before installed paths change; Program data is preserved."
+]);
+describe(program.command("uninstall")
+    .description("uninstall this Program")
+    .option("--everything", "also remove Processes, data, and runtime state")
+    .action(async function (options) {
+    await uninstall(options.everything === true);
+}), [
+    "Removes the installed Program files while preserving its Processes, data,",
+    "and runtime Program. --everything removes all system-owned state."
+]);
+attached("start", "run the production Program without installing", [
+    "Runs this Program attached to the terminal. Output arrives here, and",
+    "ending this command stops the Program. An optional buildCommand runs",
+    "before launch, and the Program's exit status becomes this command's status."
+], "production");
+attached("dev", "run the development Program without installing", [
+    "Runs the same attached lifecycle as start using the development",
+    "declarations. A Client URL must respond within 15 seconds before launch."
+], "development");
+// Every command begins with the same breathing room. Keep this at the entry
+// point so individual commands never need to manufacture their own opening.
+console.log("");
+if (process.argv.length === 2)
+    program.help();
 try {
-    await wanted.run(parse(wanted, rest));
+    await program.parseAsync();
 }
 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;
+    if (error instanceof PromptCancelled)
+        process.exitCode = 0;
+    else {
+        console.error(`\n  phresh: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
     }
-    return options;
 }
-function text(options, name) {
-    const value = options[name];
-    return typeof value === "string" ? value : undefined;
+function attached(name, summary, detail, mode) {
+    describe(program.command(name)
+        .description(summary)
+        .argument("[run-options...]", "--run-option-<name>=<value> values passed to the Program")
+        .allowUnknownOption()
+        .action(async function (args) {
+        await launch(mode, process.cwd(), runOptions(name, args));
+    }), detail);
 }
-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 describe(command, paragraphs) {
+    command.addHelpText("after", `\n${paragraphs.map(line => line ? `  ${line}` : "").join("\n")}\n`);
+    return command;
 }
-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")}`);
+function runOptions(command, args) {
+    const options = {};
+    for (const argument of args) {
+        if (!argument.startsWith(runOptionPrefix))
+            throw new Error(`${command} accepts Program options only as ${runOptionPrefix}<name>=<value>; received "${argument}"`);
+        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, name))
+            throw new Error(`The run option "${name}" was given more than once`);
+        options[name] = said.slice(at + 1);
     }
-    console.log("");
+    return options;
 }