@phreshos/cli 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zohayr SLILEH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,7 @@
 # @phreshos/cli
 
-The `phresh` command for creating, running, packaging, installing, and
-uninstalling Programs.
+The `phresh` command for creating and operating Programs, and for installing
+and managing the PhreshOS System on the current machine.
 
 ## Package status
 
@@ -21,6 +21,7 @@ phresh install  # lay this program out on this machine
 phresh uninstall # remove its installed form
 phresh start    # run what your build left, and stay with it
 phresh dev      # run from source, and stay with it
+phresh system status # inspect the local System and its background service
 ```
 
 `phresh --help` lists them, `phresh <command> --help` explains one, and
@@ -28,20 +29,53 @@ phresh dev      # run from source, and stay with it
 unknown command, an unknown flag and a malformed option are each refused
 and named.
 
-**This tool acts on the current project, and the list ends there.** It is
-not the machine's control panel — it accepts no arbitrary program identity
-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.
+Every top-level Program command acts on the current project, and that list ends
+there. It accepts no arbitrary Program identity and has no word for a Process,
+Window, store, or setting. Machine lifecycle is isolated under `phresh system`;
+it manages the System installation and native service, not the state inside the
+System.
+
+## System lifecycle
+
+```bash
+phresh system install
+phresh system uninstall
+phresh system status
+phresh system start
+phresh system stop
+phresh system enable
+phresh system disable
+```
+
+`install` resolves the newest compatible stable release from the official
+[`PhreshOS/system`](https://github.com/PhreshOS/system) GitHub Releases. It
+downloads the production archive and adjacent checksum, verifies every byte,
+installs production dependencies into a staged version directory, atomically
+points the stable `current` path at it, then registers, enables, and starts the
+native per-user service. The selected release and the service entry therefore
+cannot become two competing sources of truth if installation is interrupted.
+It never reads a source checkout and never requires Bun or TypeScript.
+
+The System runs under `launchd` on macOS and `systemd --user` on Linux. The
+native manager owns it after the CLI exits and restarts a failed active
+service. `start` and `stop` change current execution only; `enable` and
+`disable` change automatic startup only. `status` reads installation,
+registration, startup, process, and local-intake readiness without changing
+any of them.
+
+Installation files and persistent System state have separate homes. Removing
+the System unregisters its service and removes its release files while keeping
+`~/.phreshos`, including Programs and owner data. Windows remains unsupported
+until the System has an equally strong local-intake authorization model there.
 
 ## 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 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 directory name becomes the stable kebab-case Program identity. In a
 terminal, `create` asks for the directory when it is omitted, the readable
@@ -55,11 +89,9 @@ phresh create status-board \
 ```
 
 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`.
+project and leaves installation as the first reported next step. Generated and
+initialized Programs always use the published package ranges embedded in the
+CLI; repository layout never changes dependency meaning.
 
 ## Saying something to a program you start
 
@@ -117,7 +149,7 @@ export default defineConfig({
 
     apiDocs: "api.md",
 
-    icons: "icons",
+    icon: "icon.png",
 
     buildCommand: "bun run build",
 
@@ -212,7 +244,9 @@ In a terminal, `init` asks for the production locations and commands needed by
 `start` and `install`, including whether a package build should prepare those
 locations. It then offers the development command and URL needed by `dev`.
 Existing `build` and `dev` package scripts become editable suggestions, never
-silent assumptions.
+silent assumptions. A single Endpoint defaults to `dist`; when both Endpoints
+exist, their defaults are `dist/server` and `dist/client`. API documentation is
+opt-in and defaults to disabled even when a likely document already exists.
 
 Outside a terminal it never waits for input; the same values are supplied as
 named options:
@@ -225,7 +259,7 @@ phresh init --client \
     --client-development-start-command "bun run dev"
 
 phresh init --server \
-    --server-location build/server \
+    --server-location dist \
     --server-start-command "node main.js"
 ```
 
@@ -241,7 +275,7 @@ The final `Next` line is derived from the resulting config. It always shows
 one Endpoint received a development declaration.
 
 Visual and advanced runtime defaults remain for the author to add deliberately:
-`icons`, `size`, `position`, `installCommand`, `start`, layers, and minimization
+`icon`, `size`, `position`, `installCommand`, `start`, layers, and minimization
 are not guessed. An omitted `start` is `true`; only a default-off Endpoint needs to
 say `start: false`.
 
@@ -249,9 +283,12 @@ say `start: false`.
 
 Both **run your program without installing it, and stay attached.** They
 print the `program.json` it will be declared as, hand that to the system
-through the socket it listens on — `~/.phreshos/intake.sock`, which only
-your account can open, so nothing is sent to prove anything — and then
-hold.
+through the socket below the selected system home. With no override, that is
+`~/.phreshos/intake.sock`. Set `PHRESHOS_HOME` to an absolute system home to
+address another system instance; the CLI derives
+`<PHRESHOS_HOME>/intake.sock` from it. The socket is not selected
+separately from its instance. Only your account can open it, so nothing is
+sent to prove anything, and then the command holds.
 
 **The connection is the tether, in both directions.** Ctrl-C and your
 program stops. Close the window it opened and the command returns, with
@@ -367,8 +404,8 @@ register a subscription. Those are system contracts documented once by the
 SDKs; `api-docs.md` supplies only the Program-specific meaning carried through
 them.
 
-There is **no wrapping directory**: `program.json`, `server/`, `client/`
-`icons/`, and optional `api-docs.md` sit at the package's root, and the system names the
+There is **no wrapping directory**: `program.json`, `server/`, `client/`,
+optional `icon.png`, and optional `api-docs.md` sit at the package's root, and the system names the
 directory it installs into from your program's `identity`.
 
 Nothing about the system moves because this exists. `program.json` is

package/dist/build-template.js

@@ -1,8 +1,19 @@
-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");
+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.0",
+    sha256: "6e1a87a037a6ac5f82ff4c7d420757f972098387d73a8b4165aab2ef331cec36"
+};
+const archiveUrl = `https://github.com/${repository}/archive/refs/tags/v${release.version}.zip`;
 const output = resolve(import.meta.dirname, "template");
-const excludedDirectories = new Set(["dist", "node_modules", "storage"]);
+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",
@@ -11,49 +22,69 @@ const excludedFiles = new Set([
     "pnpm-lock.yaml",
     "yarn.lock"
 ]);
-if (!existsSync(source))
-    throw new Error(`The Get Started source is not there: ${source}`);
+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 });
-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)
+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;
-    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}`;
-    }
+    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");
-function included(path) {
-    const local = relative(source, path);
-    if (!local)
-        return true;
-    const parts = local.split(sep);
+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;
-    const name = basename(path);
-    return !excludedFiles.has(name) && !name.endsWith(".zip");
+    if (parts.length === 1 && excludedRootFiles.has(local))
+        return false;
+    if (excludedFiles.has(parts.at(-1)))
+        return false;
+    return !local.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;
+function select(source, names) {
+    return Object.fromEntries(names.flatMap(name => source?.[name] === undefined ? [] : [[name, source[name]]]));
 }