@phreshos/cli 0.1.9 → 0.1.11

package/dist/build-template.js

@@ -6,8 +6,8 @@ import AdmZip from "adm-zip";
 import { readConfig } from "./project.js";
 const repository = "PhreshOS/phresh-program";
 const release = {
-    version: "0.1.0",
-    sha256: "6e1a87a037a6ac5f82ff4c7d420757f972098387d73a8b4165aab2ef331cec36"
+    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");

package/dist/cli.js

@@ -86,12 +86,16 @@ describe(program.command("pack")
     "declared for each endpoint."
 ]);
 describe(program.command("install")
-    .description("install this Program")
-    .action(async function () {
-    await install();
+    .description("install a local or official Program")
+    .argument("[name]", "name of an official Program")
+    .option("--run", "run the installed Program now")
+    .option("--startup", "run the Program when the System starts")
+    .action(async function (name, options) {
+    await install({ name, run: options.run === true, startup: options.startup === true });
 }), [
-    "Builds and installs the Program declared by this project. Running",
-    "Processes end before installed paths change; Program data is preserved."
+    "Without a name, builds and installs the Program declared by this project.",
+    "A name installs its verified official production release. --run launches",
+    "it now; --startup persists the same default launch for future starts."
 ]);
 describe(program.command("uninstall")
     .description("uninstall this Program")

package/dist/install.js

@@ -1,45 +1,51 @@
 import derive from "./derive.js";
 import { readConfig } from "./project.js";
-import { dim, heading } from "./style.js";
-import speak from "./program-intake.js";
+import { dim, heading, line } from "./style.js";
+import installProgram, {} from "./program-installation.js";
+import { prepareOfficialProgram } from "./program-release.js";
 import build from "./build-command.js";
 /**
  * Lay this program out on this machine's system.
  *
- * What is sent is the description the config derives — the same one
- * `phresh start` runs from — and the system copies what it names into
- * place. A program's parts are already on this disk at the locations it
- * names, so there is nothing an archive would carry that the description
- * does not already point at.
- *
- * **Installing takes no package, and neither does the system.** A
- * package is a way of *carrying* a program to another machine, which is
- * a different act from laying one out — and installing programs at all
- * is work for a program rather than for the core, so what a person
- * installs *from* is not this command's business either. `phresh pack`
- * makes a package when you have somewhere to send it, and stops there.
+ * A local project is built and derived from its authoring declaration. An
+ * official name resolves a verified production package and turns its
+ * canonical paths into the same concrete description. From that point on,
+ * both sources cross the exact same intake and the System performs the exact
+ * same authoritative installation.
  *
  * When the author config declares `buildCommand`, it runs here before the
  * production Program is derived and sent. The command remains authoring
  * metadata and never becomes part of the installed Program.
  *
- * Installing is not running. A program laid out here stays until
- * something removes it, and `phresh start` and `phresh dev` are for the
- * other way a program is used — attached to the terminal that began it,
- * and gone when that ends.
+ * Installation remains distinct from execution unless `run` or `startup`
+ * is explicitly requested. A run created here belongs to the installed
+ * Program and therefore outlives this command; `phresh start` and `phresh
+ * dev` remain attached authoring runs whose lifetime is the terminal's.
  */
-export default async function install(directory = process.cwd()) {
+export default async function install(options = {}) {
+    const directory = options.directory ?? process.cwd();
+    const prepared = options.name ? await prepareOfficialProgram(options.name) : null;
+    try {
+        const program = prepared?.program ?? await localProgram(directory);
+        const result = await installProgram(program, options);
+        if (options.announce !== false) {
+            const { name, identity, version } = result.program;
+            heading(`${name || identity}${version ? ` ${version}` : ""}`, result.replaced ? "reinstalled" : "installed");
+            if (result.replaced)
+                console.log(`  ${dim("its storage was kept, and its previous processes were ended")}\n`);
+            if (result.startupEnabled)
+                line("startup", "enabled");
+            if (result.process)
+                line("process", result.process);
+        }
+        return result;
+    }
+    finally {
+        await prepared?.dispose();
+    }
+}
+async function localProgram(directory) {
     const config = await readConfig(directory);
     await build(config, directory);
-    const program = derive(config, directory, "production");
-    await speak({ word: "install", program }, function (event) {
-        if (event.event !== "installed")
-            return;
-        const said = event.program;
-        heading(`${said.name ?? String(said.identity)}${said.version ? ` ${said.version}` : ""}`, event.replaced ? "reinstalled" : "installed");
-        // What it kept. Every process ended before the installed paths
-        // changed, while storage stayed in its canonical place.
-        if (event.replaced)
-            console.log(`  ${dim("its storage was kept, and its previous processes were ended")}\n`);
-    });
+    return derive(config, directory, "production");
 }

package/dist/pack.js

@@ -1,5 +1,6 @@
 import { readConfig, readManifest } from "./project.js";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import AdmZip from "adm-zip";
 import build from "./build-command.js";
@@ -47,7 +48,10 @@ export default async function pack(directory = process.cwd()) {
         document(zip, directory, config.apiDocs);
     zip.addFile("program.json", Buffer.from(JSON.stringify(program(config, version), null, 4) + "\n"));
     const archive = `${config.identity}@${version ?? "0.0.0"}.zip`;
-    zip.writeZip(resolve(directory, archive));
+    const bytes = zip.toBuffer();
+    writeFileSync(resolve(directory, archive), bytes);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    writeFileSync(resolve(directory, `${archive}.sha256`), `${digest}  ${archive}\n`);
     console.log(`\nPacked ${archive}`);
     return archive;
 }

package/dist/program-installation.js

@@ -0,0 +1,54 @@
+import speak from "./program-intake.js";
+/** Install one prepared Program and await every explicitly requested outcome. */
+export default async function installProgram(program, options = {}) {
+    let installedValue;
+    let replaced = false;
+    let startupEnabled = false;
+    let processValue;
+    await speak({
+        word: "install",
+        program,
+        run: options.run === true,
+        startup: options.startup === true
+    }, function (event) {
+        if (event.event === "installed") {
+            installedValue = event.program;
+            replaced = event.replaced === true;
+        }
+        else if (event.event === "startupEnabled")
+            startupEnabled = true;
+        else if (event.event === "running")
+            processValue = event.process;
+    });
+    if (installedValue === undefined)
+        throw new Error("The System ended Program installation without confirming it");
+    const installed = installedProgram(installedValue);
+    if (options.startup && !startupEnabled)
+        throw new Error("The System installed the Program without confirming startup");
+    const process = processValue === undefined ? null : processIdentity(processValue);
+    if (options.run && !process)
+        throw new Error("The System installed the Program without confirming that it is running");
+    return {
+        program: installed,
+        replaced,
+        startupEnabled,
+        process
+    };
+}
+function processIdentity(value) {
+    if (typeof value !== "string" || !value)
+        throw new Error("The System returned an invalid Process identity");
+    return value;
+}
+function installedProgram(value) {
+    if (!record(value)
+        || typeof value.identity !== "string"
+        || typeof value.name !== "string"
+        || value.version !== null && typeof value.version !== "string") {
+        throw new Error("The System returned an invalid installed Program");
+    }
+    return { identity: value.identity, name: value.name, version: value.version };
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/program-intake.js

@@ -14,10 +14,11 @@ import { isAbsolute, join } from "node:path";
  * question would make lifetime ambiguous. A line delimiter keeps the
  * connection available for the stream of events that follows a launch.
  *
- * One question, then events until the system closes. Installing and
- * uninstalling say one thing and end; running says one thing, then whatever
- * the Program says, then how it ended. None pretends to be a remote method
- * returning through an unrelated transport.
+ * One question, then events until the system closes. Installation confirms
+ * each requested outcome — laid out, startup enabled, running — and then
+ * ends. Uninstalling says one thing and ends; an attached run says how it
+ * began, whatever the Program says, and how it ended. None pretends to be a
+ * remote method returning through an unrelated transport.
  */
 export function programIntakePath(environment = process.env, userHome = homedir()) {
     const instanceHome = environment.PHRESHOS_HOME;

package/dist/program-release.js

@@ -0,0 +1,165 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+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);
+    const bytes = await downloadProgramRelease(release, fetcher);
+    const directory = await mkdtemp(join(tmpdir(), `phresh-${release.identity}-`));
+    try {
+        extract(bytes, directory);
+        const program = await readProgram(directory, release);
+        return {
+            program,
+            release,
+            dispose: async () => { await rm(directory, { recursive: true, force: true }); }
+        };
+    }
+    catch (error) {
+        await rm(directory, { recursive: true, force: true });
+        throw error;
+    }
+}
+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`, {
+        headers: {
+            Accept: "application/vnd.github+json",
+            "User-Agent": "@phreshos/cli"
+        },
+        signal: AbortSignal.timeout(30_000)
+    });
+    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());
+}
+export function selectProgramRelease(identity, value) {
+    if (!Array.isArray(value))
+        throw new Error(`The ${identity} 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 }] : [];
+    });
+    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`);
+    return selected;
+}
+export async function downloadProgramRelease(release, fetcher = fetch) {
+    const [archive, checksum] = await Promise.all([
+        fetchAsset(release.archive, fetcher),
+        fetchAsset(release.checksum, fetcher)
+    ]);
+    const bytes = Buffer.from(await archive.arrayBuffer());
+    const said = (await checksum.text()).trim();
+    const name = `${release.identity}@${release.version}.zip`;
+    const match = /^([a-f0-9]{64})\s+(.+)$/i.exec(said);
+    if (!match || match[2] !== name)
+        throw new Error(`The checksum for ${name} is invalid`);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== match[1]?.toLowerCase())
+        throw new Error(`The downloaded ${name} does not match its SHA-256 checksum`);
+    return bytes;
+}
+async function readProgram(directory, release) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(join(directory, "program.json"), "utf8"));
+    }
+    catch {
+        throw new Error(`The ${release.identity} Program package has no valid program.json`);
+    }
+    if (!record(value) || value.identity !== release.identity || value.version !== release.version) {
+        throw new Error(`The ${release.identity} Program package identity or version does not match its release`);
+    }
+    if (value.storage !== undefined)
+        throw new Error("A published Program package cannot choose its installed storage");
+    return {
+        ...value,
+        ...pathField(value, directory, "apiDocs", "api-docs.md"),
+        ...pathField(value, directory, "icon", "icon.png"),
+        ...half(value, directory, "server"),
+        ...half(value, directory, "client")
+    };
+}
+function half(value, directory, name) {
+    const declared = value[name];
+    if (declared === undefined)
+        return {};
+    if (!record(declared) || declared.location !== name)
+        throw new Error(`A published Program's ${name} must be packaged at ./${name}`);
+    return { [name]: { ...declared, location: join(directory, name) } };
+}
+function pathField(value, directory, field, canonical) {
+    const declared = value[field];
+    if (declared === undefined)
+        return {};
+    if (declared !== canonical)
+        throw new Error(`A published Program's ${field} must be packaged as ${canonical}`);
+    return { [field]: join(directory, canonical) };
+}
+function extract(bytes, directory) {
+    const archive = new AdmZip(bytes);
+    for (const entry of archive.getEntries()) {
+        const name = entry.entryName.replaceAll("\\", "/");
+        const destination = resolve(directory, name);
+        const within = relative(directory, destination);
+        if (!name || name.startsWith("/") || name.split("/").includes("..") || isAbsolute(within) || within.startsWith("..")) {
+            throw new Error(`The Program package contains an unsafe path: ${entry.entryName}`);
+        }
+        if (entry.isDirectory) {
+            mkdirSync(destination, { recursive: true, mode: 0o700 });
+            continue;
+        }
+        mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+        writeFileSync(destination, entry.getData(), { mode: 0o600 });
+    }
+}
+async function fetchAsset(url, fetcher) {
+    const response = await fetcher(url, {
+        headers: { "User-Agent": "@phreshos/cli" },
+        signal: AbortSignal.timeout(120_000)
+    });
+    if (!response.ok)
+        throw new Error(`A Program release asset could not be downloaded (${response.status} ${response.statusText})`);
+    return response;
+}
+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 parseVersion(tag) {
+    const match = /^v(\d+)\.(\d+)\.(\d+)$/.exec(tag);
+    return match ? tag.slice(1) : undefined;
+}
+function compare(left, right) {
+    const a = left.split(".").map(Number);
+    const b = right.split(".").map(Number);
+    return (a[0] ?? 0) - (b[0] ?? 0) || (a[1] ?? 0) - (b[1] ?? 0) || (a[2] ?? 0) - (b[2] ?? 0);
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/system/installation.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { mkdir, mkdtemp, open, readFile, readdir, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { requireSuccess } from "./process.js";
+import { minimumSystemNodeVersion } from "./node.js";
 import AdmZip from "adm-zip";
 /** Owns immutable release directories and the one atomic active record. */
 export default class SystemInstallation {
@@ -171,7 +172,13 @@ async function validateDistribution(directory) {
     catch {
         throw new Error("The System release has no valid production package manifest");
     }
-    if (!record(manifest) || manifest.type !== "module" || !record(manifest.scripts) || manifest.scripts.start !== "node server/main.js" || !record(manifest.dependencies)) {
+    if (!record(manifest)
+        || manifest.type !== "module"
+        || !record(manifest.scripts)
+        || manifest.scripts.start !== "node server/main.js"
+        || !record(manifest.engines)
+        || manifest.engines.node !== `>=${minimumSystemNodeVersion}`
+        || !record(manifest.dependencies)) {
         throw new Error("The System release package manifest is invalid");
     }
     for (const path of ["server/main.js", "client/index.html"]) {

package/dist/system/lifecycle.js

@@ -4,6 +4,7 @@ import { intakeReady, waitForIntake } from "./readiness.js";
 import systemPaths from "./paths.js";
 import systemService from "./service/index.js";
 import nodeExecutable from "./node.js";
+import installProgram from "../install.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 /** Coordinates acquisition, immutable files, and the native service as one transaction. */
@@ -18,7 +19,8 @@ export default class SystemLifecycle {
             resolveRelease: dependencies?.resolveRelease ?? resolveSystemRelease,
             downloadRelease: dependencies?.downloadRelease ?? downloadSystemRelease,
             ready: dependencies?.ready ?? intakeReady,
-            wait: dependencies?.wait ?? waitForIntake
+            wait: dependencies?.wait ?? waitForIntake,
+            provisionSetup: dependencies?.provisionSetup ?? provisionSetup
         };
     }
     async install() {
@@ -40,13 +42,24 @@ export default class SystemLifecycle {
             await service.start();
             await this.waitUntilReady();
             await activation.commit();
-            return await this.status();
         }
         catch (error) {
             await service.stop().catch(() => undefined);
             await activation.rollback();
             return await this.restoredFailure(error, previous, previousService);
         }
+        // The System transaction is complete before a Program crosses its
+        // live intake. A provisioning failure therefore leaves a healthy
+        // System available for a retry instead of rolling it back around a
+        // separate Program installation that may already have succeeded.
+        try {
+            await this.dependencies.provisionSetup();
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`The PhreshOS System is running, but Setup could not be provisioned: ${reason}`, { cause: error });
+        }
+        return await this.status();
     }
     async uninstall() {
         return await this.dependencies.installation.exclusive(() => this.uninstallExclusive());
@@ -168,6 +181,9 @@ export default class SystemLifecycle {
         throw error;
     }
 }
+async function provisionSetup() {
+    await installProgram({ name: "setup", run: true, startup: true, announce: false });
+}
 function definition(installation, executable) {
     return {
         executable,

package/dist/system/node.js

@@ -1,9 +1,28 @@
 import { isAbsolute } from "node:path";
 import { requireSuccess } from "./process.js";
+export const minimumSystemNodeVersion = "24.15.0";
 /** Resolve the real Node executable even when another runtime invoked the CLI. */
 export default async function nodeExecutable() {
-    if (!process.versions.bun && process.release.name === "node" && isAbsolute(process.execPath))
-        return process.execPath;
+    const executable = !process.versions.bun && process.release.name === "node" && isAbsolute(process.execPath)
+        ? process.execPath
+        : await discoveredNodeExecutable();
+    const result = await requireSuccess(executable, ["-p", "process.versions.node"]);
+    const version = result.stdout.trim();
+    if (!supportsSystemNode(version)) {
+        throw new Error(`Node.js ${minimumSystemNodeVersion} or newer is required to run the PhreshOS System${version ? ` (found ${version})` : ""}`);
+    }
+    return executable;
+}
+export function supportsSystemNode(version) {
+    const actual = parseVersion(version);
+    const minimum = parseVersion(minimumSystemNodeVersion);
+    if (!actual || !minimum)
+        return false;
+    return actual.major > minimum.major
+        || actual.major === minimum.major && actual.minor > minimum.minor
+        || actual.major === minimum.major && actual.minor === minimum.minor && actual.patch >= minimum.patch;
+}
+async function discoveredNodeExecutable() {
     const command = process.platform === "win32" ? "node.exe" : "node";
     const result = await requireSuccess(command, ["-p", "process.execPath"]);
     const executable = result.stdout.trim();
@@ -11,3 +30,13 @@ export default async function nodeExecutable() {
         throw new Error("A real Node.js executable is required to run the PhreshOS System service");
     return executable;
 }
+function parseVersion(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (!match)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3])
+    };
+}

package/dist/template/gitignore

@@ -14,6 +14,7 @@ dist-ssr
 
 # Made by `phresh pack` in the project root.
 /*.zip
+/*.zip.sha256
 
 # Editor directories and files
 .vscode/*

package/dist/template/package.json

@@ -1,7 +1,7 @@
 {
     "name": "phresh-program",
     "private": true,
-    "version": "0.1.0",
+    "version": "0.1.2",
     "type": "module",
     "scripts": {
         "dev": "phresh dev",
@@ -16,7 +16,7 @@
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.9",
+        "@phreshos/cli": "^0.1.11",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/dist/template/phresh.config.ts

@@ -22,7 +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.0",
+    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

package/dist/template.json

@@ -1,5 +1,5 @@
 {
     "repository": "PhreshOS/phresh-program",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "development": true
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.9",
+    "version": "0.1.11",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"