@phreshos/cli 0.1.48 → 0.1.49

package/dist/commands/observation.js

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

package/dist/commands/options.js

@@ -0,0 +1,52 @@
+import { collect, integer } from "./input.js";
+export const jsonOption = option("--json", "write the result as machine-readable JSON on one line");
+export const processOptions = Object.freeze([
+    option("--process <identity>", "Process identity or Program-local name", { mandatory: true }),
+    option("--program <identity>", "owning Program identity when resolving a Process name")
+]);
+export const endpointOptions = Object.freeze([
+    ...processOptions,
+    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-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"),
+    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 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()")
+]);
+export const launchOptions = Object.freeze([
+    ...serverOverrideOptions,
+    option("--client", "start the Client Endpoint"),
+    option("--no-client", "do not start the Client Endpoint"),
+    ...clientOverrideOptions,
+    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", {
+        default: [],
+        repeatable: true,
+        parse: (value, previous) => collect(value, Array.isArray(previous) ? previous : [])
+    })
+]);
+export const namedLaunchOptions = Object.freeze(launchOptions.map(current => current.flags === "--name <name>"
+    ? Object.freeze({ ...current, mandatory: true })
+    : current));
+export const timeoutOption = option("--timeout <milliseconds>", "maximum wait in milliseconds", {
+    parse: value => integer(value)
+});
+export function withJson(...options) {
+    return Object.freeze([...options, jsonOption]);
+}
+export function option(flags, description, values = {}) {
+    return Object.freeze({ flags, description, ...values });
+}

package/dist/commands/process.js

@@ -0,0 +1,111 @@
+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 { connected, requireProcess, requireProgram } from "./connection.js";
+import { bounded, integer, launch, page } from "./input.js";
+import { wait } from "./observation.js";
+import { processView } from "./projection.js";
+export default function processCommands(root, connect) {
+    const processes = defineCommand(root, {
+        name: "process",
+        description: "discover and control live Program executions",
+        guidance: ["A Process is one execution of a Program and owns its Server and Client Endpoints."]
+    });
+    defineCommand(processes, {
+        name: "list",
+        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"),
+        examples: ["phresh process list", "phresh process list --program terminal --json"]
+    }, 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), current => `${current.identity}\n${current.name ?? ""}`);
+        return { ...selected, data: await Promise.all(selected.data.map(processView)) };
+    }));
+    defineCommand(processes, {
+        name: "inspect",
+        description: "read one live Process and its Endpoint state",
+        requiresSystem: true,
+        options: withJson(...processOptions),
+        output: jsonOutput(processOutput, "The selected Process"),
+        examples: ["phresh process inspect --process main --program terminal"]
+    }, async ({ options }) => connected(connect, async (system) => {
+        return await processView(await requireProcess(system, options.process, options.program));
+    }));
+    defineCommand(processes, {
+        name: "create",
+        description: "create a Process",
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "owning Program identity", { mandatory: true }), ...launchOptions),
+        output: jsonOutput(processOutput, "The created Process"),
+        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);
+        return await processView(await program.process.create(launch(options)));
+    }));
+    defineCommand(processes, {
+        name: "findOrCreate",
+        aliases: ["find-or-create"],
+        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"),
+        examples: ["phresh process find-or-create --program terminal --name main --json"]
+    }, async ({ options }) => connected(connect, async (system) => {
+        const program = await requireProgram(system, options.program);
+        return await processView(await program.process.findOrCreate(launch(options, true)));
+    }));
+    defineCommand(processes, {
+        name: "exit",
+        description: "exit one Process and all of its live Endpoints",
+        requiresSystem: true,
+        options: withJson(...processOptions),
+        output: jsonOutput(processOutput, "The Process state immediately before exit"),
+        examples: ["phresh process exit --process main --program terminal"]
+    }, async ({ options }) => connected(connect, async (system) => {
+        const process = await requireProcess(system, options.process, options.program);
+        const snapshot = await processView(process);
+        await process.exit();
+        return snapshot;
+    }));
+    defineCommand(processes, {
+        name: "wait",
+        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"),
+        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")
+            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));
+        return {
+            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)
+        };
+    }));
+}
+async function eventView(event, message, scoped) {
+    if (event === "create")
+        return processView(message);
+    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/commands/program.js

@@ -0,0 +1,90 @@
+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 { connected, requireProgram } from "./connection.js";
+import { bounded, integer, page } from "./input.js";
+import { wait } from "./observation.js";
+import { programView } from "./projection.js";
+export default function programCommands(root, connect) {
+    const programs = defineCommand(root, {
+        name: "program",
+        description: "discover PhreshOS Programs and their agent documentation",
+        guidance: ["A Program is the stable installed or retained definition that owns Processes."]
+    });
+    defineCommand(programs, {
+        name: "list",
+        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"),
+        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);
+        const selected = page(programs, options.search, bounded(options.offset, "--offset", 0), bounded(options.limit, "--limit", 1, 100), current => `${current.identity}\n${current.name}\n${current.description ?? ""}`);
+        return { ...selected, data: await Promise.all(selected.data.map(programView)) };
+    }));
+    defineCommand(programs, {
+        name: "inspect",
+        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"),
+        examples: ["phresh program inspect --program terminal"]
+    }, async ({ options }) => connected(connect, async (system) => {
+        return await programView(await requireProgram(system, options.program));
+    }));
+    defineCommand(programs, {
+        name: "agent",
+        description: "read a Program's own agent operating policy",
+        requiresSystem: true,
+        options: withJson(option("--program <identity>", "Program identity", { mandatory: true })),
+        output: jsonOutput(value.object({
+            program: value.string("Program identity"),
+            content: value.string("Program-owned agent documentation")
+        }, ["program", "content"], "Program agent documentation"), "The Program's agent documentation"),
+        examples: ["phresh program agent --program terminal --json"]
+    }, 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`);
+        return { program: program.identity, content };
+    }));
+    defineCommand(programs, {
+        name: "wait",
+        description: "wait for one Program registry event",
+        requiresSystem: true,
+        options: withJson(option("--event <event>", "Program lifecycle event", {
+            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"),
+        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") {
+            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));
+        return {
+            scope: options.program ? `program:${options.program}` : "program",
+            event: options.event,
+            payload: await eventView(options.event, message, options.program ? target : undefined)
+        };
+    }));
+}
+async function eventView(event, message, scoped) {
+    if (event === "uninstall") {
+        if (scoped)
+            return { program: await programView(scoped), everything: message === true };
+        const current = message;
+        return { program: await programView(current.program), everything: current.everything };
+    }
+    if (scoped)
+        return programView(scoped);
+    return programView(message);
+}
+function timeout(value) {
+    return value === undefined ? undefined : bounded(value, "--timeout", 1);
+}

package/dist/commands/project.js

@@ -0,0 +1,152 @@
+import { defineCommand } from "../contract/command.js";
+import create from "../create.js";
+import init from "../init.js";
+import install from "../install.js";
+import launch from "../launch.js";
+import pack from "../pack.js";
+import uninstall from "../uninstall.js";
+import { option } from "./options.js";
+import { textOutput } from "./schemas.js";
+const runOptionPrefix = "--run-option-";
+/** Register commands whose subject is a Program project or release. */
+export default function projectCommands(program, coreRange) {
+    defineCommand(program, {
+        name: "create",
+        description: "create a new Program project",
+        arguments: [{ syntax: "[directory]", description: "directory for the new Program" }],
+        options: [
+            option("--name <name>", "human-readable Program name"),
+            option("--package-manager <manager>", "package manager used to install dependencies", { choices: ["bun", "npm", "pnpm", "yarn"] }),
+            option("--no-install", "create files without installing dependencies")
+        ],
+        guidance: [
+            "Creates a complete Server and Client project from the maintained Phresh Program template bundled with this CLI.",
+            "In a terminal, omitted values are collected interactively. Automation supplies the directory and optional choices through named options."
+        ],
+        examples: ["phresh create", "phresh create my-program --package-manager bun"],
+        output: textOutput("Created Program project and installation status")
+    }, async ({ arguments: [directory], options }) => {
+        await create({ directory, name: options.name, packageManager: options.packageManager, install: options.install });
+    });
+    defineCommand(program, {
+        name: "init",
+        description: "initialize an existing Program project",
+        options: [
+            option("--name <name>", "human-readable Program name"),
+            option("--build-command <command>", "prepare production files before use"),
+            option("--server", "include a Server endpoint"),
+            option("--server-location <path>", "production Server directory"),
+            option("--server-start-command <command>", "production Server command"),
+            option("--server-entry-file <path>", "production Server worker entry"),
+            option("--server-development-start-command <command>", "development Server command"),
+            option("--server-development-entry-file <path>", "development Server worker entry"),
+            option("--client", "include a Client endpoint"),
+            option("--client-location <path>", "production Client directory"),
+            option("--client-development-url <url>", "fixed or external development Client URL"),
+            option("--client-development-start-command <command>", "development Client command"),
+            option("--force", "replace an existing phresh.config.ts")
+        ],
+        guidance: [
+            "Reads identity, version, and description from package.json, then writes phresh.config.ts.",
+            "A terminal asks only for values the project cannot provide. Without a terminal, declare at least one endpoint with options."
+        ],
+        examples: ["phresh init --server --client", "phresh init --client --client-location dist/client"],
+        output: textOutput("Initialized Program configuration")
+    }, async ({ options }) => {
+        await init({
+            name: options.name,
+            buildCommand: options.buildCommand,
+            server: options.server === true || options.serverLocation !== undefined || options.serverStartCommand !== undefined || options.serverEntryFile !== undefined,
+            serverLocation: options.serverLocation,
+            serverStartCommand: options.serverStartCommand,
+            serverEntryFile: options.serverEntryFile,
+            serverDevelopmentStartCommand: options.serverDevelopmentStartCommand,
+            serverDevelopmentEntryFile: options.serverDevelopmentEntryFile,
+            client: options.client === true
+                || options.clientLocation !== undefined
+                || options.clientDevelopmentUrl !== undefined
+                || options.clientDevelopmentStartCommand !== undefined,
+            clientLocation: options.clientLocation,
+            clientDevelopmentUrl: options.clientDevelopmentUrl,
+            clientDevelopmentStartCommand: options.clientDevelopmentStartCommand,
+            force: options.force === true
+        }, process.cwd(), coreRange);
+    });
+    defineCommand(program, {
+        name: "pack",
+        description: "build and package this Program",
+        guidance: ["Runs an optional buildCommand, then packages the production files declared for each endpoint."],
+        examples: ["phresh pack"],
+        output: textOutput("Packaged Program release")
+    }, async function () {
+        await pack();
+    });
+    defineCommand(program, {
+        name: "install",
+        description: "install a local or official Program",
+        arguments: [{ syntax: "[name]", description: "name of an official Program" }],
+        options: [option("--run", "run the installed Program now")],
+        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."
+        ],
+        requiresSystem: true,
+        examples: ["phresh install", "phresh install terminal --run"],
+        output: textOutput("Installed Program and optional Process identity")
+    }, async ({ arguments: [name], options }) => {
+        await install({ name, run: options.run === true });
+    });
+    defineCommand(program, {
+        name: "uninstall",
+        description: "uninstall a local or installed Program",
+        arguments: [{ syntax: "[name]", description: "name of an installed Program" }],
+        options: [option("--everything", "also remove Processes, data, and runtime state")],
+        guidance: [
+            "Without a name, uses the Program declared by this project.",
+            "Removes installed files while preserving Processes, data, and runtime Program state unless --everything is supplied."
+        ],
+        requiresSystem: true,
+        examples: ["phresh uninstall", "phresh uninstall terminal --everything"],
+        output: textOutput("Uninstalled Program state")
+    }, async ({ arguments: [name], options }) => {
+        await uninstall({ name, everything: options.everything === true });
+    });
+    attached(program, "start", "run the production Program without installing", [
+        "Runs this Program attached to the terminal. Output arrives here, and ending this command stops the Program.",
+        "An optional buildCommand runs before launch, and the Program's exit status becomes this command's status."
+    ], "production");
+    attached(program, "dev", "run the development Program without installing", [
+        "Runs the same attached lifecycle as start using the development declarations.",
+        "A Client URL must respond within 15 seconds before launch."
+    ], "development");
+}
+function attached(program, name, description, guidance, mode) {
+    defineCommand(program, {
+        name,
+        description,
+        arguments: [{ syntax: "[run-options...]", description: "--run-option-<name>=<value> values passed to the Program" }],
+        allowUnknownOptions: true,
+        requiresSystem: true,
+        guidance,
+        examples: [`phresh ${name}`, `phresh ${name} --run-option-example=value`],
+        output: textOutput("Attached Process lifecycle and output")
+    }, async ({ arguments: [arguments_] }) => {
+        await launch(mode, process.cwd(), runOptions(name, arguments_));
+    });
+}
+function runOptions(command, arguments_) {
+    const options = {};
+    for (const argument of arguments_) {
+        if (!argument.startsWith(runOptionPrefix))
+            throw new Error(`${command} accepts Program options only as ${runOptionPrefix}<name>=<value>; received "${argument}"`);
+        const said = argument.slice(runOptionPrefix.length);
+        const at = said.indexOf("=");
+        if (at < 1)
+            throw new Error(`"${argument}" says no value — write ${runOptionPrefix}<name>=<value>, and end with = for an empty value`);
+        const name = said.slice(0, at);
+        if (Object.hasOwn(options, name))
+            throw new Error(`The run option "${name}" was given more than once`);
+        options[name] = said.slice(at + 1);
+    }
+    return options;
+}

package/dist/commands/projection.js

@@ -0,0 +1,59 @@
+export function endpoint(process, name) {
+    return name === "server" ? process.server : process.client;
+}
+export function windowOf(process) {
+    return process.client.window;
+}
+export async function programView(program) {
+    return {
+        identity: program.identity,
+        assetId: program.assetId,
+        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, serverService, clientService] = await Promise.all([
+        process.server.exists(),
+        process.client.exists(),
+        process.server.isService(),
+        process.client.isService()
+    ]);
+    return {
+        identity: process.identity,
+        name: process.name,
+        program: process.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 }
+    };
+}
+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(),
+        service: await endpoint(process, name).isService()
+    };
+}
+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 };
+}

package/dist/commands/schemas.js

@@ -0,0 +1,89 @@
+import { value } from "../contract/schema.js";
+const metric = {
+    anyOf: [value.number("pixels"), value.string("workspace-relative expression")]
+};
+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 clientDeclaration = value.nullable(value.object({
+    start: value.boolean("whether a default Process starts this Endpoint"),
+    service: value.boolean("default Service role for new incarnations"),
+    title: value.nullable(value.string("default Window title")),
+    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(["window", "under", "over"], "default Window layer")),
+    minimize: value.nullable(value.boolean("default minimized state")),
+    permissions
+}, ["start", "service", "title", "size", "position", "layer", "minimize", "permissions"], "resolved Client Endpoint declaration"));
+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")),
+    description: value.nullable(value.string("Program description")),
+    installed: value.boolean("whether production files are installed"),
+    hasAgent: value.boolean("whether the Program provides agent documentation"),
+    server: endpointDeclaration,
+    client: clientDeclaration
+}, ["identity", "assetId", "name", "version", "description", "installed", "hasAgent", "server", "client"], "Program state");
+export const processOutput = value.object({
+    identity: value.string("unique Process identity"),
+    name: value.nullable(value.string("stable Program-local Process name")),
+    program: value.string("owning Program identity"),
+    startedAt: value.string("ISO start time"),
+    server: endpointState("Server Endpoint state"),
+    client: endpointState("Client Endpoint state")
+}, ["identity", "name", "program", "startedAt", "server", "client"], "Process state");
+export const endpointOutput = value.object({
+    process: value.string("owning Process identity"),
+    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")
+}, ["process", "program", "endpoint", "declared", "running", "service"], "Endpoint state");
+export const windowOutput = value.object({
+    process: value.string("owning Process identity"),
+    title: value.string("Window title"),
+    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"),
+    front: value.boolean("whether the Window is at the front of its layer"),
+    layer: value.enumeration(["window", "under", "over"], "Window layer"),
+    location: value.string("current Client location")
+}, ["process", "title", "position", "size", "minimized", "front", "layer", "location"], "Window state");
+export function pageOutput(items, description) {
+    return value.object({
+        data: value.array(items, description),
+        total: value.integer("total matching values"),
+        truncated: value.boolean("whether more matching values exist")
+    }, ["data", "total", "truncated"], description);
+}
+export function eventOutput(description, payload = value.any("event payload")) {
+    return value.object({
+        scope: value.string("subscription scope"),
+        event: value.string("event name"),
+        payload
+    }, ["scope", "event", "payload"], description);
+}
+export function jsonOutput(schema, description) {
+    return { format: "json", description, value: schema };
+}
+export function textOutput(description) {
+    return { format: "text", 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")
+    }, ["declared", "running", "service"], description);
+}