@phreshos/cli 0.1.0 → 0.1.2

package/README.md

@@ -204,17 +204,17 @@ phresh init --server \
 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
+A Program must declare a Server endpoint, a Client endpoint, 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.
+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
-are not guessed. An omitted `start` is `true`; only a default-off half needs to
+are not guessed. An omitted `start` is `true`; only a default-off Endpoint needs to
 say `start: false`.
 
 ## start and dev
@@ -332,6 +332,13 @@ 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.
 
+The document covers only what the Program owns: its capabilities, operation
+and event names, payloads, behavior, state, and Program-defined failures. It
+does not explain how to find a Program, obtain an Endpoint, publish or ask, or
+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
 directory it installs into from your program's `identity`.

package/dist/client-development.js

@@ -5,6 +5,7 @@ import commandEnvironment from "./command-environment.js";
 const timeout = 15_000;
 const reportEvery = 2_000;
 const pollEvery = 200;
+const clientOrigin = "null";
 /** Refuse to start an owned command over a URL already served by something else. */
 export async function assertClientDevelopmentUrlFree(url) {
     if (!await occupied(url))
@@ -82,8 +83,15 @@ export async function waitForClientDevelopment(url, command, waiting = timeout,
     let nextReport = began + reporting;
     const commandEnded = command?.exited.then(exit => { throw commandFailure(exit); });
     while (Date.now() - began < waiting) {
-        if (await available(url, waiting - (Date.now() - began)))
+        const availability = await inspect(url, waiting - (Date.now() - began));
+        if (availability === "ready")
             return;
+        if (availability === "cors-blocked") {
+            throw new Error([
+                `Client development URL responded, but does not allow the sandboxed Client origin: ${url}`,
+                `Enable CORS so the response includes Access-Control-Allow-Origin: * (for Vite, use server: { cors: true }).`
+            ].join("\n"));
+        }
         const now = Date.now();
         if (now >= nextReport) {
             line("waiting for", url);
@@ -108,14 +116,18 @@ export function commandFailure(exit) {
         return new Error(`Client development command ended on ${exit.signal}`);
     return new Error(`Client development command exited with ${exit.code ?? 0}`);
 }
-async function available(url, remaining) {
+async function inspect(url, remaining) {
     try {
-        const response = await fetch(url, { signal: AbortSignal.timeout(Math.max(1, Math.min(500, remaining))) });
+        const response = await fetch(url, {
+            headers: { origin: clientOrigin },
+            signal: AbortSignal.timeout(Math.max(1, Math.min(500, remaining)))
+        });
+        const allowedOrigin = response.headers.get("access-control-allow-origin")?.trim();
         await response.body?.cancel();
-        return true;
+        return allowedOrigin === "*" || allowedOrigin === clientOrigin ? "ready" : "cors-blocked";
     }
     catch {
-        return false;
+        return "unavailable";
     }
 }
 function terminate(child, signal) {

package/dist/init.js

@@ -1,6 +1,6 @@
 import {} from "@phreshos/core";
 import { configFile, readManifest } from "./project.js";
-import { dim, heading, line } from "./style.js";
+import { bold, dim, heading, line } from "./style.js";
 import ensureProjectDependency, { projectScript } from "./project-dependency.js";
 import { createInterface } from "node:readline/promises";
 import { existsSync, writeFileSync } from "node:fs";
@@ -21,21 +21,23 @@ export default async function init(options = {}, directory = process.cwd(), core
     if (existsSync(path) && options.force !== true && !interactive)
         throw new Error(`${configFile} already exists — use --force to replace it`);
     const readline = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
-    async function ask(question, fallback) {
+    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})`)}`;
-        const said = (await readline.question(`  ${question}${suffix} `)).trim();
+        console.log(`  ${dim(explanation)}`);
+        const said = (await readline.question(`  ${bold(question)}${suffix} `)).trim();
+        console.log("");
         return said || fallback || "";
     }
-    async function yes(question, fallback) {
-        return (await ask(question, fallback ? "Y/n" : "y/N")).toLowerCase().startsWith("y");
+    async function yes(explanation, question, fallback) {
+        return (await ask(explanation, question, fallback ? "Y/n" : "y/N")).toLowerCase().startsWith("y");
     }
     try {
         if (existsSync(path) && options.force !== true) {
             heading(configFile, "already initialized");
-            if (!await yes("Replace it?", false)) {
-                console.log(`\n  ${dim("No changes made.")}\n`);
+            if (!await yes("The existing configuration must be replaced before this project can be initialized again.", "Replace it?", false)) {
+                console.log(`  ${dim("No changes made.")}\n`);
                 return;
             }
         }
@@ -51,35 +53,36 @@ export default async function init(options = {}, directory = process.cwd(), core
         if (!explicitShape) {
             if (!interactive)
                 throw new Error("Choose at least one half with --server, --client, or both");
-            serverSelected = await yes("Include a server half?", true);
-            clientSelected = !serverSelected || await yes("Include a client half?", true);
+            serverSelected = await yes("A Server runs on the host machine and can keep working without an open desktop.", "Does this Program have a Server?", true);
+            clientSelected = !serverSelected || await yes("A Client runs through a desktop and provides the Program's visual interface.", "Does this Program have a Client?", true);
         }
         if (!serverSelected && !clientSelected)
             throw new Error("A Program must have a server half, a client half, or both");
-        const name = options.name ?? (interactive ? await ask("What name should people see?", manifest.name) : undefined);
+        const name = options.name ?? (interactive ? await ask("This name is shown to people; the package name remains the Program identity.", "What name should people see?", manifest.name) : undefined);
         if (name !== undefined && name.trim().length === 0)
             throw new Error("--name must not be empty");
         let apiDocs = options.apiDocs;
         if (interactive && apiDocs === undefined) {
             const suggested = ["api-docs.md", "README.md"].find(file => existsSync(resolve(directory, file)));
-            if (await yes("Provide an API documentation entry point?", Boolean(suggested)))
-                apiDocs = await ask("Where is its Markdown file?", suggested);
+            if (await yes("API documentation explains only the services this Program itself provides.", "Does this Program provide API documentation?", Boolean(suggested))) {
+                apiDocs = await ask("The path is resolved from the project root and becomes the official API entry point.", "Where is the API documentation file?", suggested);
+            }
         }
         if (apiDocs !== undefined && apiDocs.trim().length === 0)
             throw new Error("An API documentation path must not be empty");
         let buildCommand = options.buildCommand;
         if (interactive && buildCommand === undefined) {
             const suggested = manifest.scripts?.build && projectScript(directory, manifest.packageManager, "build");
-            const builds = await yes("Run a command before production start, install, and pack?", Boolean(suggested));
+            const builds = await yes("Production operations need the Program's built files.", "Build before start, install, and pack?", Boolean(suggested));
             if (builds)
-                buildCommand = await ask("What builds the production files?", suggested || undefined);
+                buildCommand = await ask("This command produces the production Server and Client files.", "What command builds the Program?", suggested || undefined);
         }
         if (buildCommand !== undefined && buildCommand.trim().length === 0)
             throw new Error("A build command must not be empty");
         let server;
         if (serverSelected) {
-            const location = options.serverLocation ?? (interactive ? await ask("Where are the production server files?", "build/server") : "");
-            const startCommand = options.serverStartCommand ?? (interactive ? await ask("What starts the production server?", "node main.js") : "");
+            const location = options.serverLocation ?? (interactive ? await ask("The system runs the production Server from this project-relative directory.", "Where are the production Server files?", "build/server") : "");
+            const startCommand = options.serverStartCommand ?? (interactive ? await ask("This command runs inside the production Server directory.", "What command starts the production Server?", "node main.js") : "");
             if (!location)
                 throw new Error("--server-location is required without a terminal");
             if (!startCommand)
@@ -87,8 +90,9 @@ export default async function init(options = {}, directory = process.cwd(), core
             let development = options.serverDevelopmentStartCommand;
             if (interactive && development === undefined) {
                 const suggested = manifest.scripts?.dev && projectScript(directory, manifest.packageManager, "dev");
-                if (await yes("Develop the server from source?", Boolean(suggested && !clientSelected)))
-                    development = await ask("What starts the development server?", suggested || undefined);
+                if (await yes("Development mode can run the Server directly from the project source.", "Run the Server from source during development?", Boolean(suggested && !clientSelected))) {
+                    development = await ask("This command remains attached to the phresh dev session.", "What command starts the development Server?", suggested || undefined);
+                }
             }
             if (development !== undefined && development.trim().length === 0)
                 throw new Error("A server development command must not be empty");
@@ -96,17 +100,18 @@ export default async function init(options = {}, directory = process.cwd(), core
         }
         let client;
         if (clientSelected) {
-            const location = options.clientLocation ?? (interactive ? await ask("Where are the production client files?", "dist") : "");
+            const location = options.clientLocation ?? (interactive ? await ask("The system serves the production Client from this project-relative directory.", "Where are the production Client files?", "dist") : "");
             if (!location)
                 throw new Error("--client-location is required without a terminal");
             let developmentUrl = options.clientDevelopmentUrl;
             let developmentStartCommand = options.clientDevelopmentStartCommand;
             if (interactive && developmentUrl === undefined && developmentStartCommand === undefined) {
                 const suggested = manifest.scripts?.dev && projectScript(directory, manifest.packageManager, "dev");
-                if (await yes("Use a client development server?", Boolean(suggested))) {
-                    developmentUrl = await ask("Where is the development client served?", "http://localhost:5173/");
-                    if (await yes("Should the CLI start that development server?", Boolean(suggested)))
-                        developmentStartCommand = await ask("What starts it?", suggested || undefined);
+                if (await yes("A development server can provide live updates instead of built Client files.", "Use a Client development server?", Boolean(suggested))) {
+                    developmentUrl = await ask("The desktop opens this exact HTTP or HTTPS address during phresh dev.", "What URL serves the development Client?", "http://localhost:5173/");
+                    if (await yes("The CLI can own the development server and stop it when the session ends.", "Should phresh dev start the Client server?", Boolean(suggested))) {
+                        developmentStartCommand = await ask("This command remains attached to the phresh dev session.", "What command starts the Client development server?", suggested || undefined);
+                    }
                 }
             }
             if (developmentStartCommand !== undefined && developmentUrl === undefined)
@@ -142,7 +147,16 @@ export default async function init(options = {}, directory = process.cwd(), core
             line("client", `./${config.client.location}`);
         console.log("");
         const next = [config.server?.development || config.client?.development ? "phresh dev" : null, "phresh start", "phresh install"].filter(Boolean);
-        console.log(`  ${dim("Next:")} ${next.join(`  ${dim("or")}  `)}\n`);
+        console.log(`  ${dim("Next:")} ${next.join(`  ${dim("or")}  `)}`);
+        if (config.client) {
+            heading("Client requirements");
+            line("base URL", "./", "required for production assets");
+            if (config.client.development)
+                line("CORS", "enabled", "required on the development server");
+            console.log("");
+        }
+        else
+            console.log("");
     }
     finally {
         readline?.close();

package/dist/launch.js

@@ -81,7 +81,7 @@ export default async function launch(which, directory = process.cwd(), options =
         if (Object.keys(options).length)
             line("options", Object.entries(options).map(([name, value]) => `${name}=${value}`).join("  "));
         const attachment = attach(program, options, {
-            started: identity => console.log(`  ${dim("running as")} ${identity}\n`),
+            started: identity => console.log(`${clientDevelopment ? "\n" : ""}  ${dim("running as")} ${identity}\n`),
             output: (stream, text) => (stream === "err" ? process.stderr : process.stdout).write(text)
         }, undefined, controller.signal);
         const ended = clientDevelopment ? await Promise.race([

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "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",
@@ -15,7 +15,7 @@
         "README.md"
     ],
     "dependencies": {
-        "@phreshos/core": "0.1.0",
+        "@phreshos/core": "^0.1.0",
         "adm-zip": "^0.6.0"
     },
     "devDependencies": {