@phreshos/cli 0.1.20 → 0.1.21

package/README.md

@@ -156,6 +156,12 @@ export default defineConfig({
 
     icon: "icon.png",
 
+    categories: ["Utilities"],
+
+    keywords: ["files", "storage"],
+
+    website: "https://example.com/file-manager",
+
     buildCommand: "bun run build",
 
     server: {
@@ -164,6 +170,8 @@ export default defineConfig({
 
         installCommand: "npm ci",
 
+        uninstallCommand: "npm run clean:external",
+
         startCommand: "node main.js",
 
         development: {
@@ -368,6 +376,10 @@ The command installs through the machine's local intake. A running
 Program may also install itself through the server SDK; installation is not a
 client capability.
 
+When a Server declares `installCommand`, `phresh install` writes that command's
+`stdout` and `stderr` chunks as the System emits them. The final installed
+confirmation appears only after the output stream completes successfully.
+
 That is also why it names **paths** rather than sending bytes: install
 used to want an upload because the installer was a browser, which has
 bytes and no path. You have the paths.
@@ -384,13 +396,19 @@ running Processes, stored data, and runtime Program. `--everything` explicitly
 ends those Processes, removes everything the system owns for the Program, and
 forgets its runtime record.
 
+When the installed Server declares `uninstallCommand`, the System runs it from
+that Server directory before removing files. `phresh uninstall` writes its
+ordered `stdout` and `stderr` chunks as they arrive. A failed cleanup command
+aborts removal and reports the failure.
+
 The identity comes from this project's `phresh.config.ts`; the command does not
 accept an arbitrary Program identity.
 
 ## What pack produces
 
-`pack` takes what is at each half's `location` and writes
-`<identity>@<version>.zip`. Your program may leave its halves anywhere; the
+`pack` takes what is at each half's `location` and writes both `program.json`
+and `<identity>@<version>.zip`. The exact generated declaration is also stored
+inside the archive. Your program may leave its halves anywhere; the
 package always keeps them in the same places, so the artifact's shape
 belongs to the contract rather than to your project. That is why the
 `program.json` it writes names `server` and `client` explicitly — those
@@ -405,5 +423,7 @@ An authored agent document may use any project-relative path, while packaging
 normalizes it to `agent.md`.
 
 Nothing about the system moves because this exists. `program.json` is
-still the only thing the system reads, and a package assembled by hand
-is still a package. This just means you do not have to.
+still the only declaration the system and release catalog read. Root
+`categories`, `keywords`, and `website` values are optional and cross into it
+without affecting execution. The file is generated output; `phresh.config.ts`
+remains the authored source.

package/dist/derive.js

@@ -27,6 +27,9 @@ export default function derive(config, directory, which) {
         name: config.name,
         version: config.version,
         description: config.description,
+        categories: config.categories,
+        keywords: config.keywords,
+        website: config.website,
         // Where it already is. Unlike pack, which gives it its canonical
         // name, this points into the authoring tree and leaves it alone.
         icon: config.icon && resolve(directory, config.icon),
@@ -41,6 +44,7 @@ export default function derive(config, directory, which) {
                 location: resolve(directory, server.location),
                 start: server.start,
                 installCommand: config.server?.installCommand,
+                uninstallCommand: config.server?.uninstallCommand,
                 startCommand: server.startCommand
             } },
         // A URL stands as written; a directory is made absolute. The

package/dist/pack.js

@@ -24,8 +24,9 @@ import build from "./build-command.js";
  * The archive itself therefore needs no second naming layer.
  *
  * The files go into the archive directly rather than through a staging
- * directory: a copy of a build is a thing that can be stale, and there
- * is nothing a staging directory was doing that the archive does not.
+ * directory: a copy of a build is a thing that can be stale. The generated
+ * standalone program.json is also placed beside the archive for release
+ * discovery; both declarations are made from the same bytes.
  */
 export default async function pack(directory = process.cwd()) {
     const config = await readConfig(directory);
@@ -47,7 +48,12 @@ export default async function pack(directory = process.cwd()) {
         file(zip, directory, config.icon, "icon.png", "Program icon");
     if (config.agent)
         file(zip, directory, config.agent, "agent.md", "Program agent documentation");
-    zip.addFile("program.json", Buffer.from(JSON.stringify(program(config, version), null, 4) + "\n"));
+    const declaration = Buffer.from(JSON.stringify(program(config, version), null, 4) + "\n");
+    zip.addFile("program.json", declaration);
+    // The standalone release declaration and the declaration inside the
+    // archive are the same bytes. There is no separately authored catalog
+    // description that can drift from the installable Program.
+    writeFileSync(resolve(directory, "program.json"), declaration);
     const archive = `${config.identity}@${version ?? "0.0.0"}.zip`;
     const bytes = zip.toBuffer();
     writeFileSync(resolve(directory, archive), bytes);
@@ -67,7 +73,10 @@ function program(config, version) {
         description: config.description,
         icon: config.icon ? "icon.png" : undefined,
         agent: config.agent ? "agent.md" : undefined,
-        ...config.server && { server: { location: "server", start: config.server.start, installCommand: config.server.installCommand, startCommand: config.server.startCommand } },
+        categories: config.categories,
+        keywords: config.keywords,
+        website: config.website,
+        ...config.server && { server: { location: "server", start: config.server.start, installCommand: config.server.installCommand, uninstallCommand: config.server.uninstallCommand, startCommand: config.server.startCommand } },
         ...config.client && { client: { location: "client", start: config.client.start, title: config.client.title, size: config.client.size, position: config.client.position, layer: config.client.layer, minimize: config.client.minimize } }
     };
 }

package/dist/program-command-output.js

@@ -0,0 +1,8 @@
+/** Writes one validated Program lifecycle-command output event verbatim. */
+export default function writeProgramCommandOutput(event) {
+    if ((event.stream !== "stdout" && event.stream !== "stderr") || typeof event.text !== "string") {
+        throw new Error("The System returned an invalid Program command output chunk");
+    }
+    const output = event.stream === "stderr" ? process.stderr : process.stdout;
+    output.write(event.text);
+}

package/dist/program-installation.js

@@ -1,4 +1,5 @@
 import speak from "./program-intake.js";
+import writeProgramCommandOutput from "./program-command-output.js";
 /** Install one prepared Program and await every explicitly requested outcome. */
 export default async function installProgram(program, options = {}) {
     let installedValue;
@@ -11,7 +12,9 @@ export default async function installProgram(program, options = {}) {
         run: options.run === true,
         startup: options.startup === true
     }, function (event) {
-        if (event.event === "installed") {
+        if (event.event === "output")
+            writeProgramCommandOutput(event);
+        else if (event.event === "installed") {
             installedValue = event.program;
             replaced = event.replaced === true;
         }

package/dist/project.js

@@ -39,12 +39,28 @@ function coherent(config) {
         throw new Error("A program's identity is kebab-case, because it is also the name of its directory");
     if (!config.server && !config.client)
         throw new Error("A program must have a server half, a client half, or both");
-    for (const field of ["name", "version", "description", "icon", "agent"]) {
+    for (const field of ["name", "version", "description", "icon", "agent", "website"]) {
         if (config[field] !== undefined && typeof config[field] !== "string")
             throw new Error(`A program's ${field} must be text`);
     }
     if (config.agent !== undefined && config.agent.trim().length === 0)
         throw new Error("A program's agent documentation must be a non-empty path");
+    if (config.website !== undefined) {
+        try {
+            new URL(config.website);
+        }
+        catch {
+            throw new Error("A program's website must be a valid URL");
+        }
+    }
+    for (const [field, maximum] of [["categories", 20], ["keywords", 50]]) {
+        const values = config[field];
+        if (values === undefined)
+            continue;
+        if (!Array.isArray(values) || values.length > maximum || values.some(value => typeof value !== "string" || value.trim().length === 0 || value.trim().length > 50)) {
+            throw new Error(`A program's ${field} must contain at most ${maximum} non-empty values of at most 50 characters`);
+        }
+    }
     if (config.buildCommand !== undefined && (typeof config.buildCommand !== "string" || config.buildCommand.trim().length === 0))
         throw new Error("A program's buildCommand must be non-empty text");
     for (const half of ["server", "client"]) {
@@ -64,6 +80,8 @@ function coherent(config) {
         throw new Error("A server half must say what starts it");
     if (config.server?.installCommand !== undefined && typeof config.server.installCommand !== "string")
         throw new Error("A server half's install command must be text");
+    if (config.server?.uninstallCommand !== undefined && typeof config.server.uninstallCommand !== "string")
+        throw new Error("A server half's uninstall command must be text");
     if (config.client?.title !== undefined && typeof config.client.title !== "string")
         throw new Error("A client half's title must be text");
     if (config.client?.minimize !== undefined && typeof config.client.minimize !== "boolean")

package/dist/template/metadata.json

@@ -0,0 +1,11 @@
+{
+    "schema": 1,
+    "identity": "phresh",
+    "version": "0.1.13",
+    "name": "Phresh Program",
+    "description": "A minimal Client and Server Program for exploring PhreshOS development.",
+    "icon": "icon.png",
+    "categories": ["Development"],
+    "keywords": ["example", "counter", "client", "server"],
+    "website": "https://github.com/PhreshOS/phresh-program"
+}

package/dist/template/package.json

@@ -1,7 +1,7 @@
 {
     "name": "phresh",
     "private": true,
-    "version": "0.1.12",
+    "version": "0.1.13",
     "description": "The official PhreshOS starter Program.",
     "type": "module",
     "scripts": {
@@ -22,7 +22,7 @@
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.20",
+        "@phreshos/cli": "^0.1.21",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/dist/template/phresh.config.ts

@@ -4,7 +4,7 @@ export default defineConfig({
     identity: "phresh",
     name: "Phresh Program",
     description: "A minimal counter with direct Client and Server endpoints.",
-    version: "0.1.12",
+    version: "0.1.13",
     icon: "icon.png",
     buildCommand: "vite-node scripts/build.ts",
     server: {

package/dist/template.json

@@ -1,6 +1,6 @@
 {
     "repository": "PhreshOS/phresh-program",
-    "version": "0.1.12",
-    "sha256": "408d2a1353c32d5ffe69773d115663d125311586394f8bcddd0a0e07f33da914",
+    "version": "0.1.13",
+    "sha256": "c55ff8129295c9c90b7a78fef8689fef6e0d180c7a284fdb180127700b74fcb0",
     "development": true
 }

package/dist/uninstall.js

@@ -1,10 +1,13 @@
 import { readConfig } from "./project.js";
 import { dim, heading } from "./style.js";
 import speak from "./program-intake.js";
+import writeProgramCommandOutput from "./program-command-output.js";
 /** Uninstall the Program declared by the current project. */
 export default async function uninstall(everything = false, directory = process.cwd()) {
     const config = await readConfig(directory);
     await speak({ word: "uninstall", identity: config.identity, everything }, function (event) {
+        if (event.event === "output")
+            return writeProgramCommandOutput(event);
         if (event.event !== "uninstalled")
             return;
         heading(config.name ?? config.identity, "uninstalled");

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-  "version": "0.1.20",
+  "version": "0.1.21",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"
@@ -49,7 +49,7 @@
     "packageManager": "bun@1.3.14",
     "dependencies": {
         "@clack/prompts": "^1.7.0",
-    "@phreshos/core": "^0.1.12",
+    "@phreshos/core": "^0.1.13",
         "adm-zip": "^0.6.0",
         "commander": "^15.0.0",
         "picocolors": "^1.1.1"