@phreshos/cli 0.1.65 → 0.1.67

package/dist/commands/access.js

@@ -5,6 +5,7 @@ import { connectSystem } from "./connection.js";
 import windowCommands from "./window.js";
 import executeCommand from "./execute.js";
 import operationCommands from "./operation.js";
+import serviceCommands from "./service.js";
 /** Expose the shared System domains through explicit Node SDK executors. */
 export default function accessCommands(program, connect = connectSystem) {
     executeCommand(program, connect);
@@ -12,5 +13,6 @@ export default function accessCommands(program, connect = connectSystem) {
     programCommands(program, connect);
     processCommands(program, connect);
     endpointCommands(program, connect);
+    serviceCommands(program, connect);
     windowCommands(program, connect);
 }

package/dist/commands/execution.js

@@ -6,8 +6,19 @@ export const executeCommandPaths = Object.freeze({
     "program.list": ["program", "list"],
     "program.find": ["program", "inspect"],
     "program.agent": ["program", "agent"],
-    "program.getLaunch": ["program", "getLaunch"],
-    "program.setLaunch": ["program", "setLaunch"],
+    "program.definition": ["program", "definition"],
+    "program.getStartup": ["program", "getStartup"],
+    "program.enableStartup": ["program", "enableStartup"],
+    "program.disableStartup": ["program", "disableStartup"],
+    "program.pinned": ["program", "pinned"],
+    "program.pin": ["program", "pin"],
+    "program.unpin": ["program", "unpin"],
+    "program.getPermission": ["program", "getPermission"],
+    "program.listPermissions": ["program", "listPermissions"],
+    "program.allowsPermission": ["program", "allowsPermission"],
+    "program.allowPermission": ["program", "allowPermission"],
+    "program.denyPermission": ["program", "denyPermission"],
+    "program.requestPermission": ["program", "requestPermission"],
     "program.logs": ["program", "logs"],
     "program.wait": ["program", "wait"],
     "process.list": ["process", "list"],
@@ -24,14 +35,25 @@ export const executeCommandPaths = Object.freeze({
     "endpoint.publish": ["endpoint", "publish"],
     "endpoint.wait": ["endpoint", "wait"],
     "endpoint.waitLifecycle": ["endpoint", "waitLifecycle"],
+    "service.list": ["service", "list"],
+    "service.search": ["service", "search"],
+    "service.inspect": ["service", "inspect"],
+    "service.waitReady": ["service", "waitReady"],
+    "service.ask": ["service", "ask"],
+    "service.publish": ["service", "publish"],
+    "service.wait": ["service", "wait"],
+    "service.waitLifecycle": ["service", "waitLifecycle"],
+    "service.waitDiscovery": ["service", "waitDiscovery"],
     "window.inspect": ["window", "inspect"],
     "window.move": ["window", "move"],
     "window.resize": ["window", "resize"],
     "window.setGeometry": ["window", "setGeometry"],
     "window.minimize": ["window", "minimize"],
     "window.maximize": ["window", "maximize"],
-    "window.changeTitle": ["window", "changeTitle"],
-    "window.changeHeader": ["window", "changeHeader"],
+    "window.setTitle": ["window", "setTitle"],
+    "window.setHeader": ["window", "setHeader"],
+    "window.setFrame": ["window", "setFrame"],
+    "window.setTransaction": ["window", "setTransaction"],
     "window.raise": ["window", "raise"],
     "window.wait": ["window", "wait"]
 });

package/dist/commands/options.js

@@ -10,8 +10,8 @@ export const endpointOptions = Object.freeze([
     option("--endpoint <endpoint>", "Endpoint kind", { mandatory: true, choices: ["server", "client"] })
 ]);
 export const clientOverrideOptions = Object.freeze([
-    option("--client-service", "address this Client incarnation through system.service()"),
-    option("--no-client-service", "do not address this Client incarnation through system.service()"),
+    option("--client-service", "make this Client execution context available through Service discovery"),
+    option("--no-client-service", "keep this Client execution context out of Service discovery"),
     option("--client-title <title>", "initial Window title"),
     option("--client-width <value>", "initial Window width"),
     option("--client-height <value>", "initial Window height"),
@@ -22,8 +22,8 @@ export const clientOverrideOptions = Object.freeze([
     option("--client-maximized", "open the Window maximized")
 ]);
 export const serverOverrideOptions = Object.freeze([
-    option("--server-service", "address this Server incarnation through system.service()"),
-    option("--no-server-service", "do not address this Server incarnation through system.service()")
+    option("--server-service", "make this Server execution context available through Service discovery"),
+    option("--no-server-service", "keep this Server execution context out of Service discovery")
 ]);
 export const launchOptions = Object.freeze([
     ...serverOverrideOptions,

package/dist/commands/program.js

@@ -1,3 +1,4 @@
+import { parsePermissionName } from "@phreshos/core";
 import { defineCommand } from "../contract/command.js";
 import { value } from "../contract/schema.js";
 import { launchOptions, option, timeoutOption, withJson } from "./options.js";
@@ -60,32 +61,157 @@ export default function programCommands(root, connect) {
         return result;
     }));
     defineCommand(programs, {
-        name: "getLaunch",
-        aliases: ["get-launch"],
-        description: executeDescription("program", "getLaunch"),
+        name: "definition",
+        description: executeDescription("program", "definition"),
         requiresSystem: true,
         options: withJson(option("--program <identity>", "Program identity", { mandatory: true })),
-        output: dataOutput(value.any("Saved Process launch or null"), "The saved Program launch", { format: "value" }),
-        examples: ["phresh program get-launch --program terminal --json"]
+        output: dataOutput(value.any("Complete canonical Program definition"), "The Program definition", { format: "value" }),
+        examples: ["phresh program definition --program terminal --json"]
     }, ({ options }) => connected(connect, system => system.execute({
         $domain: "program",
-        $operation: "getLaunch",
+        $operation: "definition",
         identity: options.program
     })));
     defineCommand(programs, {
-        name: "setLaunch",
-        aliases: ["set-launch"],
-        description: executeDescription("program", "setLaunch"),
+        name: "getStartup",
+        aliases: ["get-startup"],
+        description: executeDescription("program", "getStartup"),
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "Program identity", { mandatory: true })),
+        output: dataOutput(value.any("Stored System-start launch or null"), "The Program startup launch", { format: "value" }),
+        examples: ["phresh program get-startup --program terminal --json"]
+    }, ({ options }) => connected(connect, system => system.execute({
+        $domain: "program",
+        $operation: "getStartup",
+        identity: options.program
+    })));
+    defineCommand(programs, {
+        name: "enableStartup",
+        aliases: ["enable-startup"],
+        description: executeDescription("program", "enableStartup"),
         requiresSystem: true,
         options: withJson(option("--program <identity>", "Program identity", { mandatory: true }), ...launchOptions),
-        output: dataOutput(value.any("Saved Process launch"), "The saved Program launch", { format: "value" }),
-        examples: ["phresh program set-launch --program terminal --client --name main --json"]
+        output: dataOutput(value.any("Stored System-start launch"), "The Program startup launch", { format: "value" }),
+        examples: ["phresh program enable-startup --program terminal --client --name main --json"]
     }, ({ options }) => connected(connect, system => system.execute({
         $domain: "program",
-        $operation: "setLaunch",
+        $operation: "enableStartup",
         identity: options.program,
         launch: launch(options)
     })));
+    defineCommand(programs, {
+        name: "disableStartup",
+        aliases: ["disable-startup"],
+        description: executeDescription("program", "disableStartup"),
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "Program identity", { mandatory: true })),
+        output: dataOutput(value.nullable(value.any("disabled startup")), "Startup is disabled", { format: "value" }),
+        examples: ["phresh program disable-startup --program terminal"]
+    }, ({ options }) => connected(connect, system => system.execute({
+        $domain: "program",
+        $operation: "disableStartup",
+        identity: options.program
+    })));
+    for (const operation of ["pinned", "pin", "unpin"])
+        defineCommand(programs, {
+            name: operation,
+            description: executeDescription("program", operation),
+            requiresSystem: true,
+            options: withJson(option("--program <identity>", "Program identity", { mandatory: true })),
+            output: dataOutput(value.boolean("whether the Program is pinned"), "The Program pinned state", { format: "value" }),
+            examples: [`phresh program ${operation} --program terminal`]
+        }, ({ options }) => connected(connect, system => system.execute({
+            $domain: "program",
+            $operation: operation,
+            identity: options.program
+        })));
+    defineCommand(programs, {
+        name: "getPermission",
+        aliases: ["get-permission"],
+        description: executeDescription("program", "getPermission"),
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "Program identity", { mandatory: true }), option("--permission <name>", "permission name", { mandatory: true })),
+        output: dataOutput(value.any("effective permission assignment"), "The effective permission", { format: "value" }),
+        examples: ["phresh program get-permission --program terminal --permission network --json"]
+    }, ({ options }) => connected(connect, system => system.execute({
+        $domain: "program",
+        $operation: "getPermission",
+        identity: options.program,
+        permission: parsePermissionName(options.permission)
+    })));
+    defineCommand(programs, {
+        name: "listPermissions",
+        aliases: ["list-permissions"],
+        description: executeDescription("program", "listPermissions"),
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "Program identity", { mandatory: true })),
+        output: dataOutput(value.any("effective permission assignments"), "The effective permissions", { format: "value" }),
+        examples: ["phresh program list-permissions --program terminal --json"]
+    }, ({ options }) => connected(connect, system => system.execute({
+        $domain: "program",
+        $operation: "listPermissions",
+        identity: options.program
+    })));
+    defineCommand(programs, {
+        name: "allowsPermission",
+        aliases: ["allows-permission"],
+        description: executeDescription("program", "allowsPermission"),
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "Program identity", { mandatory: true }), option("--permission <name>", "permission name", { mandatory: true }), option("--value <json>", "requested permission value encoded as JSON")),
+        output: dataOutput(value.boolean("whether the requested access is allowed"), "The permission decision", { format: "value" }),
+        examples: ["phresh program allows-permission --program terminal --permission network --value '[\"https://example.com\"]'"]
+    }, ({ options }) => connected(connect, system => system.execute({
+        $domain: "program",
+        $operation: "allowsPermission",
+        identity: options.program,
+        permission: parsePermissionName(options.permission),
+        ...(options.value === undefined ? {} : { value: permissionRequest(options.value) })
+    })));
+    defineCommand(programs, {
+        name: "allowPermission",
+        aliases: ["allow-permission"],
+        description: executeDescription("program", "allowPermission"),
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "Program identity", { mandatory: true }), option("--permission <name>", "permission name", { mandatory: true }), option("--value <json>", "complete allowed permission value encoded as JSON")),
+        output: dataOutput(value.any("stored permission assignment"), "The stored permission", { format: "value" }),
+        examples: ["phresh program allow-permission --program terminal --permission network --value '[\"https://example.com\"]'"]
+    }, ({ options }) => connected(connect, system => system.execute({
+        $domain: "program",
+        $operation: "allowPermission",
+        identity: options.program,
+        permission: parsePermissionName(options.permission),
+        ...(options.value === undefined ? {} : { value: permissionRequest(options.value) })
+    })));
+    defineCommand(programs, {
+        name: "denyPermission",
+        aliases: ["deny-permission"],
+        description: executeDescription("program", "denyPermission"),
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "Program identity", { mandatory: true }), option("--permission <name>", "permission name", { mandatory: true })),
+        output: dataOutput(value.any("stored permission assignment"), "The stored permission", { format: "value" }),
+        examples: ["phresh program deny-permission --program terminal --permission network"]
+    }, ({ options }) => connected(connect, system => system.execute({
+        $domain: "program",
+        $operation: "denyPermission",
+        identity: options.program,
+        permission: parsePermissionName(options.permission)
+    })));
+    defineCommand(programs, {
+        name: "requestPermission",
+        aliases: ["request-permission"],
+        description: executeDescription("program", "requestPermission"),
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "Program identity", { mandatory: true }), option("--permission <name>", "permission name", { mandatory: true }), option("--value <json>", "complete requested permission value encoded as JSON"), timeoutOption),
+        output: dataOutput(value.any("permission decision"), "The permission decision", { format: "value" }),
+        examples: ["phresh program request-permission --program terminal --permission uploads"]
+    }, ({ options }) => connected(connect, system => system.execute({
+        $domain: "program",
+        $operation: "requestPermission",
+        identity: options.program,
+        permission: parsePermissionName(options.permission),
+        ...(options.value === undefined ? {} : { value: permissionRequest(options.value) }),
+        ...(options.timeout === undefined ? {} : { timeout: bounded(options.timeout, "--timeout", 0) })
+    })));
     defineCommand(programs, {
         name: "logs",
         description: executeDescription("program", "logs"),
@@ -111,7 +237,7 @@ export default function programCommands(root, connect) {
         requiresSystem: true,
         options: withJson(option("--event <event>", "Program lifecycle event", {
             mandatory: true,
-            choices: ["create", "forget", "install", "uninstall", "processCreate", "processExit"]
+            choices: ["create", "forget", "install", "uninstall", "pinned", "processCreate", "processExit"]
         }), option("--program <identity>", "observe events belonging to one Program"), timeoutOption),
         output: dataOutput(eventOutput("The observed Program event", value.any("Program state or uninstall result")), "One Program event", eventPresentation),
         examples: ["phresh program wait --event create", "phresh program wait --event uninstall --program terminal --json"]
@@ -123,3 +249,12 @@ export default function programCommands(root, connect) {
         ...(options.timeout === undefined ? {} : { timeout: bounded(options.timeout, "--timeout", 1) })
     })));
 }
+function permissionRequest(source) {
+    const value = json(source, "--value");
+    if (value === true || strings(value))
+        return value;
+    throw new Error("--value must be true or a JSON array of strings");
+}
+function strings(value) {
+    return Array.isArray(value) && value.every(entry => typeof entry === "string");
+}

package/dist/commands/project.js

@@ -85,7 +85,7 @@ export default function projectCommands(program, coreRange) {
         name: "install",
         description: "install a local or official Program",
         arguments: [{ syntax: "[name]", description: "name of an official Program" }],
-        options: [option("--run", "launch the installed Program before startup"), option("--purge", "delete existing installed Program storage")],
+        options: [option("--run", "launch one default Process after installation"), option("--purge", "delete existing installed Program storage")],
         guidance: [
             "Without a name, builds and installs the Program declared by this project.",
             "A name installs its verified official production release. --run launches the installed Program now."

package/dist/commands/projection.js

@@ -18,19 +18,22 @@ export async function programView(program) {
     };
 }
 export async function processView(process) {
-    const [server, client, serverService, clientService] = await Promise.all([
-        process.server.exists(),
-        process.client.exists(),
-        process.server.isService(),
-        process.client.isService()
+    const program = process.program();
+    const [server, client] = await Promise.all([
+        program.server === null
+            ? Promise.resolve({ running: false, service: false })
+            : Promise.all([process.server.running(), process.server.isService()]).then(([running, service]) => ({ running, service })),
+        program.client === null
+            ? Promise.resolve({ running: false, service: false })
+            : Promise.all([process.client.running(), process.client.isService()]).then(([running, service]) => ({ running, service }))
     ]);
     return {
         identity: process.identity,
         name: process.name,
-        program: process.program().identity,
+        program: program.identity,
         startedAt: process.startedAt.toISOString(),
-        server: { declared: process.program().server !== null, running: server, service: serverService },
-        client: { declared: process.program().client !== null, running: client, service: clientService }
+        server: { declared: program.server !== null, ...server },
+        client: { declared: program.client !== null, ...client }
     };
 }
 export async function endpointView(process, name) {
@@ -40,7 +43,7 @@ export async function endpointView(process, name) {
         program: program.identity,
         endpoint: name,
         declared: name === "server" ? program.server !== null : program.client !== null,
-        running: await endpoint(process, name).exists(),
+        running: await endpoint(process, name).running(),
         service: await endpoint(process, name).isService()
     };
 }

package/dist/commands/schemas.js

@@ -3,25 +3,60 @@ import { value } from "../contract/schema.js";
 const metric = {
     anyOf: [value.number("pixels"), value.string("workspace-relative expression")]
 };
+const transaction = {
+    anyOf: [
+        value.boolean("default or disabled transaction"),
+        value.number("duration in milliseconds"),
+        value.object({
+            duration: value.number("duration in milliseconds"),
+            easing: value.any("CSS easing name or cubic Bézier tuple")
+        }, ["duration", "easing"], "appearance transaction")
+    ]
+};
+const frame = {
+    anyOf: [
+        value.boolean("default or absent frame"),
+        value.object({
+            radius: { anyOf: [value.number("radius in pixels"), value.literal("full", "fully rounded radius")] },
+            color: value.string("Appearance color role or CSS color"),
+            material: {
+                anyOf: [
+                    value.literal(false, "disabled Material"),
+                    value.object({
+                        grain: value.number("grain frequency"),
+                        grainAmount: value.number("grain intensity"),
+                        backdrop: value.number("backdrop blur"),
+                        opacity: value.number("Material opacity"),
+                        distortion: value.number("backdrop distortion"),
+                        saturation: value.number("backdrop saturation")
+                    }, [], "partial Appearance Material")
+                ]
+            }
+        }, [], "Window frame customization")
+    ]
+};
 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")
+    service: value.boolean("default Service role for new execution contexts")
 }, ["start", "service"], "resolved Server Endpoint declaration"));
 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"),
+    service: value.boolean("default Service role for new execution contexts"),
     title: value.nullable(value.string("default Window title")),
+    header: value.nullable(value.boolean("default Window header visibility")),
+    frame: value.nullable(frame),
+    transaction: value.nullable(transaction),
     size: value.nullable(value.object({ width: metric, height: metric }, ["width", "height"], "default Window size")),
     position: value.nullable(value.object({ x: metric, y: metric }, ["x", "y"], "default Window position")),
     layer: value.nullable(value.enumeration(layers, "default Window layer")),
     minimize: value.nullable(value.boolean("default minimized state")),
     maximize: value.nullable(value.boolean("default maximized state"))
-}, ["start", "service", "title", "size", "position", "layer", "minimize", "maximize"], "resolved Client Endpoint declaration"));
+}, ["start", "service", "title", "header", "frame", "transaction", "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"),
     name: value.string("human-readable Program name"),
-    version: value.nullable(value.string("Program version")),
+    version: value.string("Resolved Program version"),
     description: value.nullable(value.string("Program description")),
     installed: value.boolean("whether production files are installed"),
     hasAgent: value.boolean("whether the Program provides agent documentation"),
@@ -41,19 +76,28 @@ export const endpointOutput = value.object({
     program: value.string("owning Program identity"),
     endpoint: value.enumeration(["server", "client"], "Endpoint kind"),
     declared: value.boolean("whether the Program declares this Endpoint"),
-    running: value.boolean("whether the Endpoint currently exists"),
-    service: value.boolean("whether this Endpoint incarnation is addressable as a Service")
+    running: value.boolean("whether the Endpoint currently has a running execution context"),
+    service: value.boolean("whether this Endpoint execution context is addressable as a Service")
 }, ["process", "program", "endpoint", "declared", "running", "service"], "Endpoint state");
+export const serviceOutput = value.object({
+    program: value.string("owning Program identity"),
+    process: value.string("Process and Service name"),
+    endpoint: value.enumeration(["server", "client"], "Endpoint kind"),
+    available: value.boolean("whether a ready Endpoint is currently available at this address")
+}, ["program", "process", "endpoint", "available"], "Service state");
 export const windowOutput = value.object({
     process: value.string("owning Process identity"),
     title: value.string("Window title"),
+    header: value.boolean("whether the Desktop-owned Window header is shown"),
+    frame,
+    transaction,
     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(layers, "Window layer")
-}, ["process", "title", "position", "size", "minimized", "maximized", "front", "layer"], "Window state");
+}, ["process", "title", "header", "frame", "transaction", "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 = list("data", "Program", "Programs", "No matching Programs", [
     { label: "Name", path: "name" },
@@ -73,7 +117,13 @@ export const processListPresentation = list("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"], ["Header", "header"], ["Position", "position"], ["Size", "size"], ["Minimized", "minimized"], ["Maximized", "maximized"], ["Front", "front"], ["Layer", "layer"], ["Location", "location"]);
+export const servicePresentation = fields(["Program", "program"], ["Service", "process"], ["Endpoint", "endpoint"], ["Available", "available"]);
+export const serviceListPresentation = list("data", "Service", "Services", "No matching Services", [
+    { label: "Service", path: "process" },
+    { label: "Program", path: "program" },
+    { label: "Endpoint", path: "endpoint" }
+]);
+export const windowPresentation = fields(["Process", "process"], ["Title", "title"], ["Header", "header"], ["Frame", "frame"], ["Transaction", "transaction"], ["Position", "position"], ["Size", "size"], ["Minimized", "minimized"], ["Maximized", "maximized"], ["Front", "front"], ["Layer", "layer"]);
 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"]);
@@ -81,6 +131,8 @@ export const windowMinimizePresentation = fields(["Process", "process"], ["Minim
 export const windowMaximizePresentation = fields(["Process", "process"], ["Maximized", "maximized"]);
 export const windowTitlePresentation = fields(["Process", "process"], ["Title", "title"]);
 export const windowHeaderPresentation = fields(["Process", "process"], ["Header", "header"]);
+export const windowFramePresentation = fields(["Process", "process"], ["Frame", "frame"]);
+export const windowTransactionPresentation = fields(["Process", "process"], ["Transaction", "transaction"]);
 export const windowRaisePresentation = fields(["Process", "process"], ["Front", "front"]);
 export const eventPresentation = fields(["Scope", "scope"], ["Event", "event"], ["Payload", "payload"]);
 export const lifecyclePresentation = fields(["Scope", "scope"], ["Event", "event"]);
@@ -109,8 +161,8 @@ export function textOutput(description) {
 function endpointState(description) {
     return value.object({
         declared: value.boolean("whether the Program declares this Endpoint"),
-        running: value.boolean("whether the Endpoint currently exists"),
-        service: value.boolean("whether this Endpoint incarnation is a Service")
+        running: value.boolean("whether the Endpoint currently has a running execution context"),
+        service: value.boolean("whether this Endpoint execution context is a Service")
     }, ["declared", "running", "service"], description);
 }
 function fields(...values) {

package/dist/commands/service.js

@@ -0,0 +1,133 @@
+import { parseExecuteRequest } from "@phreshos/core";
+import { defineCommand } from "../contract/command.js";
+import { value } from "../contract/schema.js";
+import { dataOutput, eventOutput, eventPresentation, lifecyclePresentation, serviceListPresentation, serviceOutput, servicePresentation, valuePresentation } from "./schemas.js";
+import { connected } from "./connection.js";
+import { bounded, payload } from "./input.js";
+import { executeDescription } from "./execution.js";
+import { option, timeoutOption, withJson } from "./options.js";
+const addressOptions = [
+    option("--program <identity>", "owning Program identity", { mandatory: true }),
+    option("--process <name>", "Process and Service name", { mandatory: true }),
+    option("--endpoint <endpoint>", "Endpoint kind", { mandatory: true, choices: ["server", "client"] })
+];
+const availabilityEvents = ["available", "unavailable"];
+export default function serviceCommands(root, connect) {
+    const services = defineCommand(root, {
+        name: "service",
+        description: "discover and communicate with named Endpoint Services",
+        guidance: ["Discovery returns ready Services; exact addresses remain stable while their providers are unavailable."]
+    });
+    defineCommand(services, {
+        name: "list",
+        description: executeDescription("service", "list"),
+        requiresSystem: true,
+        options: withJson(),
+        output: dataOutput(value.array(serviceOutput, "ready Services"), "Visible Services", serviceListPresentation),
+        examples: ["phresh service list"]
+    }, async () => executeService(connect, { $operation: "list" }));
+    defineCommand(services, {
+        name: "search",
+        description: executeDescription("service", "search"),
+        requiresSystem: true,
+        options: withJson(option("--name <name>", "Process and Service name", { mandatory: true })),
+        output: dataOutput(value.array(serviceOutput, "matching ready Services"), "Matching Services", serviceListPresentation),
+        examples: ["phresh service search --name ssh"]
+    }, async ({ options }) => executeService(connect, { $operation: "search", name: options.name }));
+    defineCommand(services, {
+        name: "inspect",
+        description: executeDescription("service", "inspect"),
+        requiresSystem: true,
+        options: withJson(...addressOptions),
+        output: dataOutput(serviceOutput, "The selected Service", servicePresentation),
+        examples: ["phresh service inspect --program terminal --process ssh --endpoint server"]
+    }, async ({ options }) => executeAddressedService(connect, options, { $operation: "inspect" }));
+    defineCommand(services, {
+        name: "waitReady",
+        aliases: ["wait-ready"],
+        description: executeDescription("service", "waitReady"),
+        requiresSystem: true,
+        options: withJson(...addressOptions, timeoutOption),
+        output: dataOutput(serviceOutput, "The ready Service", servicePresentation),
+        examples: ["phresh service wait-ready --program terminal --process ssh --endpoint server"]
+    }, async ({ options }) => executeAddressedService(connect, options, {
+        $operation: "waitReady",
+        ...(options.timeout === undefined ? {} : { timeout: timeout(options.timeout) })
+    }));
+    defineCommand(services, {
+        name: "ask",
+        description: executeDescription("service", "ask"),
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "owning Program identity", { mandatory: true }), option("--process <name>", "Process and Service name", { mandatory: true }), option("--endpoint <endpoint>", "Endpoint kind", { mandatory: true, choices: ["server"] }), option("--event <event>", "event name", { mandatory: true }), option("--payload <json>", "arbitrary event payload as JSON"), timeoutOption),
+        output: dataOutput(value.any("answer returned by the Server Service contract"), "The Service answer", valuePresentation),
+        examples: ["phresh service ask --program tilo --process board --endpoint server --event board.list --json"]
+    }, async ({ options }) => executeAddressedService(connect, options, {
+        $operation: "ask",
+        event: options.event,
+        ...(options.payload === undefined ? {} : { input: payload(options.payload) }),
+        ...(options.timeout === undefined ? {} : { timeout: timeout(options.timeout) })
+    }));
+    defineCommand(services, {
+        name: "publish",
+        description: executeDescription("service", "publish"),
+        requiresSystem: true,
+        options: withJson(...addressOptions, option("--event <event>", "event name", { mandatory: true }), option("--payload <json>", "arbitrary event payload as JSON")),
+        output: dataOutput(serviceOutput, "The addressed Service", servicePresentation),
+        examples: ["phresh service publish --program tilo --process board --endpoint client --event changed"]
+    }, async ({ options }) => executeAddressedService(connect, options, {
+        $operation: "publish",
+        event: options.event,
+        ...(options.payload === undefined ? {} : { input: payload(options.payload) })
+    }));
+    defineCommand(services, {
+        name: "wait",
+        description: executeDescription("service", "wait"),
+        requiresSystem: true,
+        options: withJson(...addressOptions, option("--event <event>", "event name", { mandatory: true }), timeoutOption),
+        output: dataOutput(eventOutput("The observed Service event"), "One Service event", eventPresentation),
+        examples: ["phresh service wait --program tilo --process board --endpoint client --event changed"]
+    }, async ({ options }) => executeAddressedService(connect, options, {
+        $operation: "wait",
+        event: options.event,
+        ...(options.timeout === undefined ? {} : { timeout: timeout(options.timeout) })
+    }));
+    defineCommand(services, {
+        name: "waitLifecycle",
+        aliases: ["wait-lifecycle"],
+        description: executeDescription("service", "waitLifecycle"),
+        requiresSystem: true,
+        options: withJson(...addressOptions, option("--event <event>", "availability event", { mandatory: true, choices: availabilityEvents }), timeoutOption),
+        output: dataOutput(eventOutput("The observed Service availability event"), "One Service lifecycle event", lifecyclePresentation),
+        examples: ["phresh service wait-lifecycle --program tilo --process board --endpoint server --event available"]
+    }, async ({ options }) => executeAddressedService(connect, options, {
+        $operation: "waitLifecycle",
+        event: options.event,
+        ...(options.timeout === undefined ? {} : { timeout: timeout(options.timeout) })
+    }));
+    defineCommand(services, {
+        name: "waitDiscovery",
+        aliases: ["wait-discovery"],
+        description: executeDescription("service", "waitDiscovery"),
+        requiresSystem: true,
+        options: withJson(option("--event <event>", "discovery event", { mandatory: true, choices: availabilityEvents }), timeoutOption),
+        output: dataOutput(eventOutput("The observed Service discovery event"), "One Service discovery event", lifecyclePresentation),
+        examples: ["phresh service wait-discovery --event available"]
+    }, async ({ options }) => executeService(connect, {
+        $operation: "waitDiscovery",
+        event: options.event,
+        ...(options.timeout === undefined ? {} : { timeout: timeout(options.timeout) })
+    }));
+}
+function executeAddressedService(connect, options, operation) {
+    return executeService(connect, {
+        ...operation,
+        program: options.program,
+        process: options.process,
+        endpoint: options.endpoint
+    });
+}
+function executeService(connect, operation) {
+    const request = parseExecuteRequest({ $domain: "service", ...operation });
+    return connected(connect, system => system.execute(request));
+}
+function timeout(value) { return value === undefined ? undefined : bounded(value, "--timeout", 1); }

package/dist/commands/window.js

@@ -1,7 +1,7 @@
-import { parseExecuteRequest } from "@phreshos/core";
+import { parseExecuteRequest, parseWindowFrame, parseWindowTransaction } from "@phreshos/core";
 import { defineCommand } from "../contract/command.js";
 import { option, processOptions, timeoutOption, withJson } from "./options.js";
-import { dataOutput, eventOutput, eventPresentation, windowGeometryPresentation, windowHeaderPresentation, windowMinimizePresentation, windowMaximizePresentation, windowOutput, windowPositionPresentation, windowPresentation, windowRaisePresentation, windowSizePresentation, windowTitlePresentation } from "./schemas.js";
+import { dataOutput, eventOutput, eventPresentation, windowGeometryPresentation, windowFramePresentation, windowHeaderPresentation, windowMinimizePresentation, windowMaximizePresentation, windowOutput, windowPositionPresentation, windowTransactionPresentation, windowPresentation, windowRaisePresentation, windowSizePresentation, windowTitlePresentation } from "./schemas.js";
 import { connected } from "./connection.js";
 import { bounded, position, size } from "./input.js";
 import { executeDescription } from "./execution.js";
@@ -31,8 +31,8 @@ export default function windowCommands(root, connect) {
         examples: ["phresh window set-geometry --process main --program terminal --x 0 --y 0 --width 100% --height 100%"]
     }, async ({ options }) => executeWindow(connect, options, {
         $operation: "setGeometry",
-        position: position(options.x, options.y),
-        size: size(options.width, options.height)
+        ...position(options.x, options.y),
+        ...size(options.width, options.height)
     }));
     defineCommand(windows, {
         ...state("minimize", windowMinimizePresentation),
@@ -45,17 +45,38 @@ export default function windowCommands(root, connect) {
         examples: ["phresh window maximize --process main --program terminal", "phresh window maximize --process main --program terminal --restore"]
     }, async ({ options }) => executeWindow(connect, options, { $operation: "maximize", maximized: options.restore !== true }));
     defineCommand(windows, {
-        ...state("changeTitle", windowTitlePresentation),
-        aliases: ["change-title"],
+        ...state("setTitle", windowTitlePresentation),
+        aliases: ["set-title"],
         options: withJson(...processOptions, option("--title <title>", "new Window title", { mandatory: true })),
-        examples: ["phresh window change-title --process main --program terminal --title Shell"]
-    }, async ({ options }) => executeWindow(connect, options, { $operation: "changeTitle", title: options.title }));
+        examples: ["phresh window set-title --process main --program terminal --title Shell"]
+    }, async ({ options }) => executeWindow(connect, options, { $operation: "setTitle", title: options.title }));
     defineCommand(windows, {
-        ...state("changeHeader", windowHeaderPresentation),
-        aliases: ["change-header"],
+        ...state("setHeader", windowHeaderPresentation),
+        aliases: ["set-header"],
         options: withJson(...processOptions, option("--hide", "hide rather than show the Window header")),
-        examples: ["phresh window change-header --process main --program terminal --hide", "phresh window change-header --process main --program terminal"]
-    }, async ({ options }) => executeWindow(connect, options, { $operation: "changeHeader", header: options.hide !== true }));
+        examples: ["phresh window set-header --process main --program terminal --hide", "phresh window set-header --process main --program terminal"]
+    }, async ({ options }) => executeWindow(connect, options, { $operation: "setHeader", header: options.hide !== true }));
+    defineCommand(windows, {
+        ...state("setFrame", windowFramePresentation),
+        aliases: ["set-frame"],
+        options: withJson(...processOptions, option("--default", "use the default Window frame"), option("--absent", "remove the Window frame"), option("--radius <radius>", "frame radius in pixels or full"), option("--color <color>", "Appearance color role or CSS color"), option("--without-material", "render the frame without Material"), option("--grain <value>", "frame Material grain", { parse: input => numeric(input, "--grain") }), option("--grain-amount <value>", "frame Material grain intensity", { parse: input => numeric(input, "--grain-amount") }), option("--backdrop <value>", "frame Material backdrop blur", { parse: input => numeric(input, "--backdrop") }), option("--opacity <value>", "frame Material opacity", { parse: input => numeric(input, "--opacity") }), option("--distortion <value>", "frame Material distortion", { parse: input => numeric(input, "--distortion") }), option("--saturation <value>", "frame Material saturation", { parse: input => numeric(input, "--saturation") })),
+        examples: [
+            "phresh window set-frame --process overlay --absent",
+            "phresh window set-frame --process overlay --radius full --color primary"
+        ]
+    }, async ({ options }) => executeWindow(connect, options, { $operation: "setFrame", frame: frame(options) }));
+    defineCommand(windows, {
+        ...state("setTransaction", windowTransactionPresentation),
+        aliases: ["set-transaction"],
+        options: withJson(...processOptions, option("--default", "use the default Appearance transaction"), option("--disabled", "disable the default Window transaction"), option("--duration <milliseconds>", "transaction duration", { parse: input => numeric(input, "--duration") }), option("--easing <easing>", "standard easing name or four comma-separated cubic Bézier values")),
+        examples: [
+            "phresh window set-transaction --process overlay --default",
+            "phresh window set-transaction --process overlay --duration 240 --easing ease-out"
+        ]
+    }, async ({ options }) => executeWindow(connect, options, {
+        $operation: "setTransaction",
+        transaction: transaction(options)
+    }));
     defineCommand(windows, {
         ...state("raise", windowRaisePresentation),
         examples: ["phresh window raise --process main --program terminal"]
@@ -66,10 +87,10 @@ export default function windowCommands(root, connect) {
         requiresSystem: true,
         options: withJson(...processOptions, option("--event <event>", "Window event", {
             mandatory: true,
-            choices: ["move", "resize", "geometry", "minimize", "maximize", "changeTitle", "changeHeader", "front"]
+            choices: ["move", "resize", "minimize", "maximize", "changeTitle", "changeHeader", "changeFrame", "changeTransaction", "front"]
         }), timeoutOption),
         output: dataOutput(eventOutput("The observed Window event"), "One Window event", eventPresentation),
-        examples: ["phresh window wait --process main --program terminal --event geometry --json"]
+        examples: ["phresh window wait --process main --program terminal --event move --json"]
     }, async ({ options }) => executeWindow(connect, options, {
         $operation: "wait",
         event: options.event,
@@ -94,3 +115,61 @@ async function executeWindow(connect, options, operation) {
     });
     return connected(connect, system => system.execute(request));
 }
+function frame(options) {
+    const materialValues = material(options);
+    const customized = options.radius !== undefined || options.color !== undefined || materialValues !== undefined;
+    const modes = Number(options.default === true) + Number(options.absent === true) + Number(customized);
+    if (modes !== 1)
+        throw new Error("Choose exactly one of --default, --absent, or frame customization options");
+    if (options.default)
+        return true;
+    if (options.absent)
+        return false;
+    return parseWindowFrame({
+        ...(options.radius === undefined ? {} : { radius: options.radius === "full" ? "full" : numeric(options.radius, "--radius") }),
+        ...(options.color === undefined ? {} : { color: options.color }),
+        ...(materialValues === undefined ? {} : { material: materialValues })
+    });
+}
+function material(options) {
+    const values = {
+        grain: options.grain,
+        grainAmount: options.grainAmount,
+        backdrop: options.backdrop,
+        opacity: options.opacity,
+        distortion: options.distortion,
+        saturation: options.saturation
+    };
+    const customized = Object.values(values).some(value => value !== undefined);
+    const modes = Number(options.withoutMaterial === true) + Number(customized);
+    if (modes > 1)
+        throw new Error("Choose only one Material mode");
+    if (options.withoutMaterial)
+        return false;
+    if (!customized)
+        return undefined;
+    return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+}
+function transaction(options) {
+    const customized = options.duration !== undefined || options.easing !== undefined;
+    const modes = Number(options.default === true) + Number(options.disabled === true) + Number(customized);
+    if (modes !== 1)
+        throw new Error("Choose exactly one of --default, --disabled, or --duration");
+    if (options.default)
+        return true;
+    if (options.disabled)
+        return false;
+    if (options.duration === undefined)
+        throw new Error("--easing requires --duration");
+    if (options.easing === undefined)
+        return parseWindowTransaction(options.duration);
+    const pieces = options.easing.split(",").map(value => value.trim());
+    const easing = pieces.length === 4 ? pieces.map(value => numeric(value, "--easing")) : options.easing;
+    return parseWindowTransaction({ duration: options.duration, easing });
+}
+function numeric(value, name) {
+    const result = Number(value);
+    if (!Number.isFinite(result))
+        throw new Error(`${name} must be a finite number`);
+    return result;
+}

package/dist/install.js

@@ -5,7 +5,7 @@ import { prepareOfficialProgram } from "./program-release.js";
 /**
  * Lay this program out on this machine's system.
  *
- * A local project is built and derived from its authoring declaration. An
+ * A local project is built and derived from its authoring definition. An
  * official name resolves a verified production package and turns its
  * canonical paths into the same concrete definition. From that point on,
  * both sources cross the exact same gateway and the System performs the exact
@@ -15,8 +15,7 @@ import { prepareOfficialProgram } from "./program-release.js";
  * production Program is derived and sent. The command remains authoring
  * metadata and never becomes part of the installed Program.
  *
- * The System executes the Program's stored startup after installation.
- * `run` requests an additional Process before startup, created by System. It belongs
+ * `run` overrides the Program's install launch with one default Process. It 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.

package/dist/program-installation.js

@@ -17,8 +17,9 @@ export default async function installProgram(program, options = {}) {
         }
         else
             installed = await system.program.forceCreate(program);
-        if (options.run)
-            stopObserving = installed.subscribe("processCreate", created => { process ??= created.identity; });
+        // A definition-owned installLaunch can create the Process even when
+        // the CLI did not supply --run, so observation belongs to installation.
+        stopObserving = installed.subscribe("processCreate", created => { process ??= created.identity; });
         for await (const chunk of installed.install({ launch: options.run ? true : undefined, purge: options.purge }))
             writeProgramCommandOutput(chunk);
         installationFinished = true;

package/dist/template/package.json

@@ -1,7 +1,7 @@
 {
     "name": "phresh",
     "private": true,
-    "version": "0.1.40",
+    "version": "0.1.42",
     "description": "The official PhreshOS starter Program.",
     "type": "module",
     "scripts": {
@@ -14,15 +14,15 @@
         "starter"
     ],
     "dependencies": {
-        "@phreshos/client": "^0.1.46",
-        "@phreshos/core": "^0.1.54",
-        "@phreshos/react": "^0.1.28",
-        "@phreshos/server": "^0.1.50",
+        "@phreshos/client": "^0.1.48",
+        "@phreshos/core": "^0.1.56",
+        "@phreshos/react": "^0.1.29",
+        "@phreshos/server": "^0.1.52",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.65",
+        "@phreshos/cli": "^0.1.67",
         "@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.40",
+    version: "0.1.42",
     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.40",
-    "sha256": "7f2bb99438c7224e543147519a75d76a1db04313ff6ec6b024bb7532feb6a017",
+    "version": "0.1.42",
+    "sha256": "a05d624c773f52acaf7b16f65b0fd8f421bf61e7caad84348e4ec3871ae019cd",
     "development": true
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@phreshos/cli",
   "type": "module",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "description": "The Phresh command-line interface for Program projects and system management.",
   "engines": {
     "node": ">=20.10"
@@ -47,8 +47,8 @@
   "packageManager": "bun@1.3.14",
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@phreshos/core": "^0.1.54",
-    "@phreshos/node": "^0.1.27",
+    "@phreshos/core": "^0.1.56",
+    "@phreshos/node": "^0.1.29",
     "adm-zip": "^0.6.0",
     "commander": "^15.0.0",
     "picocolors": "^1.1.1"