@phreshos/cli 0.1.28 → 0.1.29

package/README.md

@@ -146,7 +146,7 @@ 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.
+width and a height; `startCommand` or `entryFile`, not a generic command.
 
 An optional top-level `buildCommand` is authoring metadata. `phresh start`,
 `phresh install`, and `phresh pack` run it from this project before consuming
@@ -244,11 +244,19 @@ Say how the server runs or where the client is served:
 ```
 
 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
+different. A Server and its development block each select exactly one of
+`startCommand` or `entryFile`. A command starts an isolated operating-system
+process tree; an entry module runs as a Worker owned by the System. In
+development, the directory containing `phresh.config.ts` becomes the derived
+Server location. A client block requires an HTTP(S) `url`; development clients
 are never resolved from filesystem paths.
 
+An `entryFile` is a path inside its Server location. Packaging copies it with
+the rest of that directory, and the System rejects a path that escapes those
+files. A Worker has no independent process working directory and is not a
+security boundary; resolve module-owned resources with `import.meta.url` and
+use the Server SDK for Program storage.
+
 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
@@ -267,9 +275,10 @@ 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`.
+In a terminal, `init` asks for the production locations and Server execution
+modes needed by `start` and `install`, including whether a package build should
+prepare those locations. It then offers the development Server mode, Client
+command, and URL needed by `dev`.
 Existing `build` and `dev` package scripts become editable suggestions, never
 silent assumptions. A single Endpoint defaults to `dist`; when both Endpoints
 exist, their defaults are `dist/server` and `dist/client`. API documentation is

package/dist/cli.js

@@ -54,7 +54,9 @@ describe(program.command("init")
     .option("--server", "include a Server endpoint")
     .option("--server-location <path>", "production Server directory")
     .option("--server-start-command <command>", "production Server command")
+    .option("--server-entry-file <path>", "production Server worker entry")
     .option("--server-development-start-command <command>", "development Server command")
+    .option("--server-development-entry-file <path>", "development Server worker entry")
     .option("--client", "include a Client endpoint")
     .option("--client-location <path>", "production Client directory")
     .option("--client-development-url <url>", "development Client URL")
@@ -64,10 +66,12 @@ describe(program.command("init")
     await init({
         name: options.name,
         buildCommand: options.buildCommand,
-        server: options.server === true || options.serverLocation !== undefined || options.serverStartCommand !== undefined,
+        server: options.server === true || options.serverLocation !== undefined || options.serverStartCommand !== undefined || options.serverEntryFile !== undefined,
         serverLocation: options.serverLocation,
         serverStartCommand: options.serverStartCommand,
+        serverEntryFile: options.serverEntryFile,
         serverDevelopmentStartCommand: options.serverDevelopmentStartCommand,
+        serverDevelopmentEntryFile: options.serverDevelopmentEntryFile,
         client: options.client === true || options.clientLocation !== undefined,
         clientLocation: options.clientLocation,
         clientDevelopmentUrl: options.clientDevelopmentUrl,

package/dist/derive.js

@@ -14,6 +14,7 @@ export default function derive(config, directory, which) {
             "    server: {",
             "        …",
             "        development: { startCommand: \"tsx source/server/main.ts\" }",
+            "        // or: development: { entryFile: \"source/server/main.js\" }",
             "    }",
             "",
             "    client: {",
@@ -45,7 +46,7 @@ export default function derive(config, directory, which) {
                 start: server.start,
                 installCommand: config.server?.installCommand,
                 uninstallCommand: config.server?.uninstallCommand,
-                startCommand: server.startCommand
+                ...serverExecution(server)
             } },
         // A URL stands as written; a directory is made absolute. The
         // contract reads both from the one field, and which it is is
@@ -67,15 +68,23 @@ export default function derive(config, directory, which) {
 function serverHalf(half, which) {
     if (!half)
         return null;
-    const { development, ...declared } = half;
+    const { development, startCommand, entryFile, ...description } = half;
     if (which === "production" || !development)
-        return declared;
+        return {
+            ...description,
+            ...serverExecution({ startCommand, entryFile })
+        };
     return {
-        ...declared,
+        ...description,
         location: ".",
-        startCommand: development.startCommand
+        ...serverExecution(development)
     };
 }
+function serverExecution(server) {
+    return server.startCommand !== undefined
+        ? { startCommand: server.startCommand }
+        : { entryFile: server.entryFile };
+}
 function clientHalf(half, which) {
     if (!half)
         return null;

package/dist/init.js

@@ -1,5 +1,5 @@
 import {} from "@phreshos/core";
-import { configFile, readManifest } from "./project.js";
+import { configFile, containedServerEntry, readManifest } from "./project.js";
 import { dim } from "./style.js";
 import ensureProjectDependency, { projectScript } from "./project-dependency.js";
 import prompts from "./prompts.js";
@@ -59,21 +59,19 @@ export default async function init(options = {}, directory = process.cwd(), core
     let server;
     if (serverSelected) {
         const location = options.serverLocation ?? (interactive ? await ask("The system runs the production Server from this project-relative directory.", "Where are the production Server files?", clientSelected ? "dist/server" : "dist") : "");
-        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)
-            throw new Error("--server-start-command is required without a terminal");
-        let development = options.serverDevelopmentStartCommand;
+        const production = options.serverStartCommand === undefined && options.serverEntryFile === undefined && interactive
+            ? await askExecution(interaction, "production", "node main.js")
+            : execution(options.serverStartCommand, options.serverEntryFile, "production Server");
+        let development = explicitExecution(options.serverDevelopmentStartCommand, options.serverDevelopmentEntryFile, "development Server");
         if (interactive && development === undefined) {
             const suggested = manifest.scripts?.dev && projectScript(directory, manifest.packageManager, "dev");
             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);
+                development = await askExecution(interaction, "development", suggested || undefined);
             }
         }
-        if (development !== undefined && development.trim().length === 0)
-            throw new Error("A server development command must not be empty");
-        server = { location, startCommand, ...development && { development: { startCommand: development } } };
+        server = { location, ...production, ...development && { development } };
     }
     let client;
     if (clientSelected) {
@@ -117,7 +115,7 @@ export default async function init(options = {}, directory = process.cwd(), core
     await ensureProjectDependency("@phreshos/core", coreRange, directory);
     writeFileSync(path, compose(config));
     if (config.server)
-        interaction.detail("server", config.server.startCommand, `./${config.server.location}`);
+        interaction.detail(config.server.startCommand ? "server" : "server worker", config.server.startCommand ?? config.server.entryFile, `./${config.server.location}`);
     if (config.client)
         interaction.detail("client", `./${config.client.location}`);
     const next = [config.server?.development || config.client?.development ? "phresh dev" : null, "phresh start", "phresh install"].filter(Boolean);
@@ -140,7 +138,9 @@ function compose(config) {
         field("buildCommand", config.buildCommand),
         half("server", config.server && {
             location: config.server.location,
-            startCommand: config.server.startCommand,
+            ...(config.server.startCommand !== undefined
+                ? { startCommand: config.server.startCommand }
+                : { entryFile: config.server.entryFile }),
             ...config.server.development && { development: config.server.development }
         }),
         half("client", config.client && {
@@ -180,3 +180,35 @@ function httpUrl(value) {
         return false;
     }
 }
+function execution(startCommand, entryFile, owner) {
+    const selected = explicitExecution(startCommand, entryFile, owner);
+    if (!selected)
+        throw new Error(`Choose exactly one --server-start-command or --server-entry-file for the ${owner}`);
+    return selected;
+}
+function explicitExecution(startCommand, entryFile, owner) {
+    if (startCommand !== undefined && entryFile !== undefined)
+        throw new Error(`The ${owner} cannot declare both a start command and an entry file`);
+    if (startCommand !== undefined) {
+        if (startCommand.trim().length === 0)
+            throw new Error(`The ${owner} command must not be empty`);
+        return { startCommand };
+    }
+    if (entryFile !== undefined) {
+        if (entryFile.trim().length === 0)
+            throw new Error(`The ${owner} entry file must not be empty`);
+        if (!containedServerEntry(entryFile))
+            throw new Error(`The ${owner} entry file must remain inside its Server directory`);
+        return { entryFile };
+    }
+}
+async function askExecution(interaction, mode, suggestedCommand) {
+    const worker = await interaction.yes("A Worker uses fewer resources but shares the System's Node.js process.", `Run the ${mode} Server as a System-owned Worker?`, false);
+    if (worker)
+        return {
+            entryFile: await interaction.ask("This JavaScript module remains inside the Server files.", `What is the ${mode} Server entry file?`, mode === "production" ? "main.js" : "source/server/main.js")
+        };
+    return {
+        startCommand: await interaction.ask(`This command runs from the ${mode === "production" ? "production Server directory" : "project directory"}.`, `What command starts the ${mode} Server?`, suggestedCommand)
+    };
+}

package/dist/launch.js

@@ -50,7 +50,7 @@ export default async function launch(which, directory = process.cwd(), options =
     const clientStartCommand = clientDevelopmentConfig?.startCommand;
     heading(`${program.name ?? program.identity}${program.version ? ` ${program.version}` : ""}`, which);
     if (program.server)
-        line("server", String(program.server.startCommand), place(directory, program.server.location));
+        line(program.server.startCommand ? "server" : "server worker", String(program.server.startCommand ?? program.server.entryFile), place(directory, program.server.location));
     if (program.client)
         line("client", clientStartCommand ?? place(directory, program.client.location), clientStartCommand ? place(directory, program.client.location) : undefined);
     line("storage", place(directory, String(program.storage)));

package/dist/pack.js

@@ -76,10 +76,21 @@ function program(config, version) {
         categories: config.categories,
         keywords: config.keywords,
         website: config.website,
-        ...config.server && { server: { location: "server", start: config.server.start, installCommand: config.server.installCommand, uninstallCommand: config.server.uninstallCommand, startCommand: config.server.startCommand } },
+        ...config.server && { server: {
+                location: "server",
+                start: config.server.start,
+                installCommand: config.server.installCommand,
+                uninstallCommand: config.server.uninstallCommand,
+                ...serverExecution(config.server)
+            } },
         ...config.client && { client: { location: "client", start: config.client.start, title: config.client.title, size: config.client.size, position: config.client.position, layer: config.client.layer, minimize: config.client.minimize } }
     };
 }
+function serverExecution(server) {
+    return server.startCommand !== undefined
+        ? { startCommand: server.startCommand }
+        : { entryFile: server.entryFile };
+}
 // What is at a half's location, where the package keeps it. A half that
 // was declared and is not there is the answer to whether it was built.
 function place(zip, directory, location, half) {

package/dist/project.js

@@ -8,7 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { isRelativeValue, layers } from "@phreshos/core";
 import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { isAbsolute, normalize, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 export const configFile = "phresh.config.ts";
 export async function readConfig(directory = process.cwd()) {
@@ -76,8 +76,8 @@ function coherent(config) {
     }
     if (!(config.server && (config.server.start ?? true)) && !(config.client && (config.client.start ?? true)))
         throw new Error("A Program's default Process must start a server endpoint, a client endpoint, or both");
-    if (config.server && (typeof config.server.startCommand !== "string" || config.server.startCommand.length === 0))
-        throw new Error("A server half must say what starts it");
+    if (config.server)
+        execution(config.server, "A server half");
     if (config.server?.installCommand !== undefined && typeof config.server.installCommand !== "string")
         throw new Error("A server half's install command must be text");
     if (config.server?.uninstallCommand !== undefined && typeof config.server.uninstallCommand !== "string")
@@ -101,8 +101,8 @@ function coherent(config) {
     const serverDevelopment = config.server?.development;
     if (serverDevelopment !== undefined && (typeof serverDevelopment !== "object" || serverDevelopment === null || Array.isArray(serverDevelopment)))
         throw new Error("server.development must be a declaration");
-    if (serverDevelopment !== undefined && (typeof serverDevelopment.startCommand !== "string" || serverDevelopment.startCommand.trim().length === 0))
-        throw new Error("server.development.startCommand must be non-empty text");
+    if (serverDevelopment !== undefined)
+        execution(serverDevelopment, "server.development");
     const clientDevelopment = config.client?.development;
     if (clientDevelopment !== undefined && (typeof clientDevelopment !== "object" || clientDevelopment === null || Array.isArray(clientDevelopment)))
         throw new Error("client.development must be a declaration");
@@ -120,6 +120,24 @@ function coherent(config) {
             throw new Error(`A window's ${what} is a finite pixel number or a relative expression such as "50% + 10"`);
     }
 }
+function execution(value, owner) {
+    const command = typeof value.startCommand === "string" && value.startCommand.trim().length > 0;
+    const entry = typeof value.entryFile === "string" && value.entryFile.trim().length > 0;
+    if (value.startCommand !== undefined && !command)
+        throw new Error(`${owner}'s startCommand must be non-empty text`);
+    if (value.entryFile !== undefined && !entry)
+        throw new Error(`${owner}'s entryFile must be a non-empty path`);
+    if (command === entry)
+        throw new Error(`${owner} must declare exactly one non-empty startCommand or entryFile`);
+    if (entry && !containedServerEntry(value.entryFile))
+        throw new Error(`${owner}'s entryFile must remain inside its Server directory`);
+}
+export function containedServerEntry(entry) {
+    if (isAbsolute(entry))
+        return false;
+    const path = normalize(entry);
+    return path !== ".." && !path.startsWith(`..${sep}`);
+}
 function httpUrl(value) {
     if (typeof value !== "string" || value.trim().length === 0)
         return false;

package/dist/template/package.json

@@ -22,7 +22,7 @@
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.28",
+        "@phreshos/cli": "^0.1.29",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-  "version": "0.1.28",
+    "version": "0.1.29",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"
@@ -49,7 +49,7 @@
     "packageManager": "bun@1.3.14",
     "dependencies": {
         "@clack/prompts": "^1.7.0",
-    "@phreshos/core": "^0.1.19",
+        "@phreshos/core": "^0.1.20",
         "adm-zip": "^0.6.0",
         "commander": "^15.0.0",
         "picocolors": "^1.1.1"