@phreshos/cli 0.1.51 → 0.1.53

package/README.md

@@ -41,6 +41,10 @@ to read the complete machine-discoverable contract. See the
 [CLI documentation](https://docs.phreshos.com/sdks/cli) for Program project,
 System, and runtime commands.
 
+Runtime commands render responsive tables or labeled fields for people by
+default. Add `--json` to receive the complete result as one JSON value for
+automation.
+
 ## Development
 
 ```sh

package/dist/commands/describe.js

@@ -1,7 +1,7 @@
 import { defineCommand, readCommandContract } from "../contract/command.js";
 import { value } from "../contract/schema.js";
 import { jsonOption, option } from "./options.js";
-import { jsonOutput } from "./schemas.js";
+import { commandPresentation, dataOutput } from "./schemas.js";
 /** Expose the authoritative CLI contract without contacting the System. */
 export default function describeCommands(root) {
     defineCommand(root, {
@@ -14,7 +14,7 @@ export default function describeCommands(root) {
         ],
         guidance: ["Omit the path to start at the CLI root. Add --all to retrieve the complete selected contract tree."],
         examples: ["phresh describe", "phresh describe process create", "phresh describe --all --json"],
-        output: jsonOutput(value.any("one command contract or a complete contract tree"), "CLI command contract")
+        output: dataOutput(value.any("one command contract or a complete contract tree"), "CLI command contract", commandPresentation)
     }, ({ arguments: [path], options }) => {
         const command = resolveCommand(root, path);
         return options.all ? describeTree(command, path) : describe(command, path);

package/dist/commands/endpoint.js

@@ -1,7 +1,7 @@
 import { defineCommand } from "../contract/command.js";
 import { value } from "../contract/schema.js";
 import { clientOverrideOptions, endpointOptions, option, serverOverrideOptions, timeoutOption, withJson } from "./options.js";
-import { endpointOutput, eventOutput, jsonOutput } from "./schemas.js";
+import { dataOutput, endpointActionPresentation, endpointOutput, endpointPresentation, eventOutput, eventPresentation, lifecyclePresentation, valuePresentation } from "./schemas.js";
 import { connected, requireProcess } from "./connection.js";
 import { bounded, clientLaunch, payload, serverLaunch } from "./input.js";
 import { wait } from "./observation.js";
@@ -17,7 +17,7 @@ export default function endpointCommands(root, connect) {
         description: "read whether one Endpoint is declared and running",
         requiresSystem: true,
         options: withJson(...endpointOptions),
-        output: jsonOutput(endpointOutput, "The selected Endpoint"),
+        output: dataOutput(endpointOutput, "The selected Endpoint", endpointPresentation),
         examples: ["phresh endpoint inspect --process main --program terminal --endpoint server"]
     }, async ({ options }) => withEndpoint(connect, options, async (process, name) => {
         return await endpointView(process, name);
@@ -27,7 +27,7 @@ export default function endpointCommands(root, connect) {
         description: "start a fresh Endpoint incarnation",
         requiresSystem: true,
         options: withJson(...endpointOptions, ...clientOverrideOptions, ...serverOverrideOptions),
-        output: jsonOutput(endpointOutput, "The started Endpoint"),
+        output: dataOutput(endpointOutput, "The started Endpoint", endpointActionPresentation),
         examples: ["phresh endpoint start --process main --program terminal --endpoint server --server-service"]
     }, async ({ options }) => withEndpoint(connect, options, async (process, name) => {
         const client = clientLaunch(options);
@@ -47,7 +47,7 @@ export default function endpointCommands(root, connect) {
         description: "stop one Endpoint",
         requiresSystem: true,
         options: withJson(...endpointOptions),
-        output: jsonOutput(endpointOutput, "The stopped Endpoint"),
+        output: dataOutput(endpointOutput, "The stopped Endpoint", endpointActionPresentation),
         examples: ["phresh endpoint stop --process main --program terminal --endpoint client"]
     }, async ({ options }) => withEndpoint(connect, options, async (process, name) => {
         await endpoint(process, name).stop();
@@ -59,7 +59,7 @@ export default function endpointCommands(root, connect) {
         description: "wait until the Server Endpoint reports readiness",
         requiresSystem: true,
         options: withJson(...endpointOptions, timeoutOption),
-        output: jsonOutput(endpointOutput, "The ready Server Endpoint"),
+        output: dataOutput(endpointOutput, "The ready Server Endpoint", endpointActionPresentation),
         examples: ["phresh endpoint wait-ready --process main --program terminal --endpoint server --timeout 30000"]
     }, async ({ options }) => withEndpoint(connect, options, async (process, name) => {
         if (name !== "server")
@@ -73,10 +73,10 @@ export default function endpointCommands(root, connect) {
         description: "wait for one lifecycle transition of an exact Endpoint",
         requiresSystem: true,
         options: withJson(...endpointOptions, option("--event <event>", "Endpoint lifecycle event", { mandatory: true, choices: ["start", "stop"] }), timeoutOption),
-        output: jsonOutput(value.object({
+        output: dataOutput(value.object({
             scope: value.string("Endpoint lifecycle subscription scope"),
             event: value.enumeration(["start", "stop"], "observed lifecycle event")
-        }, ["scope", "event"], "Endpoint lifecycle event"), "One Endpoint lifecycle event"),
+        }, ["scope", "event"], "Endpoint lifecycle event"), "One Endpoint lifecycle event", lifecyclePresentation),
         examples: ["phresh endpoint wait-lifecycle --process main --program terminal --endpoint server --event start"]
     }, async ({ options }) => withEndpoint(connect, options, async (process, name) => {
         await wait(endpoint(process, name).lifecycle, options.event, timeout(options.timeout));
@@ -87,7 +87,7 @@ export default function endpointCommands(root, connect) {
         description: "ask a Server event and return its answer",
         requiresSystem: true,
         options: withJson(...endpointOptions, option("--event <event>", "event name", { mandatory: true }), option("--payload <json>", "arbitrary event payload as JSON"), timeoutOption),
-        output: jsonOutput(value.any("answer returned by the Server event contract"), "The Server answer"),
+        output: dataOutput(value.any("answer returned by the Server event contract"), "The Server answer", valuePresentation),
         examples: ["phresh endpoint ask --process main --program terminal --endpoint server --event status --json"]
     }, async ({ options }) => withEndpoint(connect, options, async (process, name) => {
         if (name !== "server")
@@ -103,7 +103,7 @@ export default function endpointCommands(root, connect) {
         description: "publish one event without waiting for an answer",
         requiresSystem: true,
         options: withJson(...endpointOptions, option("--event <event>", "event name", { mandatory: true }), option("--payload <json>", "arbitrary event payload as JSON")),
-        output: jsonOutput(endpointOutput, "The Endpoint after publishing"),
+        output: dataOutput(endpointOutput, "The Endpoint after publishing", endpointActionPresentation),
         examples: ["phresh endpoint publish --process main --program terminal --endpoint client --event changed --payload '{\"value\":1}'"]
     }, async ({ options }) => withEndpoint(connect, options, async (process, name) => {
         endpoint(process, name).publish(options.event, payload(options.payload));
@@ -114,7 +114,7 @@ export default function endpointCommands(root, connect) {
         description: "wait for the next event emitted by one live Endpoint",
         requiresSystem: true,
         options: withJson(...endpointOptions, option("--event <event>", "event name", { mandatory: true }), timeoutOption),
-        output: jsonOutput(eventOutput("The observed Endpoint event"), "One Endpoint event"),
+        output: dataOutput(eventOutput("The observed Endpoint event"), "One Endpoint event", eventPresentation),
         examples: ["phresh endpoint wait --process main --program terminal --endpoint client --event changed --json"]
     }, async ({ options }) => withEndpoint(connect, options, async (process, name) => {
         return {

package/dist/commands/process.js

@@ -1,7 +1,7 @@
 import { defineCommand } from "../contract/command.js";
 import { value } from "../contract/schema.js";
 import { launchOptions, namedLaunchOptions, option, processOptions, timeoutOption, withJson } from "./options.js";
-import { eventOutput, jsonOutput, pageOutput, processOutput } from "./schemas.js";
+import { dataOutput, eventOutput, eventPresentation, pageOutput, processActionPresentation, processIdentityPresentation, processListPresentation, processOutput, processPresentation } from "./schemas.js";
 import { connected, requireProcess, requireProgram } from "./connection.js";
 import { bounded, integer, launch, page } from "./input.js";
 import { wait } from "./observation.js";
@@ -17,7 +17,7 @@ export default function processCommands(root, connect) {
         description: "list live Processes with bounded filtering",
         requiresSystem: true,
         options: withJson(option("--program <identity>", "restrict results to one Program"), option("--search <text>", "case-insensitive identity or name search"), option("--limit <count>", "maximum returned Processes", { parse: value => integer(value), default: 30 }), option("--offset <count>", "number of matching Processes to skip", { parse: value => integer(value), default: 0 })),
-        output: jsonOutput(pageOutput(processOutput, "matching Processes"), "A bounded page of Processes"),
+        output: dataOutput(pageOutput(processOutput, "matching Processes"), "A bounded page of Processes", processListPresentation),
         examples: ["phresh process list", "phresh process list --program terminal --json"]
     }, async ({ options }) => connected(connect, async (system) => {
         const processes = options.program
@@ -31,7 +31,7 @@ export default function processCommands(root, connect) {
         description: "read one live Process and its Endpoint state",
         requiresSystem: true,
         options: withJson(...processOptions),
-        output: jsonOutput(processOutput, "The selected Process"),
+        output: dataOutput(processOutput, "The selected Process", processPresentation),
         examples: ["phresh process inspect --process main --program terminal"]
     }, async ({ options }) => connected(connect, async (system) => {
         return await processView(await requireProcess(system, options.process, options.program));
@@ -41,7 +41,7 @@ export default function processCommands(root, connect) {
         description: "create a Process",
         requiresSystem: true,
         options: withJson(option("--program <identity>", "owning Program identity", { mandatory: true }), ...launchOptions),
-        output: jsonOutput(processOutput, "The created Process"),
+        output: dataOutput(processOutput, "The created Process", processActionPresentation),
         examples: ["phresh process create --program terminal --server --client", "phresh process create --program terminal --name main --json"]
     }, async ({ options }) => connected(connect, async (system) => {
         const program = await requireProgram(system, options.program);
@@ -53,7 +53,7 @@ export default function processCommands(root, connect) {
         description: "find the named Process or create it atomically",
         requiresSystem: true,
         options: withJson(option("--program <identity>", "owning Program identity", { mandatory: true }), ...namedLaunchOptions),
-        output: jsonOutput(processOutput, "The existing or created Process"),
+        output: dataOutput(processOutput, "The existing or created Process", processActionPresentation),
         examples: ["phresh process find-or-create --program terminal --name main --json"]
     }, async ({ options }) => connected(connect, async (system) => {
         const program = await requireProgram(system, options.program);
@@ -64,7 +64,7 @@ export default function processCommands(root, connect) {
         description: "exit one Process and all of its live Endpoints",
         requiresSystem: true,
         options: withJson(...processOptions),
-        output: jsonOutput(processOutput, "The Process state immediately before exit"),
+        output: dataOutput(processOutput, "The Process state immediately before exit", processIdentityPresentation),
         examples: ["phresh process exit --process main --program terminal"]
     }, async ({ options }) => connected(connect, async (system) => {
         const process = await requireProcess(system, options.process, options.program);
@@ -77,7 +77,7 @@ export default function processCommands(root, connect) {
         description: "wait for one Process lifecycle event",
         requiresSystem: true,
         options: withJson(option("--event <event>", "Process lifecycle event", { mandatory: true, choices: ["create", "exit"] }), option("--process <identity>", "scope the event to one Process"), option("--program <identity>", "scope the event to one Program"), timeoutOption),
-        output: jsonOutput(eventOutput("The observed Process event", value.any("Process state or exit result")), "One Process event"),
+        output: dataOutput(eventOutput("The observed Process event", value.any("Process state or exit result")), "One Process event", eventPresentation),
         examples: ["phresh process wait --event create", "phresh process wait --event exit --process main --program terminal --json"]
     }, async ({ options }) => connected(connect, async (system) => {
         if (options.process && options.event === "create")

package/dist/commands/program.js

@@ -1,7 +1,7 @@
 import { defineCommand } from "../contract/command.js";
 import { value } from "../contract/schema.js";
 import { option, timeoutOption, withJson } from "./options.js";
-import { eventOutput, jsonOutput, pageOutput, programOutput } from "./schemas.js";
+import { dataOutput, eventOutput, eventPresentation, pageOutput, programListPresentation, programOutput, programPresentation } from "./schemas.js";
 import { connected, requireProgram } from "./connection.js";
 import { bounded, integer, page } from "./input.js";
 import { wait } from "./observation.js";
@@ -17,7 +17,7 @@ export default function programCommands(root, connect) {
         description: "list Programs with bounded filtering",
         requiresSystem: true,
         options: withJson(option("--installed-only", "return only installed Programs"), option("--search <text>", "case-insensitive identity, name, or description search"), option("--limit <count>", "maximum returned Programs", { parse: value => integer(value), default: 30 }), option("--offset <count>", "number of matching Programs to skip", { parse: value => integer(value), default: 0 })),
-        output: jsonOutput(pageOutput(programOutput, "matching Programs"), "A bounded page of Programs"),
+        output: dataOutput(pageOutput(programOutput, "matching Programs"), "A bounded page of Programs", programListPresentation),
         examples: ["phresh program list", "phresh program list --installed-only --json"]
     }, async ({ options }) => connected(connect, async (system) => {
         const programs = await system.program.list(options.installedOnly === true);
@@ -29,7 +29,7 @@ export default function programCommands(root, connect) {
         description: "read one Program declaration and installed state",
         requiresSystem: true,
         options: withJson(option("--program <identity>", "Program identity", { mandatory: true })),
-        output: jsonOutput(programOutput, "The selected Program"),
+        output: dataOutput(programOutput, "The selected Program", programPresentation),
         examples: ["phresh program inspect --program terminal"]
     }, async ({ options }) => connected(connect, async (system) => {
         return await programView(await requireProgram(system, options.program));
@@ -39,10 +39,13 @@ export default function programCommands(root, connect) {
         description: "read a Program's own agent operating policy",
         requiresSystem: true,
         options: withJson(option("--program <identity>", "Program identity", { mandatory: true })),
-        output: jsonOutput(value.object({
+        output: dataOutput(value.object({
             program: value.string("Program identity"),
             content: value.string("Program-owned agent documentation")
-        }, ["program", "content"], "Program agent documentation"), "The Program's agent documentation"),
+        }, ["program", "content"], "Program agent documentation"), "The Program's agent documentation", {
+            format: "document",
+            content: "content"
+        }),
         examples: ["phresh program agent --program terminal --json"]
     }, async ({ options }) => connected(connect, async (system) => {
         const program = await requireProgram(system, options.program);
@@ -59,7 +62,7 @@ export default function programCommands(root, connect) {
             mandatory: true,
             choices: ["create", "forget", "install", "uninstall"]
         }), option("--program <identity>", "scope forget or uninstall to one Program"), timeoutOption),
-        output: jsonOutput(eventOutput("The observed Program event", value.any("Program state or uninstall result")), "One Program event"),
+        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"]
     }, async ({ options }) => connected(connect, async (system) => {
         if (options.program && options.event !== "forget" && options.event !== "uninstall") {

package/dist/commands/schemas.js

@@ -1,3 +1,4 @@
+import { clientPermissionCatalog } from "@phreshos/core";
 import { value } from "../contract/schema.js";
 const metric = {
     anyOf: [value.number("pixels"), value.string("workspace-relative expression")]
@@ -6,13 +7,10 @@ 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({
-    all: value.array(value.string("permission value"), "all permission values"),
-    services: value.array(value.string("Program identity"), "permitted Service Programs"),
-    programs: value.array(value.string("Program identity"), "permitted Programs"),
-    appearance: value.array(value.string("permission value"), "appearance permission values"),
-    desktopPreferences: value.array(value.string("permission value"), "Desktop preferences permission values")
-}, [], "immutable Client permissions");
+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"),
@@ -60,6 +58,36 @@ export const windowOutput = value.object({
     layer: value.enumeration(["window", "under", "over"], "Window layer"),
     location: value.string("current Client location")
 }, ["process", "title", "position", "size", "minimized", "front", "layer", "location"], "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 },
+    { label: "Identity", path: "identity", width: 2 },
+    { label: "Version", path: "version" },
+    { label: "Installed", path: "installed" }
+]);
+export const processPresentation = fields(["Identity", "identity"], ["Name", "name"], ["Program", "program"], ["Started", "startedAt"], ["Server declared", "server.declared"], ["Server running", "server.running"], ["Server service", "server.service"], ["Client declared", "client.declared"], ["Client running", "client.running"], ["Client service", "client.service"]);
+export const processActionPresentation = fields(["Process", "identity"], ["Name", "name"], ["Program", "program"], ["Server", "server.running"], ["Client", "client.running"]);
+export const processIdentityPresentation = fields(["Process", "identity"], ["Program", "program"]);
+export const processListPresentation = table("data", "Process", "Processes", "No matching Processes", [
+    { label: "Name", path: "name", width: 2 },
+    { label: "Identity", path: "identity", width: 2 },
+    { label: "Program", path: "program", width: 2 },
+    { label: "Server", path: "server.running" },
+    { label: "Client", path: "client.running" }
+]);
+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 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 windowTitlePresentation = fields(["Process", "process"], ["Title", "title"]);
+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"]);
+export const commandPresentation = fields(["Path", "path"], ["Name", "name"], ["Aliases", "aliases"], ["Description", "description"], ["Arguments", "arguments"], ["Options", "options"], ["Guidance", "guidance"], ["Examples", "examples"], ["Requires System", "requiresSystem"], ["Output", "output"], ["Commands", "commands"]);
+export const valuePresentation = { format: "value" };
 export function pageOutput(items, description) {
     return value.object({
         data: value.array(items, description),
@@ -74,8 +102,8 @@ export function eventOutput(description, payload = value.any("event payload")) {
         payload
     }, ["scope", "event", "payload"], description);
 }
-export function jsonOutput(schema, description) {
-    return { format: "json", description, value: schema };
+export function dataOutput(schema, description, presentation) {
+    return { format: "data", description, value: schema, presentation };
 }
 export function textOutput(description) {
     return { format: "text", description };
@@ -87,3 +115,19 @@ function endpointState(description) {
         service: value.boolean("whether this Endpoint incarnation is a Service")
     }, ["declared", "running", "service"], description);
 }
+function fields(...values) {
+    return {
+        format: "fields",
+        fields: values.map(([label, path]) => ({ label, path }))
+    };
+}
+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 { eventOutput, jsonOutput, windowOutput } from "./schemas.js";
+import { dataOutput, eventOutput, eventPresentation, windowGeometryPresentation, windowMinimizePresentation, 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";
@@ -11,11 +11,11 @@ export default function windowCommands(root, connect) {
         description: "inspect and control authoritative Client Windows",
         guidance: ["A Window belongs to the Client Endpoint of one exact Process."]
     });
-    defineCommand(windows, state("inspect", "read the complete current Window state"), async ({ options }) => {
+    defineCommand(windows, state("inspect", "read the complete current Window state", windowPresentation), async ({ options }) => {
         return await withWindow(connect, options, windowView);
     });
     defineCommand(windows, {
-        ...state("move", "change Window position"),
+        ...state("move", "change Window position", windowPositionPresentation),
         options: withJson(...processOptions, option("--x <value>", "horizontal pixels or workspace-relative expression", { mandatory: true }), option("--y <value>", "vertical pixels or workspace-relative expression", { mandatory: true })),
         examples: ["phresh window move --process main --program terminal --x 50% --y 0"]
     }, async ({ options }) => withWindow(connect, options, async (process) => {
@@ -23,7 +23,7 @@ export default function windowCommands(root, connect) {
         return await windowView(process);
     }));
     defineCommand(windows, {
-        ...state("resize", "change Window size"),
+        ...state("resize", "change Window size", windowSizePresentation),
         options: withJson(...processOptions, option("--width <value>", "width in pixels or a workspace-relative expression", { mandatory: true }), option("--height <value>", "height in pixels or a workspace-relative expression", { mandatory: true })),
         examples: ["phresh window resize --process main --program terminal --width 800 --height 600"]
     }, async ({ options }) => withWindow(connect, options, async (process) => {
@@ -31,7 +31,7 @@ export default function windowCommands(root, connect) {
         return await windowView(process);
     }));
     defineCommand(windows, {
-        ...state("setGeometry", "change Window position and size atomically"),
+        ...state("setGeometry", "change Window position and size atomically", windowGeometryPresentation),
         aliases: ["set-geometry"],
         options: withJson(...processOptions, option("--x <value>", "horizontal pixels or workspace-relative expression", { mandatory: true }), option("--y <value>", "vertical pixels or workspace-relative expression", { mandatory: true }), option("--width <value>", "width in pixels or a workspace-relative expression", { mandatory: true }), option("--height <value>", "height in pixels or a workspace-relative expression", { mandatory: true })),
         examples: ["phresh window set-geometry --process main --program terminal --x 0 --y 0 --width 100% --height 100%"]
@@ -43,7 +43,7 @@ export default function windowCommands(root, connect) {
         return await windowView(process);
     }));
     defineCommand(windows, {
-        ...state("minimize", "set Window visibility without changing its order"),
+        ...state("minimize", "set Window visibility without changing its order", windowMinimizePresentation),
         options: withJson(...processOptions, option("--restore", "restore rather than minimize the Window")),
         examples: ["phresh window minimize --process main --program terminal", "phresh window minimize --process main --program terminal --restore"]
     }, async ({ options }) => withWindow(connect, options, async (process) => {
@@ -51,7 +51,7 @@ export default function windowCommands(root, connect) {
         return await windowView(process);
     }));
     defineCommand(windows, {
-        ...state("changeTitle", "change the human-readable Window title"),
+        ...state("changeTitle", "change the human-readable Window title", windowTitlePresentation),
         aliases: ["change-title"],
         options: withJson(...processOptions, option("--title <title>", "new Window title", { mandatory: true })),
         examples: ["phresh window change-title --process main --program terminal --title Shell"]
@@ -60,7 +60,7 @@ export default function windowCommands(root, connect) {
         return await windowView(process);
     }));
     defineCommand(windows, {
-        ...state("raise", "raise the Window within its own layer"),
+        ...state("raise", "raise the Window within its own layer", windowRaisePresentation),
         examples: ["phresh window raise --process main --program terminal"]
     }, async ({ options }) => withWindow(connect, options, async (process) => {
         await windowOf(process).raise();
@@ -74,7 +74,7 @@ export default function windowCommands(root, connect) {
             mandatory: true,
             choices: ["move", "resize", "geometry", "minimize", "changeTitle", "front"]
         }), timeoutOption),
-        output: jsonOutput(eventOutput("The observed Window event"), "One Window event"),
+        output: dataOutput(eventOutput("The observed Window event"), "One Window event", eventPresentation),
         examples: ["phresh window wait --process main --program terminal --event geometry --json"]
     }, async ({ options }) => withWindow(connect, options, async (process) => {
         return {
@@ -86,13 +86,13 @@ export default function windowCommands(root, connect) {
         };
     }));
 }
-function state(name, description) {
+function state(name, description, presentation) {
     return {
         name,
         description,
         requiresSystem: true,
         options: withJson(...processOptions),
-        output: jsonOutput(windowOutput, "The current Window state")
+        output: dataOutput(windowOutput, "The current Window state", presentation)
     };
 }
 async function withWindow(connect, options, action) {

package/dist/contract/command.js

@@ -1,5 +1,5 @@
 import { Argument, Command, Option } from "commander";
-import { assertValue } from "./schema.js";
+import { writeData } from "../output/write.js";
 const contracts = new WeakMap();
 /** Register one command from the contract used by help, discovery, and execution. */
 export function defineCommand(parent, contract, execute) {
@@ -24,8 +24,8 @@ export function defineCommand(parent, contract, execute) {
             const owner = received.pop();
             const options = received.pop();
             const result = await execute({ arguments: received, options, command: owner });
-            if (contract.output?.format === "json")
-                writeJson(result, contract.output, options.json === true);
+            if (contract.output?.format === "data")
+                writeData(result, contract.output, options.json === true);
         });
     return command;
 }
@@ -82,11 +82,3 @@ function pathOf(command) {
     }
     return path;
 }
-function writeJson(result, contract, compact) {
-    const normalized = result ?? null;
-    if (contract.value)
-        assertValue(normalized, contract.value);
-    console.log(JSON.stringify(normalized, null, compact ? undefined : 2));
-    if (!compact)
-        console.log();
-}

package/dist/contract/schema.js

@@ -38,6 +38,9 @@ export function assertValue(value, contract, path = "result") {
     if (contract.type === "array") {
         if (!Array.isArray(value))
             throw new Error(`${path} must be an array`);
+        if (contract.maxItems !== undefined && value.length > contract.maxItems) {
+            throw new Error(`${path} must contain no more than ${contract.maxItems} values`);
+        }
         if (contract.items)
             value.forEach((item, index) => assertValue(item, contract.items, `${path}[${index}]`));
         return;

package/dist/output/table.js

@@ -0,0 +1,88 @@
+import Table from "cli-table3";
+import stringWidth from "string-width";
+const style = Object.freeze({ head: [], border: [] });
+/** Render a table at its natural width, constraining and wrapping it only when necessary. */
+export function renderTable(fields, rows) {
+    const width = terminalWidth();
+    if (width < minimumTableWidth(fields)) {
+        return rows.map(row => renderFields(fields, row)).join("\n");
+    }
+    const natural = createTable(fields, rows);
+    const rendered = natural.toString();
+    if (rendered.split("\n").every(line => stringWidth(line) <= width))
+        return rendered;
+    return createTable(fields, rows, allocateWidths(width, fields)).toString();
+}
+/** Render one value vertically so field names remain readable on narrow terminals. */
+export function renderFields(fields, source) {
+    const rows = fields.map(field => [field.label, display(readPath(source, field.path), true)]);
+    const width = terminalWidth();
+    const desiredLabelWidth = Math.max(6, ...fields.map(field => stringWidth(field.label) + 2));
+    const labelWidth = Math.min(24, Math.max(6, width - 11), desiredLabelWidth);
+    const valueWidth = Math.max(8, width - labelWidth - 3);
+    const table = new Table({
+        colWidths: [labelWidth, valueWidth],
+        wordWrap: true,
+        wrapOnWordBoundary: false,
+        style
+    });
+    table.push(...rows);
+    return table.toString();
+}
+export function readPath(source, path) {
+    if (!path)
+        return source;
+    return path.split(".").reduce((current, key) => {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        return current[key];
+    }, source);
+}
+export function display(value, expanded = false) {
+    if (value === null || value === undefined || value === "")
+        return "—";
+    if (typeof value === "boolean")
+        return value ? "yes" : "no";
+    if (typeof value === "string" || typeof value === "number" || typeof value === "bigint")
+        return String(value);
+    if (Array.isArray(value) && !expanded)
+        return value.length ? value.map(item => display(item)).join(", ") : "—";
+    return JSON.stringify(value, null, expanded ? 2 : undefined);
+}
+function createTable(fields, rows, colWidths) {
+    const table = new Table({
+        head: fields.map(field => field.label),
+        ...(colWidths ? { colWidths } : {}),
+        wordWrap: true,
+        wrapOnWordBoundary: false,
+        style
+    });
+    table.push(...rows.map(row => fields.map(field => display(readPath(row, field.path)))));
+    return table;
+}
+function allocateWidths(width, fields) {
+    const minimums = fields.map(field => minimumColumnWidth(field));
+    const available = width - fields.length - 1;
+    const remaining = available - minimums.reduce((total, current) => total + current, 0);
+    const weights = fields.map(field => field.width ?? 1);
+    const totalWeight = weights.reduce((total, current) => total + current, 0);
+    const widths = minimums.map((minimum, index) => minimum + Math.floor(remaining * weights[index] / totalWeight));
+    let remainder = available - widths.reduce((total, current) => total + current, 0);
+    for (let index = 0; remainder > 0; index = (index + 1) % widths.length) {
+        widths[index] = widths[index] + 1;
+        remainder--;
+    }
+    return widths;
+}
+function minimumTableWidth(fields) {
+    return fields.reduce((total, field) => total + minimumColumnWidth(field), fields.length + 1);
+}
+function minimumColumnWidth(field) {
+    return Math.max(6, stringWidth(field.label) + 2);
+}
+function terminalWidth() {
+    const configured = Number(process.env.COLUMNS);
+    if (Number.isFinite(configured) && configured > 0)
+        return Math.floor(configured);
+    return process.stdout.columns ?? 80;
+}

package/dist/output/write.js

@@ -0,0 +1,39 @@
+import { inspect } from "node:util";
+import { assertValue } from "../contract/schema.js";
+import { readPath, renderFields, renderTable } from "./table.js";
+/** Validate command data once, then select its machine or human representation. */
+export function writeData(result, contract, machine) {
+    const normalized = result ?? null;
+    assertValue(normalized, contract.value);
+    if (machine) {
+        console.log(JSON.stringify(normalized));
+        return;
+    }
+    console.log(render(normalized, contract.presentation));
+    console.log();
+}
+function render(value, presentation) {
+    switch (presentation.format) {
+        case "table": return renderCollection(value, presentation);
+        case "fields": return renderFields(presentation.fields, value);
+        case "document": return String(readPath(value, presentation.content) ?? "");
+        case "value": return inspect(value, { colors: false, depth: null, compact: false });
+    }
+}
+function renderCollection(value, presentation) {
+    const selected = readPath(value, presentation.rows);
+    const rows = Array.isArray(selected) ? selected : [];
+    if (rows.length === 0)
+        return presentation.empty;
+    const table = renderTable(presentation.columns, rows);
+    const totalValue = presentation.total ? readPath(value, presentation.total) : rows.length;
+    const total = typeof totalValue === "number" ? totalValue : rows.length;
+    const noun = total === 1 ? presentation.item : presentation.items;
+    const summary = rows.length === total
+        ? `${total} ${noun}`
+        : `${rows.length} of ${total} ${noun}`;
+    const truncated = presentation.truncated && readPath(value, presentation.truncated) === true
+        ? " · more available"
+        : "";
+    return `${table}\n${summary}${truncated}`;
+}

package/dist/program-installation.js

@@ -12,10 +12,10 @@ export default async function installProgram(program, options = {}) {
     try {
         if (program instanceof Project) {
             await program.build();
-            installed = await system.forceCreateProgram(program.productionDefinition());
+            installed = await system.program.forceCreate(program.productionDefinition());
         }
         else
-            installed = await system.forceCreateProgram(program);
+            installed = await system.program.forceCreate(program);
         for await (const chunk of installed.install())
             writeProgramCommandOutput(chunk);
         installationFinished = true;

package/dist/template/package.json

@@ -1,7 +1,7 @@
 {
     "name": "phresh",
     "private": true,
-    "version": "0.1.30",
+    "version": "0.1.31",
     "description": "The official PhreshOS starter Program.",
     "type": "module",
     "scripts": {
@@ -14,15 +14,15 @@
         "starter"
     ],
     "dependencies": {
-        "@phreshos/client": "^0.1.36",
-        "@phreshos/core": "^0.1.40",
-        "@phreshos/react": "^0.1.19",
-        "@phreshos/server": "^0.1.40",
+        "@phreshos/client": "^0.1.37",
+        "@phreshos/core": "^0.1.41",
+        "@phreshos/react": "^0.1.20",
+        "@phreshos/server": "^0.1.41",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.51",
+        "@phreshos/cli": "^0.1.53",
         "@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.30",
+    version: "0.1.31",
     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.30",
-    "sha256": "80d4648ce8a846633c11fdf7df455bd770fde47b99fda45c05c457e8551c0592",
+    "version": "0.1.31",
+    "sha256": "2e6fd21f0f7e3c95934edda1790579c7d5dadb0b381fa525ebb02f747b395520",
     "development": true
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.51",
+    "version": "0.1.53",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"
@@ -49,11 +49,13 @@
     "packageManager": "bun@1.3.14",
     "dependencies": {
         "@clack/prompts": "^1.7.0",
-        "@phreshos/core": "^0.1.40",
-        "@phreshos/node": "^0.1.15",
+    "@phreshos/core": "^0.1.42",
+    "@phreshos/node": "^0.1.17",
         "adm-zip": "^0.6.0",
+        "cli-table3": "^0.6.5",
         "commander": "^15.0.0",
-        "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+        "string-width": "^4.2.3"
     },
     "devDependencies": {
         "@types/adm-zip": "^0.5.8",