@phreshos/cli 0.1.3 → 0.1.5

package/dist/project-dependency.js

@@ -1,55 +1,105 @@
 import { line } from "./style.js";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 /** Returns the package-manager command that runs one project script. */
 export function projectScript(directory, declared, script) {
-    return `${packageManager(directory, declared).name} run ${script}`;
+    return `${projectPackageManager(directory, declared).name} run ${script}`;
 }
 /**
- * Ensures one development dependency using the source appropriate to this CLI.
+ * Resolves an SDK through the one source policy shared by `init` and `create`.
  *
- * A CLI running from this repository uses its sibling dev-kit, so Program
- * authoring can be exercised before anything is published. An installed CLI
- * has no such sibling and names the declared registry range instead. This
- * decision belongs here once for both `init` and the future `create` command.
+ * A Program inside this repository's workspace uses its sibling dev-kit. A
+ * standalone project or distributed CLI keeps the published range embedded
+ * in the generated template. Local packages therefore never leak their own
+ * workspace-only development graph into an unrelated project.
  */
-export default async function ensureProjectDependency(name, range, directory = process.cwd()) {
+export function projectDependency(name, range, directory) {
+    const workspaceDirectory = resolve(import.meta.dirname, "..", "..", "..");
+    const workspace = manifestAt(workspaceDirectory);
+    const sourceDirectory = resolve(import.meta.dirname, "..", "..", localDirectories[name]);
+    const manifest = manifestAt(sourceDirectory);
+    if (workspace?.name === "@phreshos/workspace" && workspaceIncludes(workspaceDirectory, directory, workspace.workspaces) && manifest?.name === name && manifest.version && accepts(range, manifest.version)) {
+        return {
+            installSpecifier: `${name}@workspace:*`,
+            manifestSpecifier: "workspace:*",
+            local: true
+        };
+    }
+    return {
+        installSpecifier: `${name}@${range}`,
+        manifestSpecifier: range,
+        local: false
+    };
+}
+/** Detects the package manager declared by, present in, or invoking a project. */
+export function projectPackageManager(directory, declared, preferred) {
+    const named = preferred ?? packageManagerName(declared) ?? packageManagerFromLocks(directory) ?? packageManagerFromInvocation();
+    return managers[named ?? "npm"];
+}
+/** Installs the dependencies already declared by a generated project. */
+export async function installProjectDependencies(directory, preferred, output = "inherit") {
+    const manifest = manifestAt(directory);
+    const manager = projectPackageManager(directory, manifest?.packageManager, preferred);
+    await run(manager.name, manager.installArgs, directory, output);
+    return manager.name;
+}
+/**
+ * Ensures one project dependency using the source appropriate to this CLI.
+ *
+ * `init` uses development dependencies because Core supplies the authoring
+ * contract for an existing project. `create` preserves the canonical
+ * template's own dependency sections instead.
+ */
+export default async function ensureProjectDependency(name, range, directory = process.cwd(), section = "devDependencies") {
     const manifestPath = resolve(directory, "package.json");
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
     if (manifest.dependencies?.[name] || manifest.devDependencies?.[name])
         return;
-    const manager = packageManager(directory, manifest.packageManager);
-    const source = packageSource(name, range);
+    const manager = projectPackageManager(directory, manifest.packageManager);
+    const source = projectDependency(name, range, directory);
     line("dependency", name, `${manager.name}, ${source.local ? "local dev-kit" : range}`);
-    await new Promise(function (settle, refuse) {
-        const child = spawn(manager.name, [...manager.args, source.specifier], {
+    await run(manager.name, [...manager.addArgs(section), source.installSpecifier], directory);
+    console.log("");
+}
+function run(command, args, directory, output = "inherit") {
+    return new Promise(function (settle, refuse) {
+        let diagnostic = "";
+        const child = spawn(command, args, {
             cwd: directory,
-            stdio: "inherit",
+            stdio: output === "capture" ? ["ignore", "pipe", "pipe"] : "inherit",
             shell: process.platform === "win32"
         });
-        child.once("error", error => refuse(new Error(`Could not run ${manager.name}: ${error.message}`)));
+        if (output === "capture") {
+            child.stdout?.on("data", chunk => { diagnostic += String(chunk); });
+            child.stderr?.on("data", chunk => { diagnostic += String(chunk); });
+        }
+        child.once("error", error => refuse(new Error(`Could not run ${command}: ${error.message}`)));
         child.once("exit", function (code, signal) {
             if (signal)
-                refuse(new Error(`${manager.name} ended on ${signal}`));
+                refuse(new Error(`${command} ended on ${signal}`));
             else if (code !== 0)
-                refuse(new Error(`${manager.name} exited with ${code ?? 0}`));
+                refuse(new Error(`${command} exited with ${code ?? 0}${diagnostic.trim() ? `\n\n${diagnostic.trim()}` : ""}`));
             else
                 settle();
         });
     });
-    console.log("");
-}
-function packageSource(name, range) {
-    const directory = resolve(import.meta.dirname, "..", "..", localDirectories[name]);
-    const manifest = manifestAt(directory);
-    if (manifest?.name === name && manifest.version && accepts(range, manifest.version))
-        return { specifier: directory, local: true };
-    return { specifier: `${name}@${range}`, local: false };
 }
 function accepts(range, version) {
     return range === "workspace:*" || range === version || range === `^${version}` || range === `~${version}`;
 }
+function workspaceIncludes(root, directory, patterns) {
+    const local = relative(root, resolve(directory)).replaceAll("\\", "/");
+    if (!local || local === ".." || local.startsWith("../") || isAbsolute(local))
+        return false;
+    return patterns?.some(function (pattern) {
+        if (!pattern.endsWith("/*"))
+            return local === pattern;
+        const prefix = pattern.slice(0, -1);
+        const child = local.startsWith(prefix) ? local.slice(prefix.length) : "";
+        return Boolean(child) && !child.includes("/");
+    }) ?? false;
+}
 function manifestAt(directory) {
     const path = resolve(directory, "package.json");
     if (!existsSync(path))
@@ -61,26 +111,53 @@ function manifestAt(directory) {
         return null;
     }
 }
-function packageManager(directory, declared) {
+function packageManagerName(declared) {
     const named = declared?.split("@")[0];
-    if (named === "bun")
-        return { name: "bun", args: ["add", "--dev"] };
-    if (named === "pnpm")
-        return { name: "pnpm", args: ["add", "--save-dev"] };
-    if (named === "yarn")
-        return { name: "yarn", args: ["add", "--dev"] };
-    if (named === "npm")
-        return { name: "npm", args: ["install", "--save-dev", "--no-fund", "--no-audit"] };
+    return isPackageManager(named) ? named : undefined;
+}
+function packageManagerFromLocks(directory) {
     if (existsSync(resolve(directory, "bun.lock")) || existsSync(resolve(directory, "bun.lockb")))
-        return { name: "bun", args: ["add", "--dev"] };
+        return "bun";
     if (existsSync(resolve(directory, "pnpm-lock.yaml")))
-        return { name: "pnpm", args: ["add", "--save-dev"] };
+        return "pnpm";
     if (existsSync(resolve(directory, "yarn.lock")))
-        return { name: "yarn", args: ["add", "--dev"] };
-    return { name: "npm", args: ["install", "--save-dev", "--no-fund", "--no-audit"] };
+        return "yarn";
+    if (existsSync(resolve(directory, "package-lock.json")))
+        return "npm";
+}
+function packageManagerFromInvocation() {
+    const named = process.env.npm_config_user_agent?.split("/")[0];
+    return isPackageManager(named) ? named : undefined;
+}
+function isPackageManager(value) {
+    return value === "bun" || value === "npm" || value === "pnpm" || value === "yarn";
 }
 const localDirectories = {
     "@phreshos/core": "core-sdk",
     "@phreshos/client": "client-sdk",
-    "@phreshos/server": "server-sdk"
+    "@phreshos/server": "server-sdk",
+    "@phreshos/react": "react-sdk",
+    "@phreshos/cli": "cli"
+};
+const managers = {
+    bun: {
+        name: "bun",
+        installArgs: ["install"],
+        addArgs: section => ["add", ...section === "devDependencies" ? ["--dev"] : []]
+    },
+    npm: {
+        name: "npm",
+        installArgs: ["install", "--no-fund", "--no-audit"],
+        addArgs: section => ["install", ...section === "devDependencies" ? ["--save-dev"] : ["--save"], "--no-fund", "--no-audit"]
+    },
+    pnpm: {
+        name: "pnpm",
+        installArgs: ["install"],
+        addArgs: section => ["add", ...section === "devDependencies" ? ["--save-dev"] : ["--save-prod"]]
+    },
+    yarn: {
+        name: "yarn",
+        installArgs: ["install"],
+        addArgs: section => ["add", ...section === "devDependencies" ? ["--dev"] : []]
+    }
 };

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

@@ -0,0 +1,28 @@
+# 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
+state.
+
+```bash
+bun install
+bun phresh dev
+```
+
+Development starts the Server source and Vite Client together. For the
+production shape, build and attach the Program with:
+
+```bash
+bun phresh start
+```
+
+The structure follows the endpoint boundaries directly:
+
+```text
+source/
+├── client/   React interface
+└── server/   authoritative counter and API
+```
+
+The Program declaration lives in `phresh.config.ts`. Its own service contract
+is documented in `api-docs.md`.

package/dist/template/api-docs.md

@@ -0,0 +1,38 @@
+# Counter API
+
+The Server owns one number for the lifetime of its Process.
+
+| Name | Destination | Interaction | Payload | Answer |
+| --- | --- | --- | --- | --- |
+| `read` | Server | `ask()` | `undefined` | `number` |
+| `increment` | Server | `publish()` | `undefined` | None |
+| `changed` | Server | `subscribe()` | `number` | None |
+
+## Ask the Server: `read`
+
+`read` is a question addressed to this Process's Server. It answers with the
+current counter value.
+
+```ts
+const count = await process.server.ask<number>("read")
+```
+
+## Publish to the Server: `increment`
+
+`increment` is a one-way event addressed to this Process's Server. It adds one
+to the counter and does not produce an answer.
+
+```ts
+process.server.publish("increment")
+```
+
+## Subscribe to the Server: `changed`
+
+After an increment, the Server emits `changed` with the new counter value.
+Anyone holding that Process's Server can subscribe to the event.
+
+```ts
+process.server.subscribe<number>("changed", count => {
+  // use the latest count
+})
+```

package/dist/template/gitignore

@@ -0,0 +1,30 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Made by `phresh pack` in the project root.
+/*.zip
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Made by the system the first time this program runs.
+storage

package/dist/template/package.json

@@ -0,0 +1,28 @@
+{
+    "name": "phresh-program",
+    "private": true,
+    "version": "0.1.0",
+    "type": "module",
+    "scripts": {
+        "dev": "phresh dev",
+        "start": "phresh start"
+    },
+    "dependencies": {
+        "@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.5",
+        "@types/node": "^26.2.0",
+        "@types/react": "^19.2.18",
+        "@types/react-dom": "^19.2.4",
+        "@vitejs/plugin-react": "^6.0.5",
+        "tsx": "^4.23.12",
+        "typescript": "^7.0.2",
+        "vite": "^8.2.1"
+    }
+}

package/dist/template/phresh.config.ts

@@ -0,0 +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({
+
+    // 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 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",
+
+    // 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",
+
+    // One authored PNG. Installation gives it a canonical name and the system
+    // derives the standard hosted icon sizes from it.
+    icon: "icon.png",
+
+    // 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: {
+
+        // Production directory containing the Server artifact. The start
+        // command runs with this directory as its working directory.
+        location: "dist/server",
+        startCommand: "node main.js",
+
+        // 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",
+
+        // 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: {
+
+            // `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: {
+
+        // Production directory containing the browser application's
+        // `index.html` and all files reachable from it.
+        location: "dist/client",
+
+        // 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 },
+
+        // 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 },
+
+        // `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: {
+
+            // 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 --config vite.client.ts"
+        }
+    }
+})

package/dist/template/source/build.ts

@@ -0,0 +1,17 @@
+import { externalDependencies } from "@/vite.server"
+import { writeFile } from "node:fs/promises"
+import packageConfig from "@/package.json"
+import { build } from "vite"
+
+const dependencies: Partial<typeof packageConfig.dependencies> = {}
+
+for (const externalDependency of externalDependencies) {
+
+    dependencies[externalDependency] = packageConfig.dependencies[externalDependency]
+}
+
+await build({ configFile: "vite.server.ts" })
+
+await build({ configFile: "vite.client.ts" })
+
+await writeFile("dist/server/package.json", JSON.stringify({ type: "module", dependencies }))

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

@@ -0,0 +1,36 @@
+import { useSubscribe } from "@phreshos/react"
+import { useEffect, useState } from "react"
+import { current } from "@phreshos/client"
+
+function Counter() {
+
+    const [count, setCount] = useState<number>()
+
+    useSubscribe(current.server, "changed", setCount)
+
+    useEffect(function () {
+
+        current.server.ask<number>("read").then(setCount)
+
+    }, [])
+
+    return <main className="counter-card">
+
+        <span className="label">Phresh Program</span>
+
+        <h1>Server counter</h1>
+
+        <p>The value belongs to the Server and is shared with every Client representation.</p>
+
+        <button type="button" onClick={() => current.server.publish("increment")}>
+
+            count is {count ?? "…"}
+
+        </button>
+
+    </main>
+}
+
+export default function App() {
+    return <Counter />
+}

package/dist/template/source/client/dec.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />