@phreshos/cli 0.1.4 → 0.1.5

package/dist/project.js

@@ -6,11 +6,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { layers } from "@phreshos/core";
+import { isRelativeValue, 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);
@@ -40,7 +39,7 @@ function coherent(config) {
         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"]) {
+    for (const field of ["name", "version", "description", "icon"]) {
         if (config[field] !== undefined && typeof config[field] !== "string")
             throw new Error(`A program's ${field} must be text`);
     }

package/dist/prompts.js

@@ -0,0 +1,105 @@
+import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
+import colors from "picocolors";
+import { column, heading, line } from "./style.js";
+/** Signals an ordinary interactive cancellation rather than an operation failure. */
+export class PromptCancelled extends Error {
+}
+/**
+ * One interaction language shared by commands that can ask questions.
+ *
+ * Clack owns terminal behavior. This adapter owns only the product's wording
+ * and the rule that automation never opens or waits for a prompt.
+ */
+export default function prompts() {
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    function begin(title, context) {
+        if (interactive)
+            intro(`${colors.bold(title)}${context ? ` ${colors.dim(`· ${context}`)}` : ""}`);
+        else
+            heading(title, context);
+    }
+    function finish(message) {
+        if (interactive)
+            outro(colors.bold(message));
+        else
+            heading(message);
+    }
+    function detail(label, value, source) {
+        if (interactive)
+            log.message(`${colors.dim(column(label))}${value}${source ? `  ${colors.dim(source)}` : ""}`);
+        else
+            line(label, value, source);
+    }
+    function message(value = "") {
+        if (interactive)
+            log.message(value);
+        else
+            console.log(value ? `  ${value}` : "");
+    }
+    async function progress(message, completed, work) {
+        if (!interactive)
+            return await work();
+        const indicator = spinner();
+        indicator.start(message);
+        try {
+            const result = await work();
+            indicator.clear();
+            log.success(completed, { spacing: 0 });
+            return result;
+        }
+        catch (error) {
+            indicator.error(`${message} failed`);
+            throw error;
+        }
+    }
+    async function ask(explanation, question, fallback) {
+        if (!interactive)
+            throw new Error(`${question} Supply the corresponding option when no terminal is attached`);
+        log.message(colors.dim(explanation));
+        const value = await text({
+            message: question,
+            placeholder: fallback,
+            defaultValue: fallback
+        });
+        if (isCancel(value))
+            stop();
+        return value.trim();
+    }
+    async function yes(explanation, question, fallback) {
+        if (!interactive)
+            throw new Error(`${question} Supply the corresponding option when no terminal is attached`);
+        log.message(colors.dim(explanation));
+        const value = await confirm({ message: question, initialValue: fallback });
+        if (isCancel(value))
+            stop();
+        return value;
+    }
+    async function choose(explanation, question, values, fallback) {
+        if (!interactive)
+            throw new Error(`${question} Supply the corresponding option when no terminal is attached`);
+        log.message(colors.dim(explanation));
+        const value = await select({
+            message: question,
+            options: values.map(value => ({ value, label: value })),
+            initialValue: fallback
+        });
+        if (isCancel(value))
+            stop();
+        return value;
+    }
+    function stop() {
+        cancel("No changes made");
+        throw new PromptCancelled();
+    }
+    return {
+        interactive,
+        begin,
+        finish,
+        detail,
+        message,
+        progress,
+        ask,
+        yes,
+        choose
+    };
+}

package/dist/style.js

@@ -1,16 +1,8 @@
-/**
- * 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;
+import colors from "picocolors";
+/** The quiet and emphatic text used by non-interactive command reports. */
+export const dim = colors.dim;
+export const bold = colors.bold;
+export const accent = colors.cyan;
 // 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.
 //
@@ -18,7 +10,10 @@ export const bold = (text) => colour ? `${escape}[1m${text}${escape}[22m` : text
 // 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)}` : ""}`);
+    console.log(`  ${dim(column(label))}${value}${note ? `  ${dim(note)}` : ""}`);
+}
+export function column(label) {
+    return label.length < 12 ? label.padEnd(12) : `${label} `;
 }
 export function heading(title, note) {
     console.log("");

package/dist/template/README.md

@@ -1,4 +1,4 @@
-# Get Started
+# Phresh Program
 
 A small Counter built as a complete Program. Its Node.js Server owns the
 number, while its React Client reads and increments that same authoritative

package/dist/template/package.json

@@ -1,21 +1,22 @@
 {
-    "name": "get-started",
+    "name": "phresh-program",
     "private": true,
     "version": "0.1.0",
     "type": "module",
     "scripts": {
-        "phresh": "phresh"
+        "dev": "phresh dev",
+        "start": "phresh start"
     },
     "dependencies": {
-        "@phreshos/client": "^0.1.0",
-        "@phreshos/react": "^0.1.0",
-        "@phreshos/server": "^0.1.0",
-        "@phreshos/core": "^0.1.0",
+        "@phreshos/client": "^0.1.1",
+        "@phreshos/react": "^0.1.1",
+        "@phreshos/server": "^0.1.1",
+        "@phreshos/core": "^0.1.1",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.4",
+        "@phreshos/cli": "^0.1.5",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/dist/template/phresh.config.ts

@@ -1,69 +1,109 @@
 import { defineConfig } from "@phreshos/core"
 
+/**
+ * This is the Program's authoring declaration, not a runtime configuration
+ * loaded by either endpoint. The Phresh CLI reads it and derives the concrete
+ * Program description needed for development, production, installation, or
+ * packaging.
+ *
+ * Production uses the built locations and commands declared below.
+ * Development replaces only each endpoint's location and start command with
+ * its `development` declaration. Packaging relocates the production files
+ * into the Program archive. Relative paths begin at this project directory.
+ */
 export default defineConfig({
 
-    // The stable, kebab-case address used by programs and the system.
-    identity: "get-started",
+    // Permanent public address of the Program. It is kebab-case because the
+    // system also uses it as the installed directory name. Unlike `name`, it
+    // is an identifier and must remain stable across releases.
+    identity: "phresh-program",
 
-    // Human-facing details shown by the desktop and development tools.
-    name: "Get Started",
+    // Human-facing metadata shown by the desktop and authoring tools. None of
+    // these values determines the Program's identity.
+    name: "Phresh Program",
     description: "A simple counter whose state lives on the Server.",
     version: "0.1.0",
 
-    // The official entry point for this Program's own API.
+    // Markdown entry point for the API owned by this Program. It documents the
+    // counter service contract; PhreshOS endpoint mechanics belong in PhreshOS
+    // documentation instead of being repeated here.
     apiDocs: "api-docs.md",
 
-    // A directory containing files named by size, such as 128x128.png.
-    icons: "icons",
+    // One authored PNG. Installation gives it a canonical name and the system
+    // derives the standard hosted icon sizes from it.
+    icon: "icon.png",
 
-    // Runs before production start, install, and pack; dev uses the
-    // development declarations below instead.
+    // Prepares both production endpoint directories. The CLI runs it from this
+    // project before `phresh start`, `phresh install`, and `phresh pack`.
+    // `phresh dev` does not build and uses the declarations below instead.
     buildCommand: "node --import tsx source/build.ts",
 
+    // A Process may run its Server and Client independently. This declaration
+    // says how the Server is prepared and started; it does not merge Server
+    // code into the browser Client.
     server: {
 
-        // The built server directory and the command run from within it.
+        // Production directory containing the Server artifact. The start
+        // command runs with this directory as its working directory.
         location: "dist/server",
         startCommand: "node main.js",
 
-        // Optional preparation performed once before the installed server
-        // first starts. This bundled example does not need it.
+        // An install command is optional and runs inside `location` when the
+        // Program is installed. This build bundles its Server dependencies, so
+        // the example does not need one.
         // installCommand: "npm install",
 
-        // A declared half starts by default. Set this to false when it
-        // should exist but only be included when explicitly requested.
+        // Declared endpoints start in a default Process unless `start` is
+        // false. A false value keeps the capability available for an explicit
+        // Process launch without starting it automatically.
         // start: false,
 
         development: {
 
-            // Development server commands run from the project root.
+            // `phresh dev` runs this command from the project directory. The
+            // project directory becomes the development Server location, so
+            // source imports and watch mode work without a production build.
             startCommand: "node --watch --import tsx source/server/main.ts"
         }
     },
 
+    // The Client declaration also defines the initial Window created for it.
+    // It contains presentation defaults only; live Window state belongs to
+    // each running Process.
     client: {
 
-        // The directory containing the built browser application.
+        // Production directory containing the browser application's
+        // `index.html` and all files reachable from it.
         location: "dist/client",
 
-        title: "Get Started",
+        // Initial Window values. The title defaults to the Program name when
+        // omitted. This example chooses a fixed initial size while leaving
+        // placement, layer, and minimized state to their system defaults.
+        title: "Phresh Program",
         size: { width: 600, height: 500 },
 
-        // Optional defaults for the window created with this client half.
-        // title: "Get Started",
-        // Fractions and percentages are relative to the Window's layer. Pixel
-        // offsets may be combined with them in one linear expression.
+        // Geometry accepts finite pixel numbers or linear values. Fractions
+        // and percentages are relative to the selected desktop layer, and a
+        // pixel offset may be combined with either form.
         // size: { width: "50% + 20", height: 440 },
         // position: { x: "1/2 + 10", y: 40 },
-        // layer: "window", // "under" and "over" are frameless desktop layers.
+
+        // `window` is the ordinary framed layer. `under` and `over` are
+        // structurally isolated, frameless desktop layers.
+        // layer: "window",
+
+        // The initial Window may also be declared to open minimized.
         // minimize: true,
 
         development: {
 
-            // The CLI starts this command, then waits for the URL before it
-            // launches the development Program.
+            // Development Clients are addressed by URL rather than a local
+            // artifact directory. The CLI starts this optional tool, waits for
+            // the URL to respond, and only then launches the Program. The dev
+            // server must allow the desktop origin through CORS; this project's
+            // Vite configuration does so.
             url: "http://localhost:5200/",
-            startCommand: "vite dev"
+            startCommand: "vite dev --config vite.client.ts"
         }
     }
 })

package/dist/template/source/build.ts

@@ -1,4 +1,4 @@
-import { externalDependencies } from "@/vite.config"
+import { externalDependencies } from "@/vite.server"
 import { writeFile } from "node:fs/promises"
 import packageConfig from "@/package.json"
 import { build } from "vite"
@@ -10,8 +10,8 @@ for (const externalDependency of externalDependencies) {
     dependencies[externalDependency] = packageConfig.dependencies[externalDependency]
 }
 
-await build({ build: { ssr: true } })
+await build({ configFile: "vite.server.ts" })
 
-await build()
+await build({ configFile: "vite.client.ts" })
 
 await writeFile("dist/server/package.json", JSON.stringify({ type: "module", dependencies }))

package/dist/template/source/client/app.tsx

@@ -1,4 +1,4 @@
-import { CurrentProvider, useSubscribe } from "@phreshos/react"
+import { useSubscribe } from "@phreshos/react"
 import { useEffect, useState } from "react"
 import { current } from "@phreshos/client"
 
@@ -16,7 +16,7 @@ function Counter() {
 
     return <main className="counter-card">
 
-        <span className="label">Get Started</span>
+        <span className="label">Phresh Program</span>
 
         <h1>Server counter</h1>
 
@@ -32,10 +32,5 @@ function Counter() {
 }
 
 export default function App() {
-
-    return <CurrentProvider waitServer fallback={<main className="loading">Connecting to the Server…</main>}>
-
-        <Counter />
-
-    </CurrentProvider>
+    return <Counter />
 }

package/dist/template/source/server/main.ts

@@ -6,7 +6,7 @@ let count = 0
 
 current.answer("read", () => count)
 
-current.subscribe("increment", function () {
+current.subscribe("increment", async function () {
 
     count += 1
 

package/dist/template/vite.client.ts

@@ -0,0 +1,22 @@
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+import { resolve } from "node:path"
+
+export default defineConfig({
+    root: "source/client",
+    plugins: [react()],
+    base: "./",
+    resolve: {
+        tsconfigPaths: true,
+        dedupe: ["react"]
+    },
+    server: {
+        cors: true,
+        port: 5200,
+        strictPort: true
+    },
+    build: {
+        emptyOutDir: true,
+        outDir: resolve(import.meta.dirname, "dist/client")
+    }
+})

package/dist/template/vite.server.ts

@@ -0,0 +1,27 @@
+import packageConfig from "./package.json" with { type: "json" }
+import { defineConfig } from "vite"
+import { resolve } from "node:path"
+
+export const externalDependencies: (keyof typeof packageConfig.dependencies)[] = [
+
+    // Add packages here that should NOT be bundled during server, Example: "sqlite3"
+]
+
+export default defineConfig({
+    root: "source/server",
+    resolve: {
+        tsconfigPaths: true
+    },
+    ssr: {
+        noExternal: true,
+        external: externalDependencies
+    },
+    build: {
+        ssr: true,
+        emptyOutDir: true,
+        outDir: resolve(import.meta.dirname, "dist/server"),
+        rolldownOptions: {
+            input: "main.ts"
+        }
+    }
+})

package/dist/template.json

@@ -0,0 +1,5 @@
+{
+    "repository": "PhreshOS/phresh-program",
+    "version": "0.1.0",
+    "development": true
+}

package/package.json

@@ -1,11 +1,12 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.4",
+    "version": "0.1.5",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "scripts": {
+        "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
         "compile": "tsc --noEmit false --outDir dist --rootDir source --rewriteRelativeImportExtensions true --allowImportingTsExtensions true",
-        "build": "node --run compile && node dist/build-template.js",
+        "build": "node --run clean && node --run compile && node dist/build-template.js",
         "prepack": "node --run build"
     },
     "bin": {
@@ -16,8 +17,11 @@
         "README.md"
     ],
     "dependencies": {
-        "@phreshos/core": "^0.1.0",
-        "adm-zip": "^0.6.0"
+        "@clack/prompts": "^1.7.0",
+        "@phreshos/core": "^0.1.1",
+        "adm-zip": "^0.6.0",
+        "commander": "^15.0.0",
+        "picocolors": "^1.1.1"
     },
     "devDependencies": {
         "@types/adm-zip": "^0.5.8",

package/dist/questions.js

@@ -1,25 +0,0 @@
-import { bold, dim } from "./style.js";
-import { createInterface } from "node:readline/promises";
-/** One prompt language shared by every interactive command. */
-export default function questions() {
-    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-    const readline = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
-    async function ask(explanation, question, fallback) {
-        if (!readline)
-            throw new Error(`${question} Supply the corresponding option when no terminal is attached`);
-        const suffix = fallback === undefined ? "" : ` ${dim(`(${fallback})`)}`;
-        console.log(`  ${dim(explanation)}`);
-        const said = (await readline.question(`  ${bold(question)}${suffix} `)).trim();
-        console.log("");
-        return said || fallback || "";
-    }
-    async function yes(explanation, question, fallback) {
-        return (await ask(explanation, question, fallback ? "Y/n" : "y/N")).toLowerCase().startsWith("y");
-    }
-    return {
-        interactive,
-        ask,
-        yes,
-        close: () => readline?.close()
-    };
-}

package/dist/relative-value.js

@@ -1,118 +0,0 @@
-/**
- * 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;
-}