@phreshos/cli 0.1.13 → 0.1.15

package/README.md

@@ -78,10 +78,11 @@ Windows; neither becomes a network endpoint or introduces a bearer secret.
 
 `phresh create <directory>` creates a complete Server and Client Program from
 the maintained `PhreshOS/phresh-program` repository. The CLI build downloads
-one exact tagged source release, verifies its SHA-256 checksum, removes
-repository-only material, and bundles the resulting authoring project. The
-installed CLI therefore creates projects offline without reading a live branch
-or maintaining a second template by hand.
+the newest complete stable release, validates its source identity and version,
+removes repository-only material, and bundles that exact authoring project.
+The resolved source digest is recorded with the bundle. The installed CLI
+therefore creates projects offline without reading a live branch or maintaining
+a release pin or 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

package/dist/program-release.js

@@ -4,16 +4,6 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import AdmZip from "adm-zip";
-const officialPrograms = {
-    phresh: {
-        identity: "phresh-program",
-        repository: "PhreshOS/phresh-program"
-    },
-    setup: {
-        identity: "setup",
-        repository: "PhreshOS/setup-program"
-    }
-};
 /** Resolve, verify, and unpack one official production Program release. */
 export async function prepareOfficialProgram(name, fetcher = fetch) {
     const release = await resolveOfficialProgramRelease(name, fetcher);
@@ -34,10 +24,8 @@ export async function prepareOfficialProgram(name, fetcher = fetch) {
     }
 }
 export async function resolveOfficialProgramRelease(name, fetcher = fetch) {
-    const official = officialPrograms[name];
-    if (!official)
-        throw new Error(`No official Program is named "${name}"`);
-    const response = await fetcher(`https://api.github.com/repos/${official.repository}/releases?per_page=100`, {
+    const requested = programName(name);
+    const response = await fetcher(`https://api.github.com/repos/PhreshOS/${requested}-program/releases?per_page=100`, {
         headers: {
             Accept: "application/vnd.github+json",
             "User-Agent": "@phreshos/cli"
@@ -46,26 +34,24 @@ export async function resolveOfficialProgramRelease(name, fetcher = fetch) {
     });
     if (!response.ok)
         throw new Error(`The ${name} release list could not be read (${response.status} ${response.statusText})`);
-    return selectProgramRelease(official.identity, await response.json());
+    return selectProgramRelease(await response.json());
 }
-export function selectProgramRelease(identity, value) {
+export function selectProgramRelease(value) {
     if (!Array.isArray(value))
-        throw new Error(`The ${identity} release list is invalid`);
+        throw new Error("The Program release list is invalid");
     const releases = value.flatMap(function (item) {
         if (!record(item) || item.draft === true || item.prerelease === true || typeof item.tag_name !== "string" || !Array.isArray(item.assets))
             return [];
         const version = parseVersion(item.tag_name);
         if (!version)
             return [];
-        const archiveName = `${identity}@${version}.zip`;
-        const archive = asset(item.assets, archiveName);
-        const checksum = asset(item.assets, `${archiveName}.sha256`);
-        return archive && checksum ? [{ identity, version, archive, checksum }] : [];
+        const files = programAssets(item.assets, version);
+        return files ? [{ version, ...files }] : [];
     });
     releases.sort((left, right) => compare(right.version, left.version));
     const selected = releases[0];
     if (!selected)
-        throw new Error(`No stable ${identity} Program release is available`);
+        throw new Error("No stable Program release is available");
     return selected;
 }
 export async function downloadProgramRelease(release, fetcher = fetch) {
@@ -150,6 +136,27 @@ function asset(assets, name) {
     const found = assets.find(item => record(item) && item.name === name && typeof item.browser_download_url === "string");
     return record(found) && typeof found.browser_download_url === "string" ? found.browser_download_url : undefined;
 }
+function programAssets(assets, version) {
+    const suffix = `@${version}.zip`;
+    const archives = assets.flatMap(function (item) {
+        if (!record(item) || typeof item.name !== "string" || typeof item.browser_download_url !== "string" || !item.name.endsWith(suffix))
+            return [];
+        const identity = item.name.slice(0, -suffix.length);
+        if (!validProgramName(identity))
+            return [];
+        const checksum = asset(assets, `${item.name}.sha256`);
+        return checksum ? [{ identity, archive: item.browser_download_url, checksum }] : [];
+    });
+    return archives.length === 1 ? archives[0] : undefined;
+}
+function programName(name) {
+    if (!validProgramName(name))
+        throw new Error(`The official Program name "${name}" is invalid`);
+    return name;
+}
+function validProgramName(name) {
+    return name.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+}
 function parseVersion(tag) {
     const match = /^v(\d+)\.(\d+)\.(\d+)$/.exec(tag);
     return match ? tag.slice(1) : undefined;

package/dist/style.js

@@ -19,7 +19,6 @@ export function column(label) {
     return label.length < 12 ? label.padEnd(12) : `${label} `;
 }
 export function heading(title, note) {
-    console.log("");
     section(title, note);
     console.log("");
 }

package/dist/template/README.md

@@ -16,13 +16,18 @@ production shape, build and attach the Program with:
 bun phresh start
 ```
 
-The structure follows the endpoint boundaries directly:
+The structure keeps composition, representation, and authoritative behavior distinct:
 
 ```text
 source/
-├── client/   React interface
-└── server/   authoritative counter and API
+├── client/
+│   ├── main.tsx   Client composition
+│   └── view/      React representation
+└── server/
+    ├── main.ts    Server composition
+    ├── core/      authoritative counter
+    └── view/      endpoint adapter and service exposure
 ```
 
 The Program declaration lives in `phresh.config.ts`. Its own service contract
-is documented in `api-docs.md`.
+is exposed as the `counter` Server service and documented in `api-docs.md`.

package/dist/template/api-docs.md

@@ -1,6 +1,6 @@
 # Counter API
 
-The Server owns one number for the lifetime of its Process.
+The `counter` Server service owns one number for the lifetime of its Process.
 
 | Name | Destination | Interaction | Payload | Answer |
 | --- | --- | --- | --- | --- |
@@ -14,7 +14,13 @@ The Server owns one number for the lifetime of its Process.
 current counter value.
 
 ```ts
-const count = await process.server.ask<number>("read")
+const counter = host.service({
+  program: "phresh-program",
+  endpoint: "server",
+  name: "counter"
+})
+
+const count = await counter.channel.ask<number>("read")
 ```
 
 ## Publish to the Server: `increment`
@@ -23,7 +29,7 @@ const count = await process.server.ask<number>("read")
 to the counter and does not produce an answer.
 
 ```ts
-process.server.publish("increment")
+counter.channel.publish("increment")
 ```
 
 ## Subscribe to the Server: `changed`
@@ -32,7 +38,7 @@ 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 => {
+counter.channel.subscribe<number>("changed", count => {
   // use the latest count
 })
 ```

package/dist/template/gitignore

@@ -1,31 +1,19 @@
 # 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
 /*.zip.sha256
 
-# Editor directories and files
-.vscode/*
-!.vscode/extensions.json
+# Editor and machine residue.
+.vscode
 .idea
 .DS_Store
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?
 
-# Made by the system the first time this program runs.
+# Made by the system the first time this Program runs.
 storage

package/dist/template/package.json

@@ -1,28 +1,34 @@
 {
     "name": "phresh-program",
     "private": true,
-    "version": "0.1.2",
+    "version": "0.1.6",
+    "description": "The official PhreshOS starter Program.",
     "type": "module",
     "scripts": {
         "dev": "phresh dev",
         "start": "phresh start"
     },
+    "keywords": [
+        "phreshos",
+        "program",
+        "starter"
+    ],
     "dependencies": {
-        "@phreshos/client": "^0.1.1",
-        "@phreshos/react": "^0.1.1",
-        "@phreshos/server": "^0.1.1",
-        "@phreshos/core": "^0.1.1",
+        "@phreshos/client": "^0.1.9",
+        "@phreshos/core": "^0.1.6",
+        "@phreshos/react": "^0.1.5",
+        "@phreshos/server": "^0.1.7",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.13",
+        "@phreshos/cli": "^0.1.15",
         "@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"
+        "vite": "^8.2.1",
+        "vite-node": "^6.0.0"
     }
 }

package/dist/template/phresh.config.ts

@@ -22,12 +22,7 @@ export default defineConfig({
     // these values determines the Program's identity.
     name: "Phresh Program",
     description: "A simple counter whose state lives on the Server.",
-    version: "0.1.2",
-
-    // 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",
+    version: "0.1.6",
 
     // One authored PNG. Installation gives it a canonical name and the system
     // derives the standard hosted icon sizes from it.
@@ -36,7 +31,7 @@ export default defineConfig({
     // 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",
+    buildCommand: "vite-node scripts/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
@@ -62,8 +57,8 @@ export default defineConfig({
 
             // `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"
+            // source imports work without a production build.
+            startCommand: "vite-node source/server/main.ts"
         }
     },
 

package/dist/template/{source → scripts}/build.ts

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

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

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

package/dist/template/source/server/core/counter.ts

@@ -0,0 +1,13 @@
+/** Owns the Program's authoritative counter state without knowing how it is exposed. */
+export default class Counter {
+  private value = 0
+
+  public read() {
+    return this.value
+  }
+
+  public increment() {
+    this.value += 1
+    return this.value
+  }
+}

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

@@ -1,14 +1,3 @@
-import { current } from "@phreshos/server"
+import view from "./view/view"
 
-// 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", async function () {
-
-    count += 1
-
-    current.publish("changed", count)
-})
+await view()

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

@@ -0,0 +1,16 @@
+import { current } from "@phreshos/server"
+import docs from "@/api-docs.md?raw"
+import Counter from "@server/core/counter"
+
+const counter = new Counter()
+
+/** Exposes the counter core through this Server endpoint. */
+export default async function view() {
+  current.answer("read", () => counter.read())
+
+  current.subscribe("increment", () => {
+    current.publish("changed", counter.increment())
+  })
+
+  await current.enableService({ name: "counter", docs })
+}

package/dist/template/tsconfig.json

@@ -9,6 +9,10 @@
         "jsx": "react-jsx",
         "strict": true,
         "noEmit": true,
+        "types": [
+            "@types/node",
+            "vite/client"
+        ],
         "paths": {
             "@/*": [
                 "./*"

package/dist/template/{vite.server.ts → vite.config.ts}

@@ -13,7 +13,6 @@ export default defineConfig({
         tsconfigPaths: true
     },
     ssr: {
-        noExternal: true,
         external: externalDependencies
     },
     build: {
@@ -24,4 +23,4 @@ export default defineConfig({
             input: "main.ts"
         }
     }
-})
+})

package/dist/template.json

@@ -1,5 +1,6 @@
 {
     "repository": "PhreshOS/phresh-program",
-    "version": "0.1.2",
+    "version": "0.1.6",
+    "sha256": "a56227927522a550ef5dab3eb5127274e23ecd9c0dabb912f8b46f37990a9602",
     "development": true
 }

package/package.json

@@ -1,17 +1,18 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-  "version": "0.1.13",
+    "version": "0.1.15",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"
     },
     "scripts": {
         "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+        "check:scripts": "tsc --project tsconfig.scripts.json",
         "compile": "tsc --noEmit false --outDir dist --rootDir source --rewriteRelativeImportExtensions true --allowImportingTsExtensions true",
-        "build": "node --run clean && node --run compile && node dist/build-template.js",
+        "build": "node --run clean && node --run compile && vite-node scripts/build-template.ts",
         "test": "node --run compile && node --test tests/*.test.mjs",
-        "verify": "node --run build && node --run test && node scripts/verify-package.mjs",
+        "verify": "node --run check:scripts && node --run build && node --run test && node scripts/verify-package.mjs",
         "verify:system-release": "node --run compile && node scripts/verify-system-release.mjs",
         "verify:linux-service": "node --run compile && node scripts/verify-linux-service.mjs",
         "verify:macos-service": "node --run compile && node scripts/verify-macos-service.mjs",
@@ -56,6 +57,7 @@
     "devDependencies": {
         "@types/adm-zip": "^0.5.8",
         "@types/node": "^25.9.5",
-        "typescript": "^6.0.3"
+        "typescript": "^6.0.3",
+        "vite-node": "^6.0.0"
     }
 }

package/dist/build-template.js

@@ -1,90 +0,0 @@
-import metadata from "../package.json" with { type: "json" };
-import { createHash } from "node:crypto";
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
-import AdmZip from "adm-zip";
-import { readConfig } from "./project.js";
-const repository = "PhreshOS/phresh-program";
-const release = {
-    version: "0.1.2",
-    sha256: "dba5f1fd868c46501d5bd3463f4f8f0e098c7a231cb75794c01118689dc69339"
-};
-const archiveUrl = `https://github.com/${repository}/archive/refs/tags/v${release.version}.zip`;
-const output = resolve(import.meta.dirname, "template");
-const descriptionOutput = resolve(import.meta.dirname, "template.json");
-const excludedDirectories = new Set([".github", "dist", "node_modules", "scripts", "storage"]);
-const excludedRootFiles = new Set(["CONTRIBUTING.md", "LICENSE", "SECURITY.md"]);
-const excludedFiles = new Set([
-    ".DS_Store",
-    "bun.lock",
-    "bun.lockb",
-    "package-lock.json",
-    "pnpm-lock.yaml",
-    "yarn.lock"
-]);
-const response = await fetch(archiveUrl);
-if (!response.ok)
-    throw new Error(`Could not download ${repository} v${release.version}: ${response.status} ${response.statusText}`);
-const bytes = Buffer.from(await response.arrayBuffer());
-const digest = createHash("sha256").update(bytes).digest("hex");
-if (digest !== release.sha256)
-    throw new Error(`The ${repository} v${release.version} source archive failed integrity verification`);
-const archive = new AdmZip(bytes);
-const entries = archive.getEntries();
-const roots = new Set(entries.map(entry => entry.entryName.split("/")[0]).filter(Boolean));
-if (roots.size !== 1)
-    throw new Error(`The ${repository} v${release.version} source archive has an invalid root`);
-const root = [...roots][0];
-rmSync(output, { recursive: true, force: true });
-rmSync(descriptionOutput, { force: true });
-for (const entry of entries) {
-    if (entry.isDirectory || !entry.entryName.startsWith(`${root}/`))
-        continue;
-    const local = entry.entryName.slice(root.length + 1);
-    if (!included(local))
-        continue;
-    const target = local === ".gitignore" ? "gitignore" : local;
-    const path = resolve(output, target);
-    if (!path.startsWith(`${output}${sep}`))
-        throw new Error(`The ${repository} source archive contains an unsafe path: ${local}`);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, entry.getData());
-}
-const manifestPath = resolve(output, "package.json");
-const manifestSource = archive.readFile(`${root}/package.json`);
-if (!manifestSource)
-    throw new Error(`The ${repository} v${release.version} source archive has no package.json`);
-const manifest = JSON.parse(manifestSource.toString("utf8"));
-manifest.scripts = select(manifest.scripts, ["dev", "start"]);
-manifest.devDependencies = {
-    ...manifest.devDependencies,
-    "@phreshos/cli": `^${metadata.version}`
-};
-delete manifest.author;
-delete manifest.license;
-delete manifest.repository;
-delete manifest.bugs;
-delete manifest.homepage;
-delete manifest.packageManager;
-writeFileSync(manifestPath, JSON.stringify(manifest, null, 4) + "\n");
-const config = await readConfig(output);
-if (config.identity !== "phresh-program" || config.name !== "Phresh Program")
-    throw new Error(`The ${repository} release is not Phresh Program`);
-writeFileSync(descriptionOutput, JSON.stringify({
-    repository,
-    version: release.version,
-    development: Boolean(config.server?.development || config.client?.development)
-}, null, 4) + "\n");
-function included(local) {
-    const parts = local.split("/");
-    if (parts.some(part => excludedDirectories.has(part)))
-        return false;
-    if (parts.length === 1 && excludedRootFiles.has(local))
-        return false;
-    if (excludedFiles.has(parts.at(-1)))
-        return false;
-    return !local.endsWith(".zip");
-}
-function select(source, names) {
-    return Object.fromEntries(names.flatMap(name => source?.[name] === undefined ? [] : [[name, source[name]]]));
-}

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

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

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

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