@phreshos/cli 0.1.36 → 0.1.37

package/dist/cli.js

@@ -9,7 +9,7 @@ import init from "./init.js";
 import pack from "./pack.js";
 import uninstall from "./uninstall.js";
 import systemCommands from "./system/command.js";
-import controlCommands from "./control-command.js";
+import controlCommands from "./control/command.js";
 import describeCommands from "./describe-command.js";
 import { commandContract } from "./command-contract.js";
 const metadata = createRequire(import.meta.url)("../package.json");

package/dist/control/command.js

@@ -0,0 +1,12 @@
+import endpointCommands from "./endpoint.js";
+import processCommands from "./process.js";
+import programCommands from "./program.js";
+import { connectSystem } from "./shared.js";
+import windowCommands from "./window.js";
+/** Expose the shared System handles as explicit CLI commands. */
+export default function controlCommands(program, connect = connectSystem) {
+    programCommands(program, connect);
+    processCommands(program, connect);
+    endpointCommands(program, connect);
+    windowCommands(program, connect);
+}

package/dist/control/endpoint.js

@@ -0,0 +1,82 @@
+import {} from "commander";
+import { commandContract } from "../command-contract.js";
+import { clientOverrideOptions, endpointOptions, outputOptions } from "./options.js";
+import { bounded, clientLaunch, connected, endpoint, endpointView, integer, output, payload, requireProcess, wait } from "./shared.js";
+export default function endpointCommands(root, connect) {
+    const endpoints = commandContract(root.command("endpoint")
+        .description("inspect, control, and communicate with Process Endpoints"));
+    outputOptions(endpointOptions(endpoints.command("inspect")
+        .description("read whether one Endpoint is declared and running")))
+        .action(async (options) => withEndpoint(connect, options, async (process, name) => {
+        output(await endpointView(process, name), options.compact);
+    }));
+    outputOptions(clientOverrideOptions(endpointOptions(endpoints.command("start")
+        .description("start a fresh Endpoint incarnation"))))
+        .action(async (options) => withEndpoint(connect, options, async (process, name) => {
+        const overrides = clientLaunch(options);
+        if (name === "server" && overrides !== undefined)
+            throw new Error("Client overrides require --endpoint client");
+        if (name === "client")
+            await process.client.start(typeof overrides === "object" ? overrides : undefined);
+        else
+            await process.server.start();
+        output(await endpointView(process, name), options.compact);
+    }));
+    outputOptions(endpointOptions(endpoints.command("stop")
+        .description("stop one Endpoint")))
+        .action(async (options) => withEndpoint(connect, options, async (process, name) => {
+        await endpoint(process, name).stop();
+        output(await endpointView(process, name), options.compact);
+    }));
+    outputOptions(endpointOptions(endpoints.command("waitReady")
+        .alias("wait-ready")
+        .description("wait until the Server Endpoint reports readiness")
+        .option("--timeout <milliseconds>", "maximum wait in milliseconds", integer)))
+        .action(async (options) => withEndpoint(connect, options, async (process, name) => {
+        if (name !== "server")
+            throw new Error("waitReady requires --endpoint server");
+        await process.server.waitReady(timeout(options.timeout));
+        output(await endpointView(process, "server"), options.compact);
+    }));
+    outputOptions(endpointOptions(endpoints.command("ask")
+        .description("ask a Server event and return its answer")
+        .requiredOption("--event <event>", "event name")
+        .option("--payload <json>", "arbitrary event payload as JSON")
+        .option("--timeout <milliseconds>", "maximum wait in milliseconds", integer)))
+        .action(async (options) => withEndpoint(connect, options, async (process, name) => {
+        if (name !== "server")
+            throw new Error("ask requires --endpoint server");
+        const value = payload(options.payload);
+        const answer = options.timeout === undefined
+            ? await process.server.ask(options.event, value)
+            : await process.server.timeout(timeout(options.timeout)).ask(options.event, value);
+        output(answer, options.compact);
+    }));
+    outputOptions(endpointOptions(endpoints.command("publish")
+        .description("publish one event without waiting for an answer")
+        .requiredOption("--event <event>", "event name")
+        .option("--payload <json>", "arbitrary event payload as JSON")))
+        .action(async (options) => withEndpoint(connect, options, async (process, name) => {
+        endpoint(process, name).publish(options.event, payload(options.payload));
+        output(await endpointView(process, name), options.compact);
+    }));
+    outputOptions(endpointOptions(endpoints.command("wait")
+        .description("wait for the next event emitted by one live Endpoint")
+        .requiredOption("--event <event>", "event name")
+        .option("--timeout <milliseconds>", "maximum wait in milliseconds", integer)))
+        .action(async (options) => withEndpoint(connect, options, async (process, name) => {
+        output({
+            scope: `endpoint:${process.identity}:${name}`,
+            event: options.event,
+            payload: await wait(endpoint(process, name), options.event, timeout(options.timeout))
+        }, options.compact);
+    }));
+}
+async function withEndpoint(connect, options, action) {
+    await connected(connect, async (system) => {
+        await action(await requireProcess(system, options.process, options.program), options.endpoint);
+    });
+}
+function timeout(value) {
+    return value === undefined ? undefined : bounded(value, "--timeout", 1);
+}

package/dist/control/options.js

@@ -0,0 +1,37 @@
+import { Option } from "commander";
+import { collect } from "./shared.js";
+export function outputOptions(command) {
+    return command.option("--compact", "write machine-readable JSON on one line");
+}
+export function processOptions(command) {
+    return command
+        .requiredOption("--process <identity>", "Process identity or Program-local name")
+        .option("--program <identity>", "owning Program identity when resolving a Process name");
+}
+export function endpointOptions(command) {
+    return processOptions(command)
+        .addOption(new Option("--endpoint <endpoint>", "Endpoint kind").choices(["server", "client"]).makeOptionMandatory());
+}
+export function clientOptions(command) {
+    return clientOverrideOptions(command)
+        .option("--client", "start the Client Endpoint")
+        .option("--no-client", "do not start the Client Endpoint");
+}
+export function clientOverrideOptions(command) {
+    return command
+        .option("--client-title <title>", "initial Window title")
+        .option("--client-width <value>", "initial Window width")
+        .option("--client-height <value>", "initial Window height")
+        .option("--client-x <value>", "initial Window horizontal position")
+        .option("--client-y <value>", "initial Window vertical position")
+        .addOption(new Option("--client-layer <layer>", "initial Window layer").choices(["window", "under", "over"]))
+        .option("--client-location <location>", "initial page beneath the Client location")
+        .option("--client-minimized", "open the Window minimized");
+}
+export function launchOptions(command) {
+    return clientOptions(command)
+        .option("--name <name>", "stable Program-local Process name")
+        .option("--server", "start the Server Endpoint")
+        .option("--no-server", "do not start the Server Endpoint")
+        .option("--option <name=value>", "immutable Process option; repeat for more values", collect, []);
+}

package/dist/control/process.js

@@ -0,0 +1,94 @@
+import { Option } from "commander";
+import { commandContract } from "../command-contract.js";
+import { launchOptions, outputOptions, processOptions } from "./options.js";
+import { bounded, connected, integer, launch, output, page, processView, requireProcess, requireProgram, wait } from "./shared.js";
+export default function processCommands(root, connect) {
+    const process = commandContract(root.command("process")
+        .description("discover and control live Program executions"));
+    outputOptions(process.command("list")
+        .description("list live Processes with bounded filtering")
+        .option("--program <identity>", "restrict results to one Program")
+        .option("--search <text>", "case-insensitive identity or name search")
+        .option("--limit <count>", "maximum returned Processes", integer, 30)
+        .option("--offset <count>", "number of matching Processes to skip", integer, 0))
+        .action(async (options) => connected(connect, async (system) => {
+        const processes = options.program
+            ? await (await requireProgram(system, options.program)).process.list()
+            : await system.process.list();
+        const selected = page(processes, options.search, bounded(options.offset, "--offset", 0), bounded(options.limit, "--limit", 1, 100), value => `${value.identity}\n${value.name ?? ""}`);
+        output({ ...selected, data: await Promise.all(selected.data.map(processView)) }, options.compact);
+    }));
+    outputOptions(processOptions(process.command("inspect")
+        .description("read one live Process and its Endpoint state")))
+        .action(async (options) => connected(connect, async (system) => {
+        output(await processView(await requireProcess(system, options.process, options.program)), options.compact);
+    }));
+    outputOptions(launchOptions(process.command("create")
+        .description("create a Process")
+        .requiredOption("--program <identity>", "owning Program identity")))
+        .action(async (options) => connected(connect, async (system) => {
+        const program = await requireProgram(system, options.program);
+        output(await processView(await program.process.create(launch(options))), options.compact);
+    }));
+    outputOptions(launchOptions(process.command("findOrCreate")
+        .alias("find-or-create")
+        .description("find the named Process or create it atomically")
+        .requiredOption("--program <identity>", "owning Program identity")))
+        .action(async (options) => connected(connect, async (system) => {
+        const program = await requireProgram(system, options.program);
+        output(await processView(await program.process.findOrCreate(launch(options, true))), options.compact);
+    }));
+    outputOptions(processOptions(process.command("exit")
+        .description("exit one Process and all of its live Endpoints")))
+        .action(async (options) => connected(connect, async (system) => {
+        const process = await requireProcess(system, options.process, options.program);
+        const snapshot = await processView(process);
+        await process.exit();
+        output(snapshot, options.compact);
+    }));
+    outputOptions(process.command("wait")
+        .description("wait for one Process lifecycle event")
+        .addOption(new Option("--event <event>", "Process lifecycle event")
+        .choices(["endpointStart", "endpointStop", "create", "exit"])
+        .makeOptionMandatory())
+        .option("--process <identity>", "scope the event to one Process")
+        .option("--program <identity>", "scope the event to one Program")
+        .option("--timeout <milliseconds>", "maximum wait in milliseconds", integer))
+        .action(async (options) => connected(connect, async (system) => {
+        if (options.process && options.event === "create")
+            throw new Error("An individual Process does not emit create");
+        const target = options.process
+            ? await requireProcess(system, options.process, options.program)
+            : options.program
+                ? (await requireProgram(system, options.program)).process
+                : system.process;
+        const message = await wait(target, options.event, options.timeout === undefined
+            ? undefined
+            : bounded(options.timeout, "--timeout", 1));
+        output({
+            scope: options.process ? `process:${options.process}` : options.program ? `program:${options.program}` : "process",
+            event: options.event,
+            payload: await eventView(options.event, message, options.process ? target : undefined)
+        }, options.compact);
+    }));
+}
+async function eventView(event, message, scoped) {
+    if (event === "create")
+        return processView(message);
+    if (event === "endpointStart" || event === "endpointStop") {
+        const endpoint = message;
+        const process = await endpoint.process();
+        return {
+            process: process.identity,
+            endpoint: endpoint === process.server ? "server" : "client"
+        };
+    }
+    const exit = message;
+    const process = exit.process ?? scoped;
+    return {
+        ...(process ? { process: await processView(process) } : {}),
+        status: exit.status,
+        code: exit.code,
+        signal: exit.signal
+    };
+}

package/dist/control/program.js

@@ -0,0 +1,64 @@
+import { Option } from "commander";
+import { commandContract } from "../command-contract.js";
+import { outputOptions } from "./options.js";
+import { bounded, connected, integer, output, page, programView, requireProgram, wait } from "./shared.js";
+export default function programCommands(root, connect) {
+    const program = commandContract(root.command("program")
+        .description("discover PhreshOS Programs and their agent documentation"));
+    outputOptions(program.command("list")
+        .description("list Programs with bounded filtering")
+        .option("--installed-only", "return only installed Programs")
+        .option("--search <text>", "case-insensitive identity, name, or description search")
+        .option("--limit <count>", "maximum returned Programs", integer, 30)
+        .option("--offset <count>", "number of matching Programs to skip", integer, 0))
+        .action(async (options) => connected(connect, async (system) => {
+        const programs = await system.program.list(options.installedOnly === true);
+        const selected = page(programs, options.search, bounded(options.offset, "--offset", 0), bounded(options.limit, "--limit", 1, 100), value => `${value.identity}\n${value.name}\n${value.description ?? ""}`);
+        output({ ...selected, data: await Promise.all(selected.data.map(programView)) }, options.compact);
+    }));
+    outputOptions(program.command("inspect")
+        .description("read one Program declaration and installed state")
+        .requiredOption("--program <identity>", "Program identity"))
+        .action(async (options) => connected(connect, async (system) => {
+        output(await programView(await requireProgram(system, options.program)), options.compact);
+    }));
+    outputOptions(program.command("agent")
+        .description("read a Program's own agent operating policy")
+        .requiredOption("--program <identity>", "Program identity"))
+        .action(async (options) => connected(connect, async (system) => {
+        const program = await requireProgram(system, options.program);
+        const content = await program.agent();
+        if (content === null)
+            throw new Error(`Program "${program.identity}" has no agent documentation`);
+        output({ program: program.identity, content }, options.compact);
+    }));
+    outputOptions(program.command("wait")
+        .description("wait for one Program registry event")
+        .addOption(new Option("--event <event>", "Program lifecycle event")
+        .choices(["create", "forget", "install", "uninstall"])
+        .makeOptionMandatory())
+        .option("--program <identity>", "scope forget or uninstall to one Program")
+        .option("--timeout <milliseconds>", "maximum wait in milliseconds", integer))
+        .action(async (options) => connected(connect, async (system) => {
+        if (options.program && options.event !== "forget" && options.event !== "uninstall") {
+            throw new Error("An individual Program emits only forget and uninstall");
+        }
+        const target = options.program ? await requireProgram(system, options.program) : system.program;
+        const message = await wait(target, options.event, timeout(options.timeout));
+        output({
+            scope: options.program ? `program:${options.program}` : "program",
+            event: options.event,
+            payload: await eventView(options.event, message)
+        }, options.compact);
+    }));
+}
+async function eventView(event, message) {
+    if (event === "uninstall") {
+        const value = message;
+        return { program: await programView(value.program), everythingRemoved: value.everythingRemoved };
+    }
+    return programView(message);
+}
+function timeout(value) {
+    return value === undefined ? undefined : bounded(value, "--timeout", 1);
+}

package/dist/control/shared.js

@@ -0,0 +1,181 @@
+import { System } from "@phreshos/node";
+export const connectSystem = () => System.connect();
+export async function connected(connect, action) {
+    const system = await connect();
+    try {
+        return await action(system);
+    }
+    finally {
+        await system.disconnect();
+    }
+}
+export async function requireProgram(system, identity) {
+    const program = await system.program.find(identity);
+    if (!program)
+        throw new Error(`Unknown Program "${identity}"`);
+    return program;
+}
+export async function requireProcess(system, identity, programIdentity) {
+    const process = programIdentity
+        ? await (await requireProgram(system, programIdentity)).process.find(identity)
+        : await system.process.find(identity);
+    if (!process)
+        throw new Error(`Unknown Process "${identity}"`);
+    return process;
+}
+export function endpoint(process, name) {
+    return name === "server" ? process.server : process.client;
+}
+export async function programView(program) {
+    return {
+        identity: program.identity,
+        name: program.name,
+        version: program.version,
+        description: program.description,
+        installed: await program.installed(),
+        hasAgent: program.hasAgent,
+        server: program.server,
+        client: program.client
+    };
+}
+export async function processView(process) {
+    const [server, client] = await Promise.all([process.server.exists(), process.client.exists()]);
+    return {
+        identity: process.identity,
+        name: process.name,
+        program: process.program().identity,
+        startedAt: process.startedAt.toISOString(),
+        server: { declared: process.program().server !== null, running: server },
+        client: { declared: process.program().client !== null, running: client }
+    };
+}
+export async function endpointView(process, name) {
+    const program = process.program();
+    return {
+        process: process.identity,
+        program: program.identity,
+        endpoint: name,
+        declared: name === "server" ? program.server !== null : program.client !== null,
+        running: await endpoint(process, name).exists()
+    };
+}
+export async function windowView(process) {
+    const window = process.client.window;
+    const [title, position, size, minimized, front, layer, location] = await Promise.all([
+        window.title(),
+        window.position(),
+        window.size(),
+        window.minimized(),
+        window.front(),
+        window.layer(),
+        window.location()
+    ]);
+    return { process: process.identity, title, position, size, minimized, front, layer, location };
+}
+export function output(value, compact) {
+    console.log(JSON.stringify(value ?? null, null, compact ? undefined : 2));
+}
+export function payload(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error("--payload must be valid JSON");
+    }
+}
+export function metric(value) {
+    const trimmed = value.trim();
+    return /^-?(?:\d+\.?\d*|\.\d+)$/.test(trimmed) ? Number(trimmed) : trimmed;
+}
+export function integer(value) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed))
+        throw new Error(`Expected an integer, received "${value}"`);
+    return parsed;
+}
+export function bounded(value, name, minimum, maximum) {
+    if (value < minimum || (maximum !== undefined && value > maximum)) {
+        throw new Error(`${name} must be between ${minimum} and ${maximum ?? "Infinity"}`);
+    }
+    return value;
+}
+export function position(x, y) {
+    return { x: metric(x), y: metric(y) };
+}
+export function size(width, height) {
+    return { width: metric(width), height: metric(height) };
+}
+export function page(values, search, offset = 0, limit = 30, text) {
+    const query = search?.trim().toLocaleLowerCase();
+    const matches = query ? values.filter(value => text(value).toLocaleLowerCase().includes(query)) : [...values];
+    return {
+        data: matches.slice(offset, offset + limit),
+        total: matches.length,
+        truncated: offset + limit < matches.length
+    };
+}
+export function launch(options, named = false) {
+    const client = clientLaunch(options);
+    const values = entries(options.option);
+    const result = {};
+    if (options.name !== undefined)
+        result.name = options.name;
+    if (options.server !== undefined)
+        result.server = options.server;
+    if (client !== undefined)
+        result.client = client;
+    if (Object.keys(values).length)
+        result.options = values;
+    if (named && !result.name)
+        throw new Error("--name is required");
+    return result;
+}
+export function clientLaunch(options) {
+    const configured = options.clientTitle !== undefined
+        || options.clientWidth !== undefined
+        || options.clientHeight !== undefined
+        || options.clientX !== undefined
+        || options.clientY !== undefined
+        || options.clientLayer !== undefined
+        || options.clientLocation !== undefined
+        || options.clientMinimized === true;
+    if (!configured)
+        return options.client;
+    if (options.client === false)
+        throw new Error("Client overrides cannot be combined with --no-client");
+    if ((options.clientWidth === undefined) !== (options.clientHeight === undefined)) {
+        throw new Error("--client-width and --client-height must be supplied together");
+    }
+    if ((options.clientX === undefined) !== (options.clientY === undefined)) {
+        throw new Error("--client-x and --client-y must be supplied together");
+    }
+    return {
+        ...(options.clientTitle === undefined ? {} : { title: options.clientTitle }),
+        ...(options.clientWidth === undefined ? {} : { size: size(options.clientWidth, options.clientHeight) }),
+        ...(options.clientX === undefined ? {} : { position: position(options.clientX, options.clientY) }),
+        ...(options.clientLayer === undefined ? {} : { layer: options.clientLayer }),
+        ...(options.clientLocation === undefined ? {} : { location: options.clientLocation }),
+        ...(options.clientMinimized === true ? { minimize: true } : {})
+    };
+}
+export function collect(value, previous = []) {
+    return [...previous, value];
+}
+function entries(values = []) {
+    const result = {};
+    for (const value of values) {
+        const boundary = value.indexOf("=");
+        if (boundary < 1)
+            throw new Error("--option must use name=value");
+        result[value.slice(0, boundary)] = value.slice(boundary + 1);
+    }
+    return result;
+}
+export async function wait(target, event, timeout) {
+    return target.waitFor(event, timeout);
+}
+export function windowOf(process) {
+    return process.client.window;
+}

package/dist/control/window.js

@@ -0,0 +1,84 @@
+import { Option } from "commander";
+import { commandContract } from "../command-contract.js";
+import { outputOptions, processOptions } from "./options.js";
+import { bounded, connected, integer, output, position, requireProcess, size, wait, windowOf, windowView } from "./shared.js";
+export default function windowCommands(root, connect) {
+    const windows = commandContract(root.command("window")
+        .description("inspect and control authoritative Client Windows"));
+    outputOptions(processOptions(windows.command("inspect")
+        .description("read the complete current Window state")))
+        .action(async (options) => withWindow(connect, options, async (process) => {
+        output(await windowView(process), options.compact);
+    }));
+    outputOptions(processOptions(windows.command("move")
+        .description("change Window position")
+        .requiredOption("--x <value>", "horizontal pixels or workspace-relative expression")
+        .requiredOption("--y <value>", "vertical pixels or workspace-relative expression")))
+        .action(async (options) => withWindow(connect, options, async (process) => {
+        await windowOf(process).move(position(options.x, options.y));
+        output(await windowView(process), options.compact);
+    }));
+    outputOptions(processOptions(windows.command("resize")
+        .description("change Window size")
+        .requiredOption("--width <value>", "width in pixels or a workspace-relative expression")
+        .requiredOption("--height <value>", "height in pixels or a workspace-relative expression")))
+        .action(async (options) => withWindow(connect, options, async (process) => {
+        await windowOf(process).resize(size(options.width, options.height));
+        output(await windowView(process), options.compact);
+    }));
+    outputOptions(processOptions(windows.command("setGeometry")
+        .alias("set-geometry")
+        .description("change Window position and size atomically")
+        .requiredOption("--x <value>", "horizontal pixels or workspace-relative expression")
+        .requiredOption("--y <value>", "vertical pixels or workspace-relative expression")
+        .requiredOption("--width <value>", "width in pixels or a workspace-relative expression")
+        .requiredOption("--height <value>", "height in pixels or a workspace-relative expression")))
+        .action(async (options) => withWindow(connect, options, async (process) => {
+        await windowOf(process).setGeometry({
+            position: position(options.x, options.y),
+            size: size(options.width, options.height)
+        });
+        output(await windowView(process), options.compact);
+    }));
+    outputOptions(processOptions(windows.command("minimize")
+        .description("set Window visibility without changing its order")
+        .option("--restore", "restore rather than minimize the Window")))
+        .action(async (options) => withWindow(connect, options, async (process) => {
+        await windowOf(process).minimize(options.restore !== true);
+        output(await windowView(process), options.compact);
+    }));
+    outputOptions(processOptions(windows.command("changeTitle")
+        .alias("change-title")
+        .description("change the human-readable Window title")
+        .requiredOption("--title <title>", "new Window title")))
+        .action(async (options) => withWindow(connect, options, async (process) => {
+        await windowOf(process).changeTitle(options.title);
+        output(await windowView(process), options.compact);
+    }));
+    outputOptions(processOptions(windows.command("raise")
+        .description("raise the Window within its own layer")))
+        .action(async (options) => withWindow(connect, options, async (process) => {
+        await windowOf(process).raise();
+        output(await windowView(process), options.compact);
+    }));
+    outputOptions(processOptions(windows.command("wait")
+        .description("wait for one authoritative Window change")
+        .addOption(new Option("--event <event>", "Window event")
+        .choices(["move", "resize", "geometry", "minimize", "changeTitle", "front"])
+        .makeOptionMandatory())
+        .option("--timeout <milliseconds>", "maximum wait in milliseconds", integer)))
+        .action(async (options) => withWindow(connect, options, async (process) => {
+        output({
+            scope: `window:${process.identity}`,
+            event: options.event,
+            payload: await wait(windowOf(process), options.event, options.timeout === undefined
+                ? undefined
+                : bounded(options.timeout, "--timeout", 1))
+        }, options.compact);
+    }));
+}
+async function withWindow(connect, options, action) {
+    await connected(connect, async (system) => {
+        await action(await requireProcess(system, options.process, options.program));
+    });
+}

package/dist/describe-command.js

@@ -1,4 +1,3 @@
-import { systemControl, systemControlOperation } from "@phreshos/core";
 import { commandContract, readCommandContract } from "./command-contract.js";
 /** Add one machine-readable description entry point for the complete CLI tree. */
 export default function describeCommands(program) {
@@ -24,10 +23,6 @@ function resolveCommand(root, path) {
 }
 function describe(command, path) {
     const registered = readCommandContract(command);
-    const capability = registered?.capability ?? (path.length === 1 && Object.hasOwn(systemControl, path[0] ?? "")
-        ? systemControl[path[0]]
-        : null);
-    const operation = path.length === 2 ? systemControlOperation(path[0] ?? "", path[1] ?? "") : null;
     return {
         path,
         name: command.name(),
@@ -35,8 +30,7 @@ function describe(command, path) {
         arguments: command.registeredArguments.map(argumentDescription),
         options: command.options.map(optionDescription),
         commands: command.commands.map(child => ({ name: child.name(), description: child.description() })),
-        ...(registered?.guidance ? { guidance: registered.guidance } : {}),
-        ...(operation ? { capability: operation } : capability ? { capability } : {})
+        ...(registered?.guidance ? { guidance: registered.guidance } : {})
     };
 }
 function argumentDescription(argument) {

package/dist/template/package.json

@@ -1,7 +1,7 @@
 {
     "name": "phresh",
     "private": true,
-    "version": "0.1.19",
+    "version": "0.1.20",
     "description": "The official PhreshOS starter Program.",
     "type": "module",
     "scripts": {
@@ -14,15 +14,15 @@
         "starter"
     ],
     "dependencies": {
-        "@phreshos/client": "^0.1.23",
-        "@phreshos/core": "^0.1.22",
-        "@phreshos/react": "^0.1.11",
-        "@phreshos/server": "^0.1.23",
+        "@phreshos/client": "^0.1.24",
+        "@phreshos/core": "^0.1.25",
+        "@phreshos/react": "^0.1.12",
+        "@phreshos/server": "^0.1.25",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.36",
+        "@phreshos/cli": "^0.1.37",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/dist/template/phresh.config.ts

@@ -4,7 +4,7 @@ export default defineConfig({
     identity: "phresh",
     name: "Phresh Program",
     description: "A minimal counter with direct Client and Server endpoints.",
-    version: "0.1.19",
+    version: "0.1.20",
     icon: "icon.png",
     categories: ["Development"],
     keywords: ["example", "counter", "client", "server"],

package/dist/template/source/client/index.html

@@ -4,6 +4,7 @@
 <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
     <title>Phresh Program</title>
     <script type="module" src="./main.tsx"></script>
 </head>

package/dist/template.json

@@ -1,6 +1,6 @@
 {
     "repository": "PhreshOS/phresh-program",
-    "version": "0.1.19",
-    "sha256": "e12f0c026b7b6f3e5f77a206442e5dcb6242021902d8f5a51c9886c7d75b0e24",
+    "version": "0.1.20",
+    "sha256": "645172d788eade71536ac9f9e31426eef7286d159846fb91382bcb49193b4f5e",
     "development": true
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.36",
+    "version": "0.1.37",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"
@@ -49,8 +49,8 @@
     "packageManager": "bun@1.3.14",
     "dependencies": {
         "@clack/prompts": "^1.7.0",
-        "@phreshos/core": "^0.1.23",
-        "@phreshos/node": "^0.1.2",
+        "@phreshos/core": "^0.1.25",
+        "@phreshos/node": "^0.1.4",
         "adm-zip": "^0.6.0",
         "commander": "^15.0.0",
         "jiti": "^2.7.0",

package/dist/control-client.js

@@ -1,44 +0,0 @@
-import { gatewayAddress, resolveHome } from "@phreshos/node";
-import { connect } from "node:net";
-/** Owner-local client for the authoritative running-System contract. */
-export default class LocalSystemControl {
-    async execute(request, signal) {
-        const address = gatewayAddress(resolveHome());
-        return await new Promise((resolve, reject) => {
-            const socket = connect(address);
-            let buffer = "";
-            let settled = false;
-            const finish = (work) => {
-                if (settled)
-                    return;
-                settled = true;
-                signal?.removeEventListener("abort", cancel);
-                socket.destroy();
-                work();
-            };
-            const cancel = () => finish(() => reject(signal?.reason instanceof Error ? signal.reason : new Error("The request was cancelled")));
-            signal?.addEventListener("abort", cancel, { once: true });
-            socket.on("connect", () => socket.write(`${JSON.stringify({ target: "system", request })}\n`));
-            socket.on("data", chunk => {
-                buffer += String(chunk);
-                const boundary = buffer.indexOf("\n");
-                if (boundary < 0)
-                    return;
-                try {
-                    const outcome = JSON.parse(buffer.slice(0, boundary));
-                    if (outcome.success)
-                        finish(() => resolve(outcome.result));
-                    else
-                        finish(() => reject(new Error(outcome.error)));
-                }
-                catch {
-                    finish(() => reject(new Error("The System returned an invalid response")));
-                }
-            });
-            socket.on("error", () => finish(() => reject(new Error(`No System is listening at ${address} — start PhreshOS first`))));
-            socket.on("close", () => finish(() => reject(new Error("The System closed the request without an answer"))));
-            if (signal?.aborted)
-                cancel();
-        });
-    }
-}

package/dist/control-command.js

@@ -1,50 +0,0 @@
-import { systemControl, systemControlOperation } from "@phreshos/core";
-import LocalSystemControl from "./control-client.js";
-import { commandContract } from "./command-contract.js";
-/** Build the top-level running-System commands from Core's authoritative catalog. */
-export default function controlCommands(program, provided) {
-    let client = provided;
-    const current = () => client ?? (client = new LocalSystemControl());
-    for (const [capabilityName, capability] of Object.entries(systemControl)) {
-        const group = commandContract(program.command(capabilityName)
-            .description(capability.description)
-            .addHelpText("after", `\nOperating guidance:\n${capability.guidance.map(item => `  - ${item}`).join("\n")}\n`), {
-            guidance: capability.guidance,
-            capability
-        });
-        for (const [operationName, operation] of Object.entries(capability.operations)) {
-            commandContract(group.command(operationName)
-                .description(operation.description)
-                .option("--input <json>", "operation input as one JSON object", "{}")
-                .option("--compact", "write machine-readable JSON on one line")
-                .addHelpText("after", operationHelp(capabilityName, operationName))
-                .action(async function (options) {
-                const input = parseInput(options.input);
-                const result = await current().execute({
-                    capability: capabilityName,
-                    operation: operationName,
-                    input
-                });
-                console.log(JSON.stringify(result ?? null, null, options.compact ? undefined : 2));
-            }), { capability: operation });
-        }
-    }
-}
-function operationHelp(capability, operation) {
-    const definition = systemControlOperation(capability, operation);
-    if (!definition)
-        return "";
-    return `\nInput schema:\n${JSON.stringify(definition.input, null, 2)}\n\nExamples:\n${definition.examples.map(example => `  phresh ${capability} ${operation} --input '${JSON.stringify(example)}'`).join("\n")}\n`;
-}
-function parseInput(value) {
-    let parsed;
-    try {
-        parsed = JSON.parse(value);
-    }
-    catch {
-        throw new Error("--input must be valid JSON");
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-        throw new Error("--input must be one JSON object");
-    return parsed;
-}