@phreshos/cli 0.1.53 → 0.1.54

package/README.md

@@ -55,6 +55,12 @@ bun run verify
 `verify` checks the scripts, builds the CLI and bundled starter, runs the
 command tests, and validates the package artifact.
 
+`check` performs static checks, `build` creates distributable output, and `test`
+runs Vitest assertions from `tests/`. Run `build` before testing built artifacts.
+`verify` runs `check`, `build`, and `test` in order. Operational tooling belongs
+in `scripts/`; tests and their fixtures belong in `tests/`. Verification uses
+the committed dependency graph without local package substitutions.
+
 ## Related repositories
 
 - [`@phreshos/node`](https://github.com/PhreshOS/node) owns the Project and
@@ -76,3 +82,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow and
 ## License
 
 Licensed under the [MIT License](LICENSE). Copyright © 2026 Zohayr SLILEH.
+
+`test:platform` explicitly selects native service/installation tests for the
+current OS. These may change temporary host services; CI runs them on disposable
+runners after building.
+
+`test:live` explicitly selects external-service tests. They require network
+access and, for providers, credentials; provider calls may incur costs.

package/dist/commands/input.js

@@ -64,7 +64,6 @@ export function clientLaunch(options) {
         || options.clientX !== undefined
         || options.clientY !== undefined
         || options.clientLayer !== undefined
-        || options.clientLocation !== undefined
         || options.clientMinimized === true
         || service !== undefined;
     if (!configured)
@@ -83,8 +82,8 @@ export function clientLaunch(options) {
         ...(options.clientWidth === undefined ? {} : { size: size(options.clientWidth, options.clientHeight) }),
         ...(options.clientX === undefined ? {} : { position: position(options.clientX, options.clientY) }),
         ...(options.clientLayer === undefined ? {} : { layer: options.clientLayer }),
-        ...(options.clientLocation === undefined ? {} : { location: options.clientLocation }),
-        ...(options.clientMinimized === true ? { minimize: true } : {})
+        ...(options.clientMinimized === true ? { minimize: true } : {}),
+        ...(options.clientMaximized === true ? { maximize: true } : {})
     };
 }
 export function serverLaunch(options) {

package/dist/commands/observation.js

@@ -1,4 +1,4 @@
 /** Wait for one named event while preserving the target's own subscription contract. */
 export async function wait(target, event, timeout) {
-    return target.waitFor(event, timeout);
+    return target.wait(event, timeout);
 }

package/dist/commands/options.js

@@ -17,8 +17,8 @@ export const clientOverrideOptions = Object.freeze([
     option("--client-x <value>", "initial Window horizontal position"),
     option("--client-y <value>", "initial Window vertical position"),
     option("--client-layer <layer>", "initial Window layer", { choices: ["window", "under", "over"] }),
-    option("--client-location <location>", "initial page beneath the Client location"),
-    option("--client-minimized", "open the Window minimized")
+    option("--client-minimized", "open the Window minimized"),
+    option("--client-maximized", "open the Window maximized")
 ]);
 export const serverOverrideOptions = Object.freeze([
     option("--server-service", "address this Server incarnation through system.service()"),

package/dist/commands/projection.js

@@ -46,14 +46,14 @@ export async function endpointView(process, name) {
 }
 export async function windowView(process) {
     const window = process.client.window;
-    const [title, position, size, minimized, front, layer, location] = await Promise.all([
+    const [title, position, size, minimized, maximized, front, layer] = await Promise.all([
         window.title(),
         window.position(),
         window.size(),
         window.minimized(),
+        window.maximized(),
         window.front(),
-        window.layer(),
-        window.location()
+        window.layer()
     ]);
-    return { process: process.identity, title, position, size, minimized, front, layer, location };
+    return { process: process.identity, title, position, size, minimized, maximized, front, layer };
 }

package/dist/commands/schemas.js

@@ -1,4 +1,3 @@
-import { clientPermissionCatalog } from "@phreshos/core";
 import { value } from "../contract/schema.js";
 const metric = {
     anyOf: [value.number("pixels"), value.string("workspace-relative expression")]
@@ -7,10 +6,6 @@ const endpointDeclaration = value.nullable(value.object({
     start: value.boolean("whether a default Process starts this Endpoint"),
     service: value.boolean("default Service role for new incarnations")
 }, ["start", "service"], "resolved Server Endpoint declaration"));
-const permissions = value.object(Object.fromEntries(Object.entries(clientPermissionCatalog).map(([name, domain]) => [name, domain === "none"
-        ? { type: "array", maxItems: 0, description: `${name} presence-only grant` }
-        : value.array(value.string(permissionValueDescription(domain)), `${name} permission values`)
-])), [], "immutable Client permissions");
 const clientDeclaration = value.nullable(value.object({
     start: value.boolean("whether a default Process starts this Endpoint"),
     service: value.boolean("default Service role for new incarnations"),
@@ -19,8 +14,8 @@ const clientDeclaration = value.nullable(value.object({
     position: value.nullable(value.object({ x: metric, y: metric }, ["x", "y"], "default Window position")),
     layer: value.nullable(value.enumeration(["window", "under", "over"], "default Window layer")),
     minimize: value.nullable(value.boolean("default minimized state")),
-    permissions
-}, ["start", "service", "title", "size", "position", "layer", "minimize", "permissions"], "resolved Client Endpoint declaration"));
+    maximize: value.nullable(value.boolean("default maximized state"))
+}, ["start", "service", "title", "size", "position", "layer", "minimize", "maximize"], "resolved Client Endpoint declaration"));
 export const programOutput = value.object({
     identity: value.string("stable Program identity"),
     assetId: value.string("public Program asset identity"),
@@ -54,10 +49,10 @@ export const windowOutput = value.object({
     position: value.object({ x: metric, y: metric }, ["x", "y"], "Window position"),
     size: value.object({ width: metric, height: metric }, ["width", "height"], "Window size"),
     minimized: value.boolean("whether the Window is minimized"),
+    maximized: value.boolean("whether the Window is maximized"),
     front: value.boolean("whether the Window is at the front of its layer"),
-    layer: value.enumeration(["window", "under", "over"], "Window layer"),
-    location: value.string("current Client location")
-}, ["process", "title", "position", "size", "minimized", "front", "layer", "location"], "Window state");
+    layer: value.enumeration(["window", "under", "over"], "Window layer")
+}, ["process", "title", "position", "size", "minimized", "maximized", "front", "layer"], "Window state");
 export const programPresentation = fields(["Identity", "identity"], ["Asset", "assetId"], ["Name", "name"], ["Version", "version"], ["Description", "description"], ["Installed", "installed"], ["Agent", "hasAgent"], ["Server", "server"], ["Client", "client"]);
 export const programListPresentation = table("data", "Program", "Programs", "No matching Programs", [
     { label: "Name", path: "name", width: 2 },
@@ -77,11 +72,12 @@ export const processListPresentation = table("data", "Process", "Processes", "No
 ]);
 export const endpointPresentation = fields(["Process", "process"], ["Program", "program"], ["Endpoint", "endpoint"], ["Declared", "declared"], ["Running", "running"], ["Service", "service"]);
 export const endpointActionPresentation = fields(["Process", "process"], ["Endpoint", "endpoint"], ["Running", "running"], ["Service", "service"]);
-export const windowPresentation = fields(["Process", "process"], ["Title", "title"], ["Position", "position"], ["Size", "size"], ["Minimized", "minimized"], ["Front", "front"], ["Layer", "layer"], ["Location", "location"]);
+export const windowPresentation = fields(["Process", "process"], ["Title", "title"], ["Position", "position"], ["Size", "size"], ["Minimized", "minimized"], ["Maximized", "maximized"], ["Front", "front"], ["Layer", "layer"], ["Location", "location"]);
 export const windowPositionPresentation = fields(["Process", "process"], ["Position", "position"]);
 export const windowSizePresentation = fields(["Process", "process"], ["Size", "size"]);
 export const windowGeometryPresentation = fields(["Process", "process"], ["Position", "position"], ["Size", "size"]);
 export const windowMinimizePresentation = fields(["Process", "process"], ["Minimized", "minimized"]);
+export const windowMaximizePresentation = fields(["Process", "process"], ["Maximized", "maximized"]);
 export const windowTitlePresentation = fields(["Process", "process"], ["Title", "title"]);
 export const windowRaisePresentation = fields(["Process", "process"], ["Front", "front"]);
 export const eventPresentation = fields(["Scope", "scope"], ["Event", "event"], ["Payload", "payload"]);
@@ -124,10 +120,3 @@ function fields(...values) {
 function table(rows, item, items, empty, columns) {
     return { format: "table", rows, columns, item, items, empty, total: "total", truncated: "truncated" };
 }
-function permissionValueDescription(domain) {
-    switch (domain) {
-        case "program": return "Program identity";
-        case "network": return "network destination scope";
-        case "storage": return "storage path scope";
-    }
-}

package/dist/commands/window.js

@@ -1,6 +1,6 @@
 import { defineCommand } from "../contract/command.js";
 import { option, processOptions, timeoutOption, withJson } from "./options.js";
-import { dataOutput, eventOutput, eventPresentation, windowGeometryPresentation, windowMinimizePresentation, windowOutput, windowPositionPresentation, windowPresentation, windowRaisePresentation, windowSizePresentation, windowTitlePresentation } from "./schemas.js";
+import { dataOutput, eventOutput, eventPresentation, windowGeometryPresentation, windowMinimizePresentation, windowMaximizePresentation, windowOutput, windowPositionPresentation, windowPresentation, windowRaisePresentation, windowSizePresentation, windowTitlePresentation } from "./schemas.js";
 import { connected, requireProcess } from "./connection.js";
 import { bounded, position, size } from "./input.js";
 import { wait } from "./observation.js";
@@ -50,6 +50,14 @@ export default function windowCommands(root, connect) {
         await windowOf(process).minimize(options.restore !== true);
         return await windowView(process);
     }));
+    defineCommand(windows, {
+        ...state("maximize", "set Window maximization without changing visibility or stored geometry", windowMaximizePresentation),
+        options: withJson(...processOptions, option("--restore", "restore rather than maximize the Window")),
+        examples: ["phresh window maximize --process main --program terminal", "phresh window maximize --process main --program terminal --restore"]
+    }, async ({ options }) => withWindow(connect, options, async (process) => {
+        await windowOf(process).maximize(options.restore !== true);
+        return await windowView(process);
+    }));
     defineCommand(windows, {
         ...state("changeTitle", "change the human-readable Window title", windowTitlePresentation),
         aliases: ["change-title"],
@@ -72,7 +80,7 @@ export default function windowCommands(root, connect) {
         requiresSystem: true,
         options: withJson(...processOptions, option("--event <event>", "Window event", {
             mandatory: true,
-            choices: ["move", "resize", "geometry", "minimize", "changeTitle", "front"]
+            choices: ["move", "resize", "geometry", "minimize", "maximize", "changeTitle", "front"]
         }), timeoutOption),
         output: dataOutput(eventOutput("The observed Window event"), "One Window event", eventPresentation),
         examples: ["phresh window wait --process main --program terminal --event geometry --json"]

package/dist/github.js

@@ -0,0 +1,9 @@
+/** Headers for requests to GitHub's API, never for release asset hosts. */
+export function githubApiHeaders() {
+    const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+    return {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "@phreshos/cli",
+        ...(token ? { Authorization: `Bearer ${token}` } : {})
+    };
+}

package/dist/program-release.js

@@ -1,9 +1,11 @@
+import { githubApiHeaders } from "./github.js";
 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";
+import { parseProgramDefinition } from "@phreshos/core";
 /** Resolve, verify, and unpack one official production Program release. */
 export async function prepareOfficialProgram(name, fetcher = fetch) {
     const release = await resolveOfficialProgramRelease(name, fetcher);
@@ -26,10 +28,7 @@ export async function prepareOfficialProgram(name, fetcher = fetch) {
 export async function resolveOfficialProgramRelease(name, fetcher = fetch) {
     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"
-        },
+        headers: githubApiHeaders(),
         signal: AbortSignal.timeout(30_000)
     });
     if (!response.ok)
@@ -83,14 +82,14 @@ async function readProgram(directory, release) {
     }
     if (value.storage !== undefined)
         throw new Error("A published Program package cannot choose its installed storage");
-    return {
+    return parseProgramDefinition({
         ...value,
         storage: join(directory, "storage"),
         ...pathField(value, directory, "icon", "icon.png"),
         ...pathField(value, directory, "agent", "agent.md"),
         ...half(value, directory, "server"),
         ...half(value, directory, "client")
-    };
+    });
 }
 function half(value, directory, name) {
     const declared = value[name];

package/dist/system/release.js

@@ -1,13 +1,11 @@
+import { githubApiHeaders } from "../github.js";
 import { createHash } from "node:crypto";
 const releases = "https://api.github.com/repos/PhreshOS/system/releases?per_page=100";
 const compatible = { major: 0, minor: 1 };
 /** Resolve the newest stable release in the System line supported by this CLI. */
 export async function resolveSystemRelease(fetcher = fetch) {
     const response = await fetcher(releases, {
-        headers: {
-            Accept: "application/vnd.github+json",
-            "User-Agent": "@phreshos/cli"
-        },
+        headers: githubApiHeaders(),
         signal: AbortSignal.timeout(30_000)
     });
     if (!response.ok)

package/dist/template/package.json

@@ -1,7 +1,7 @@
 {
     "name": "phresh",
     "private": true,
-    "version": "0.1.31",
+    "version": "0.1.32",
     "description": "The official PhreshOS starter Program.",
     "type": "module",
     "scripts": {
@@ -14,15 +14,15 @@
         "starter"
     ],
     "dependencies": {
-        "@phreshos/client": "^0.1.37",
-        "@phreshos/core": "^0.1.41",
-        "@phreshos/react": "^0.1.20",
-        "@phreshos/server": "^0.1.41",
+        "@phreshos/client": "^0.1.38",
+        "@phreshos/core": "^0.1.42",
+        "@phreshos/react": "^0.1.21",
+        "@phreshos/server": "^0.1.42",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.53",
+        "@phreshos/cli": "^0.1.54",
         "@types/node": "^26.4.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.5",

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.31",
+    version: "0.1.32",
     icon: "icon.png",
     categories: ["Development"],
     keywords: ["example", "counter", "client", "server"],

package/dist/template.json

@@ -1,6 +1,6 @@
 {
     "repository": "PhreshOS/phresh-program",
-    "version": "0.1.31",
-    "sha256": "2e6fd21f0f7e3c95934edda1790579c7d5dadb0b381fa525ebb02f747b395520",
+    "version": "0.1.32",
+    "sha256": "2644513c80b924eda546f257f853bbc03619c5b9bd2b510259d4f87ecd126f4a",
     "development": true
 }

package/package.json

@@ -1,66 +1,65 @@
 {
-    "name": "@phreshos/cli",
-    "type": "module",
-    "version": "0.1.53",
-    "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 && vite-node scripts/build-template.ts",
-        "test": "node --run compile && node --test tests/*.test.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",
-        "verify:windows-service": "node --run compile && node scripts/verify-windows-service.mjs",
-        "prepack": "node --run build"
-    },
-    "bin": {
-        "phresh": "dist/cli.js"
-    },
-    "files": [
-        "dist",
-        "LICENSE",
-        "README.md"
-    ],
-    "author": "Zohayr SLILEH",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/PhreshOS/cli.git"
-    },
-    "bugs": {
-        "url": "https://github.com/PhreshOS/cli/issues"
-    },
-    "homepage": "https://github.com/PhreshOS/cli#readme",
-    "keywords": [
-        "phreshos",
-        "cli",
-        "program"
-    ],
-    "publishConfig": {
-        "access": "public",
-        "provenance": true
-    },
-    "packageManager": "bun@1.3.14",
-    "dependencies": {
-        "@clack/prompts": "^1.7.0",
-    "@phreshos/core": "^0.1.42",
-    "@phreshos/node": "^0.1.17",
-        "adm-zip": "^0.6.0",
-        "cli-table3": "^0.6.5",
-        "commander": "^15.0.0",
+  "name": "@phreshos/cli",
+  "type": "module",
+  "version": "0.1.54",
+  "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 })\"",
+    "compile": "tsc --noEmit false --outDir dist --rootDir source --rewriteRelativeImportExtensions true --allowImportingTsExtensions true",
+    "build": "node --run clean && node --run compile && vite-node scripts/build-template.ts",
+    "test": "vitest run --project default",
+    "verify": "node --run check && node --run build && node --run test",
+    "prepack": "node --run build",
+    "check": "tsc --noEmit && tsc -p tsconfig.scripts.json",
+    "test:platform": "vitest run --project platform",
+    "test:live": "vitest run --project live"
+  },
+  "bin": {
+    "phresh": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "author": "Zohayr SLILEH",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PhreshOS/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PhreshOS/cli/issues"
+  },
+  "homepage": "https://github.com/PhreshOS/cli#readme",
+  "keywords": [
+    "phreshos",
+    "cli",
+    "program"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.3.14",
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@phreshos/core": "^0.1.43",
+    "@phreshos/node": "^0.1.18",
+    "adm-zip": "^0.6.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^15.0.0",
     "picocolors": "^1.1.1",
-        "string-width": "^4.2.3"
-    },
-    "devDependencies": {
-        "@types/adm-zip": "^0.5.8",
-        "@types/node": "^25.9.5",
-        "typescript": "^6.0.3",
-        "vite-node": "^6.0.0"
-    }
+    "string-width": "^4.2.3"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.8",
+    "@types/node": "^25.9.5",
+    "typescript": "^6.0.3",
+    "vite-node": "^6.0.0",
+    "vitest": "^4.1.10"
+  }
 }