@phreshos/cli 0.1.3 → 0.1.4

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 Get Started project. Get Started is the only authored template:
+the CLI build copies a filtered snapshot into the package, excluding build
+output, storage, installed modules, lockfiles, and archives. The installed CLI
+therefore creates projects offline without cloning a repository 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. When the CLI
+runs from this repository, generated SDK dependencies point to the sibling
+dev-kits; a distributed CLI keeps the published versions embedded in its
+template. Both choices pass through the same dependency resolver used by
+`init`.
+
 ## Saying something to a program you start
 
 ```bash

package/dist/build-template.js

@@ -0,0 +1,59 @@
+import { cpSync, existsSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, relative, resolve, sep } from "node:path";
+const source = resolve(import.meta.dirname, "..", "..", "get-started");
+const output = resolve(import.meta.dirname, "template");
+const excludedDirectories = new Set(["dist", "node_modules", "storage"]);
+const excludedFiles = new Set([
+    ".DS_Store",
+    "bun.lock",
+    "bun.lockb",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock"
+]);
+if (!existsSync(source))
+    throw new Error(`The Get Started source is not there: ${source}`);
+rmSync(output, { recursive: true, force: true });
+cpSync(source, output, { recursive: true, filter: included });
+renameSync(resolve(output, ".gitignore"), resolve(output, "gitignore"));
+const manifestPath = resolve(output, "package.json");
+const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+const versions = workspaceVersions();
+for (const dependencies of [manifest.dependencies, manifest.devDependencies]) {
+    if (!dependencies)
+        continue;
+    for (const [name, range] of Object.entries(dependencies)) {
+        if (!range.startsWith("workspace:"))
+            continue;
+        const version = versions.get(name);
+        if (!version)
+            throw new Error(`The template depends on ${name}, but no matching workspace package exists`);
+        dependencies[name] = `^${version}`;
+    }
+}
+writeFileSync(manifestPath, JSON.stringify(manifest, null, 4) + "\n");
+function included(path) {
+    const local = relative(source, path);
+    if (!local)
+        return true;
+    const parts = local.split(sep);
+    if (parts.some(part => excludedDirectories.has(part)))
+        return false;
+    const name = basename(path);
+    return !excludedFiles.has(name) && !name.endsWith(".zip");
+}
+function workspaceVersions() {
+    const versions = new Map();
+    const devKit = resolve(source, "..");
+    for (const entry of readdirSync(devKit, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const path = resolve(devKit, entry.name, "package.json");
+        if (!existsSync(path))
+            continue;
+        const manifest = JSON.parse(readFileSync(path, "utf-8"));
+        if (manifest.name && manifest.version)
+            versions.set(manifest.name, manifest.version);
+    }
+    return versions;
+}

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { bold, dim, heading } from "./style.js";
 import metadata from "../package.json" with { type: "json" };
+import create from "./create.js";
 import install from "./install.js";
 import launch from "./launch.js";
 import init from "./init.js";
@@ -16,6 +17,30 @@ const coreRange = metadata.dependencies["@phreshos/core"];
  * behavior belongs to the command that needs it; parsing never guesses.
  */
 const commands = [
+    {
+        name: "create",
+        summary: "create a new Program project",
+        detail: [
+            "Creates a complete Server and Client project from the maintained",
+            "Get Started template bundled with this CLI.",
+            "",
+            "In a terminal, an omitted directory and the readable Program name",
+            "are collected interactively. Automation supplies the directory as",
+            "the first argument and may use named options."
+        ],
+        positionals: [{ name: "directory", required: false }],
+        options: [
+            { name: "name", value: "name", summary: "human-readable Program name" },
+            { name: "package-manager", value: "manager", summary: "bun, npm, pnpm, or yarn" },
+            { name: "no-install", summary: "create files without installing dependencies" }
+        ],
+        run: options => create({
+            directory: options.positionals[0],
+            name: text(options, "name"),
+            packageManager: packageManager(text(options, "package-manager")),
+            install: options["no-install"] !== true
+        })
+    },
     {
         name: "init",
         summary: "initialize an existing Program project",
@@ -150,7 +175,7 @@ catch (error) {
     process.exit(1);
 }
 function parse(command, args) {
-    const options = { run: {} };
+    const options = { run: {}, positionals: [] };
     for (let index = 0; index < args.length; index += 1) {
         const argument = args[index];
         if (command.runOptions && argument.startsWith(runOptionPrefix)) {
@@ -164,8 +189,13 @@ function parse(command, args) {
             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}"`);
+        if (!argument.startsWith("--")) {
+            const positional = command.positionals?.[options.positionals.length];
+            if (!positional)
+                throw new Error(`${command.name} takes no more positional arguments, and I was given "${argument}"`);
+            options.positionals.push(argument);
+            continue;
+        }
         const at = argument.indexOf("=");
         const name = argument.slice(2, at < 0 ? undefined : at);
         const declared = command.options?.find(option => option.name === name);
@@ -184,12 +214,20 @@ function parse(command, args) {
             throw new Error(`--${name} needs <${declared.value}>`);
         options[name] = value;
     }
+    const missing = command.positionals?.slice(options.positionals.length).find(positional => positional.required);
+    if (missing)
+        throw new Error(`${command.name} needs <${missing.name}>`);
     return options;
 }
 function text(options, name) {
     const value = options[name];
     return typeof value === "string" ? value : undefined;
 }
+function packageManager(value) {
+    if (value === undefined || value === "bun" || value === "npm" || value === "pnpm" || value === "yarn")
+        return value;
+    throw new Error(`--package-manager must be bun, npm, pnpm, or yarn; received "${value}"`);
+}
 function usage() {
     heading(`phresh ${version}`, "create and manage Programs");
     for (const command of commands)
@@ -199,7 +237,9 @@ function usage() {
     console.log("");
 }
 function about(command) {
-    heading(`phresh ${command.name}${command.options?.length || command.runOptions ? " [options]" : ""}`, command.summary);
+    const positionals = command.positionals?.map(positional => positional.required ? `<${positional.name}>` : `[${positional.name}]`).join(" ");
+    const signature = [`phresh ${command.name}`, positionals, command.options?.length || command.runOptions ? "[options]" : ""].filter(Boolean).join(" ");
+    heading(signature, command.summary);
     for (const said of command.detail)
         console.log(said ? `  ${said}` : "");
     if (command.options?.length || command.runOptions) {

package/dist/create.js

@@ -0,0 +1,130 @@
+import { projectDependency, installProjectDependencies, projectPackageManager } from "./project-dependency.js";
+import questions from "./questions.js";
+import { dim, heading, line } from "./style.js";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, relative, resolve } from "node:path";
+/** Creates a complete Program from the bundled Get Started snapshot. */
+export default async function create(options = {}, directory = process.cwd()) {
+    const prompts = questions();
+    try {
+        const requested = options.directory ?? (prompts.interactive
+            ? await prompts.ask("A new directory will contain the complete Server and Client project.", "Where should the Program be created?", "my-program")
+            : undefined);
+        if (!requested)
+            throw new Error("create needs a <directory> when no terminal is attached");
+        const target = resolve(directory, requested);
+        const identity = basename(target);
+        if (!programIdentity.test(identity))
+            throw new Error(`The directory name must be a kebab-case Program identity; received "${identity}"`);
+        if (existsSync(target))
+            throw new Error(`The destination already exists: ${target}`);
+        const name = options.name ?? (prompts.interactive
+            ? await prompts.ask("This name is shown to people; the directory name remains the Program identity.", "What name should people see?", title(identity))
+            : title(identity));
+        if (!name.trim())
+            throw new Error("--name must not be empty");
+        const install = options.install !== false;
+        const detected = projectPackageManager(directory).name;
+        const manager = options.packageManager ?? (install && prompts.interactive
+            ? packageManager(await prompts.ask("The generated project remains portable; this choice installs its dependencies now.", "Which package manager should be used?", detected))
+            : detected);
+        heading("Create Program", name);
+        line("identity", identity);
+        line("directory", target);
+        line("template", "Get Started");
+        if (install)
+            line("packages", manager);
+        console.log("");
+        const parent = dirname(target);
+        mkdirSync(parent, { recursive: true });
+        const staging = mkdtempSync(resolve(parent, `.${identity}-`));
+        try {
+            cpSync(template(), staging, { recursive: true });
+            renameSync(resolve(staging, "gitignore"), resolve(staging, ".gitignore"));
+            customize(staging, target, identity, name, manager);
+            if (install)
+                await installProjectDependencies(staging, manager);
+            renameSync(staging, target);
+        }
+        catch (error) {
+            rmSync(staging, { recursive: true, force: true });
+            throw error;
+        }
+        heading(name, "created");
+        line("directory", target);
+        line("packages", install ? "installed" : "not installed");
+        console.log("");
+        console.log(`  ${dim("Next:")} cd ${relative(directory, target) || "."}`);
+        if (!install)
+            console.log(`        ${manager} install`);
+        console.log("        phresh dev");
+        console.log("");
+    }
+    finally {
+        prompts.close();
+    }
+}
+function template() {
+    const candidates = [
+        resolve(import.meta.dirname, "template"),
+        resolve(import.meta.dirname, "..", "dist", "template")
+    ];
+    const found = candidates.find(existsSync);
+    if (!found)
+        throw new Error("The CLI template has not been built — run its build command and try again");
+    return found;
+}
+function customize(directory, finalDirectory, identity, name, manager) {
+    for (const path of textFiles(directory)) {
+        let content = readFileSync(path, "utf-8");
+        content = content.replaceAll("get-started", identity).replaceAll("Get Started", name);
+        if (basename(path) === "README.md") {
+            content = content
+                .replaceAll("bun install", `${manager} install`)
+                .replaceAll("bun phresh ", "phresh ");
+        }
+        writeFileSync(path, content);
+    }
+    const manifestPath = resolve(directory, "package.json");
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    manifest.name = identity;
+    for (const dependencies of [manifest.dependencies, manifest.devDependencies]) {
+        if (!dependencies)
+            continue;
+        for (const [dependency, range] of Object.entries(dependencies)) {
+            if (!isProjectPackage(dependency))
+                continue;
+            dependencies[dependency] = projectDependency(dependency, range, finalDirectory).manifestSpecifier;
+        }
+    }
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 4) + "\n");
+}
+function textFiles(directory) {
+    const files = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = resolve(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...textFiles(path));
+        else if (entry.isFile() && (textExtensions.has(extname(entry.name)) || textNames.has(entry.name)))
+            files.push(path);
+    }
+    return files;
+}
+function packageManager(value) {
+    if (value === "bun" || value === "npm" || value === "pnpm" || value === "yarn")
+        return value;
+    throw new Error(`The package manager must be bun, npm, pnpm, or yarn; received "${value}"`);
+}
+function isProjectPackage(value) {
+    return value === "@phreshos/core"
+        || value === "@phreshos/client"
+        || value === "@phreshos/server"
+        || value === "@phreshos/react"
+        || value === "@phreshos/cli";
+}
+function title(identity) {
+    return identity.split("-").map(word => word[0].toUpperCase() + word.slice(1)).join(" ");
+}
+const programIdentity = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const textExtensions = new Set([".css", ".html", ".json", ".md", ".ts", ".tsx"]);
+const textNames = new Set([".gitignore", "gitignore"]);

package/dist/init.js

@@ -1,8 +1,8 @@
 import {} from "@phreshos/core";
 import { configFile, readManifest } from "./project.js";
-import { bold, dim, heading, line } from "./style.js";
+import { dim, heading, line } from "./style.js";
 import ensureProjectDependency, { projectScript } from "./project-dependency.js";
-import { createInterface } from "node:readline/promises";
+import questions from "./questions.js";
 import { existsSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 /**
@@ -16,23 +16,11 @@ import { resolve } from "node:path";
 export default async function init(options = {}, directory = process.cwd(), coreRange = "^0.1.0") {
     const manifest = await readManifest(directory);
     const path = resolve(directory, configFile);
-    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const prompts = questions();
+    const { interactive, ask, yes } = prompts;
     const explicitShape = options.server === true || options.client === true;
     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(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");
-    }
     try {
         if (existsSync(path) && options.force !== true) {
             heading(configFile, "already initialized");
@@ -159,7 +147,7 @@ export default async function init(options = {}, directory = process.cwd(), core
             console.log("");
     }
     finally {
-        readline?.close();
+        prompts.close();
     }
 }
 function compose(config) {
@@ -184,8 +172,7 @@ function compose(config) {
         `import { defineConfig } from "@phreshos/core"`,
         "",
         "export default defineConfig({",
-        "",
-        blocks.filter(Boolean).join(",\n\n"),
+        blocks.filter(Boolean).join(",\n"),
         "})",
         ""
     ].join("\n");
@@ -200,9 +187,9 @@ function half(name, values) {
         if (typeof value === "string")
             return `        ${key}: ${JSON.stringify(value)}`;
         const nested = Object.entries(value).map(([nestedKey, nestedValue]) => `            ${nestedKey}: ${JSON.stringify(nestedValue)}`);
-        return `        ${key}: {\n\n${nested.join(",\n\n")}\n        }`;
+        return `        ${key}: {\n${nested.join(",\n")}\n        }`;
     });
-    return `    ${name}: {\n\n${inside.join(",\n\n")}\n    }`;
+    return `    ${name}: {\n${inside.join(",\n")}\n    }`;
 }
 function httpUrl(value) {
     try {

package/dist/project-dependency.js

@@ -1,51 +1,83 @@
 import { line } from "./style.js";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { 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 CLI running from this repository uses its sibling dev-kit. A distributed
+ * CLI has no such sibling and keeps the published range embedded in its
+ * generated template.
  */
-export default async function ensureProjectDependency(name, range, directory = process.cwd()) {
+export function projectDependency(name, range, directory) {
+    const workspace = manifestAt(resolve(import.meta.dirname, "..", "..", ".."));
+    const sourceDirectory = resolve(import.meta.dirname, "..", "..", localDirectories[name]);
+    const manifest = manifestAt(sourceDirectory);
+    if (workspace?.name === "@phreshos/workspace" && manifest?.name === name && manifest.version && accepts(range, manifest.version)) {
+        const local = relative(directory, sourceDirectory).replaceAll("\\", "/") || ".";
+        return {
+            installSpecifier: sourceDirectory,
+            manifestSpecifier: `file:${local}`,
+            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) {
+    const manifest = manifestAt(directory);
+    const manager = projectPackageManager(directory, manifest?.packageManager, preferred);
+    await run(manager.name, manager.installArgs, directory);
+    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) {
+    return new Promise(function (settle, refuse) {
+        const child = spawn(command, args, {
             cwd: directory,
             stdio: "inherit",
             shell: process.platform === "win32"
         });
-        child.once("error", error => refuse(new Error(`Could not run ${manager.name}: ${error.message}`)));
+        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}`));
             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}`;
@@ -61,26 +93,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/questions.js

@@ -0,0 +1,25 @@
+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/template/README.md

@@ -0,0 +1,28 @@
+# Get Started
+
+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,27 @@
+{
+    "name": "get-started",
+    "private": true,
+    "version": "0.1.0",
+    "type": "module",
+    "scripts": {
+        "phresh": "phresh"
+    },
+    "dependencies": {
+        "@phreshos/client": "^0.1.0",
+        "@phreshos/react": "^0.1.0",
+        "@phreshos/server": "^0.1.0",
+        "@phreshos/core": "^0.1.0",
+        "react": "^19.2.8",
+        "react-dom": "^19.2.8"
+    },
+    "devDependencies": {
+        "@phreshos/cli": "^0.1.4",
+        "@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,69 @@
+import { defineConfig } from "@phreshos/core"
+
+export default defineConfig({
+
+    // The stable, kebab-case address used by programs and the system.
+    identity: "get-started",
+
+    // Human-facing details shown by the desktop and development tools.
+    name: "Get Started",
+    description: "A simple counter whose state lives on the Server.",
+    version: "0.1.0",
+
+    // The official entry point for this Program's own API.
+    apiDocs: "api-docs.md",
+
+    // A directory containing files named by size, such as 128x128.png.
+    icons: "icons",
+
+    // Runs before production start, install, and pack; dev uses the
+    // development declarations below instead.
+    buildCommand: "node --import tsx source/build.ts",
+
+    server: {
+
+        // The built server directory and the command run from within it.
+        location: "dist/server",
+        startCommand: "node main.js",
+
+        // Optional preparation performed once before the installed server
+        // first starts. This bundled example does not need it.
+        // installCommand: "npm install",
+
+        // A declared half starts by default. Set this to false when it
+        // should exist but only be included when explicitly requested.
+        // start: false,
+
+        development: {
+
+            // Development server commands run from the project root.
+            startCommand: "node --watch --import tsx source/server/main.ts"
+        }
+    },
+
+    client: {
+
+        // The directory containing the built browser application.
+        location: "dist/client",
+
+        title: "Get Started",
+        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.
+        // size: { width: "50% + 20", height: 440 },
+        // position: { x: "1/2 + 10", y: 40 },
+        // layer: "window", // "under" and "over" are frameless desktop layers.
+        // minimize: true,
+
+        development: {
+
+            // The CLI starts this command, then waits for the URL before it
+            // launches the development Program.
+            url: "http://localhost:5200/",
+            startCommand: "vite dev"
+        }
+    }
+})

package/dist/template/source/build.ts

@@ -0,0 +1,17 @@
+import { externalDependencies } from "@/vite.config"
+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({ build: { ssr: true } })
+
+await build()
+
+await writeFile("dist/server/package.json", JSON.stringify({ type: "module", dependencies }))

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

@@ -0,0 +1,41 @@
+import { CurrentProvider, 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">Get Started</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 <CurrentProvider waitServer fallback={<main className="loading">Connecting to the Server…</main>}>
+
+        <Counter />
+
+    </CurrentProvider>
+}

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

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

package/dist/template/source/client/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <script type="module" src="./main.tsx"></script>
+</head>
+
+<body>
+</body>
+
+</html>

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

@@ -0,0 +1,8 @@
+import client from "react-dom/client"
+import { StrictMode } from "react"
+import App from "./app"
+import "./style.css"
+
+const root = client.createRoot(document.body)
+
+root.render(<StrictMode><App /></StrictMode>)

package/dist/template/source/client/style.css

@@ -0,0 +1,81 @@
+:root {
+    color: #20242a;
+    background: #f3f4f6;
+    font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    font-synthesis: none;
+}
+
+* { box-sizing: border-box; }
+
+html, body, #root { min-height: 100vh; display: grid; }
+
+body { margin: 0; }
+
+button { font: inherit; }
+
+#root {
+    min-height: 100vh;
+    display: grid;
+    place-items: center;
+    padding: 1.5rem;
+}
+
+.counter-card {
+    width: min(26rem, 100%);
+    display: grid;
+    justify-items: start;
+    gap: 1rem;
+    padding: 2rem;
+    border: 1px solid #d8dce2;
+    border-radius: 0.75rem;
+    background: #ffffff;
+    margin: auto;
+}
+
+.label {
+    color: #646b76;
+    font-size: 0.72rem;
+    font-weight: 700;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+}
+
+h1 {
+    margin: 0;
+    font-size: 2rem;
+    line-height: 1.1;
+    letter-spacing: -0.04em;
+}
+
+p {
+    margin: 0;
+    color: #5f6670;
+    font-size: 0.95rem;
+    line-height: 1.55;
+}
+
+.counter-card button {
+    min-width: 9rem;
+    min-height: 2.75rem;
+    padding: 0.65rem 1rem;
+    border: 0;
+    border-radius: 0.5rem;
+    color: #ffffff;
+    background: #2563eb;
+    cursor: pointer;
+    font-weight: 650;
+}
+
+.counter-card button:hover { background: #1d4ed8; }
+
+.counter-card button:active { background: #1e40af; }
+
+.counter-card button:focus-visible {
+    outline: 3px solid rgba(37, 99, 235, 0.25);
+    outline-offset: 2px;
+}
+
+.loading {
+    color: #646b76;
+    font-size: 0.9rem;
+}

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

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

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

@@ -0,0 +1,14 @@
+import { current } from "@phreshos/server"
+
+// The Server owns the value. Every Client representation reads and changes
+// this same state instead of keeping an independent browser counter.
+let count = 0
+
+current.answer("read", () => count)
+
+current.subscribe("increment", function () {
+
+    count += 1
+
+    current.publish("changed", count)
+})

package/dist/template/tsconfig.json

@@ -0,0 +1,24 @@
+{
+    "compilerOptions": {
+        "moduleResolution": "bundler",
+        "noUnusedParameters": true,
+        "noUnusedLocals": true,
+        "skipLibCheck": true,
+        "module": "ESNext",
+        "target": "ESNext",
+        "jsx": "react-jsx",
+        "strict": true,
+        "noEmit": true,
+        "paths": {
+            "@/*": [
+                "./*"
+            ],
+            "@server/*": [
+                "./source/server/*"
+            ],
+            "@client/*": [
+                "./source/client/*"
+            ]
+        }
+    }
+}

package/dist/template/vite.config.ts

@@ -0,0 +1,38 @@
+import packageConfig from "./package.json" with { type: "json" }
+import react from "@vitejs/plugin-react"
+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(function (config) {
+
+    return {
+        base: "./",
+        resolve: {
+            tsconfigPaths: true,
+            dedupe: ["react"]
+        },
+        server: {
+            cors: true,
+            port: 5200,
+            strictPort: true
+        },
+        root: config.isSsrBuild ? "source/server" : "source/client",
+        plugins: config.isSsrBuild ? [] : [react()],
+        ssr: {
+            noExternal: true,
+            external: externalDependencies
+        },
+        build: {
+            emptyOutDir: true,
+            rolldownOptions: {
+                input: config.isSsrBuild ? "main.ts" : "index.html"
+            },
+            outDir: resolve(import.meta.dirname, config.isSsrBuild ? "dist/server" : "dist/client"),
+        }
+    }
+})

package/package.json

@@ -1,10 +1,11 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.3",
+    "version": "0.1.4",
     "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",
+        "compile": "tsc --noEmit false --outDir dist --rootDir source --rewriteRelativeImportExtensions true --allowImportingTsExtensions true",
+        "build": "node --run compile && node dist/build-template.js",
         "prepack": "node --run build"
     },
     "bin": {