@phreshos/server 0.1.11 → 0.1.12

package/README.md

@@ -124,11 +124,9 @@ on `host`:
 const programs = await host.program.list()
 const program = await host.program.find("counter")
 const processes = await host.process.list()
-const serviceKeys = await host.service.list()
 
 const stopPrograms = host.program.subscribe("create", value => undefined)
 const stopProcesses = host.process.subscribe("exit", value => undefined)
-const stopServices = host.service.subscribe("enable", key => undefined)
 ```
 
 A Program owns its scoped Process capability:
@@ -137,12 +135,24 @@ A Program owns its scoped Process capability:
 const processes = await program.process.list()
 const process = await program.process.find("worker")
 const created = await program.process.create({ name: "worker" })
+const shared = await program.process.findOrCreate({
+  name: "shared-server",
+  server: true,
+  client: false
+})
 ```
 
-`host.service.prepare(key)` creates the exact opaque service handle. The
+`findOrCreate()` is atomic at the authoritative Core. Concurrent equivalent
+launches converge on one named Process; a different launch for that name
+rejects instead of reconfiguring the existing Process.
+
+`host.service(key)` creates the exact opaque service handle. The
 handler exposes its authored `name`, `enabled()`, `waitReady()`, lifecycle
 subscriptions, and channel; it does not expose its Program or Endpoint as
-separate fields.
+separate fields. Services are not a second public registry: inspect Programs
+and their Endpoint declarations. `program.server?.hasService()` identifies a
+declared Service capability, while `await program.server?.docs()` reads its
+installed policy and API documentation before the Endpoint starts.
 
 `program.icon()` requests a guaranteed PNG `Blob` in `small`, `medium`, or
 `large` form without exposing the Program's source path or the system's private

package/dist/channel.d.ts

@@ -1,9 +1,9 @@
-import type { Channel as CoreChannel, ChannelMessage, Cleanup, ServerServiceDefinition } from "@phreshos/core";
+import type { Channel as CoreChannel, ChannelMessage, Cleanup } from "@phreshos/core";
 import { type Endpoint } from "./domain.js";
 /** Handles one question addressed to the current Server. */
 export type Answerer<Payload = unknown, Result = undefined> = (message: ChannelMessage<Payload>) => Result | Promise<Result>;
 /** Events and questions explicitly accepted by the current Server. */
-export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint, ServerServiceDefinition> {
+export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint> {
     /** Registers one answerer; omitting its return produces `undefined`. */
     answer<Payload = unknown, Result = undefined>(event: string, answerer: Answerer<Payload, Result>): Cleanup;
 }

package/dist/channel.js

@@ -12,7 +12,7 @@ class ServerChannel extends Events {
     publish(event, payload = undefined) {
         wire.send("end-host", "emit", event, payload);
     }
-    async enableService(definition) { await enableCurrentService(definition); }
+    async enableService(name) { await enableCurrentService(name); }
     async disableService() { await disableCurrentService(); }
     answer(event, answerer) {
         return wire.answer("end-end", event, value => answerer(message(value)));

package/dist/domain.d.ts

@@ -1,4 +1,4 @@
-import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture, type AskCapture, type Cleanup, type ClientDeclaration, type EndpointDeclaration, type Exit, type Launch, type ProgramPermission, type ProgramProcess as CoreProgramProcess, type ProgramArea as CoreProgramArea, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture, type AskCapture, type Cleanup, type ClientDeclaration, type Exit, type Launch, type Position, type ProgramPermission, type ProgramProcess as CoreProgramProcess, type ProgramArea as CoreProgramArea, type Size, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
 import Events from "./events.js";
 import { type ProgramStartup } from "./startup.js";
 export interface HandleAddress {
@@ -13,6 +13,17 @@ export interface ProgramArea extends CoreProgramArea {
     resolve(...path: string[]): Promise<string>;
 }
 /** Client-safe Program data transported by the authoritative host. */
+export interface EndpointDeclarationRecord {
+    start: boolean;
+    hasService: boolean;
+}
+export interface ClientDeclarationRecord extends EndpointDeclarationRecord {
+    title: string | null;
+    size: Size | null;
+    position: Position | null;
+    layer: ClientDeclaration["layer"];
+    minimize: boolean | null;
+}
 export interface ProgramRecord {
     reference: string;
     identity: string;
@@ -20,8 +31,8 @@ export interface ProgramRecord {
     name: string;
     version: string | null;
     description: string | null;
-    server: EndpointDeclaration | null;
-    client: ClientDeclaration | null;
+    server: EndpointDeclarationRecord | null;
+    client: ClientDeclarationRecord | null;
 }
 /** Process data transported with every Endpoint reference. */
 export interface ProcessRecord {
@@ -57,7 +68,7 @@ export interface Program<Events extends object = {}> extends Omit<CoreProgram<Ev
     fork(identity: string): Promise<Program>;
 }
 /** Server-visible Process operations scoped to one Program. */
-export interface ProgramProcess extends Omit<CoreProgramProcess, "list" | "first" | "last" | "find" | "create"> {
+export interface ProgramProcess extends Omit<CoreProgramProcess, "list" | "first" | "last" | "find" | "create" | "findOrCreate"> {
     /** Returns every live Process of this Program. */
     list(): Promise<Process[]>;
     /** Returns the earliest-started live Process, or `null` when none exist. */
@@ -68,6 +79,10 @@ export interface ProgramProcess extends Omit<CoreProgramProcess, "list" | "first
     find(identityOrName: string): Promise<Process | null>;
     /** Creates one Process of this Program. */
     create(launch?: Launch): Promise<Process>;
+    /** Finds the named Process or atomically creates it with the same resolved launch. */
+    findOrCreate(launch: Launch & Readonly<{
+        name: string;
+    }>): Promise<Process>;
 }
 /** Server-visible Process handle. */
 export interface Process<Events extends object = {}> extends CoreProcess<Events> {

package/dist/domain.js

@@ -43,8 +43,12 @@ class ProgramHandle extends ProgramBase {
     get name() { return this.record.name; }
     get version() { return this.record.version; }
     get description() { return this.record.description; }
-    get server() { return this.record.server; }
-    get client() { return this.record.client; }
+    get server() {
+        return this.record.server ? declaration(this.address, "server", this.record.server) : null;
+    }
+    get client() {
+        return this.record.client ? clientDeclaration(this.address, this.record.client) : null;
+    }
     get address() { return { identity: this.identity, reference: this.reference }; }
     update(record) {
         if (record.reference !== this.reference)
@@ -74,6 +78,29 @@ class ProgramHandle extends ProgramBase {
         await wire.request(["forget", this.address]);
     }
 }
+function declaration(address, endpoint, record) {
+    return Object.freeze({
+        start: record.start,
+        hasService: () => record.hasService,
+        docs: () => endpointDocs(address, endpoint, record.hasService)
+    });
+}
+function clientDeclaration(address, record) {
+    return Object.freeze({
+        ...declaration(address, "client", record),
+        title: record.title,
+        size: record.size,
+        position: record.position,
+        layer: record.layer,
+        minimize: record.minimize
+    });
+}
+async function endpointDocs(address, endpoint, declared) {
+    if (!declared)
+        return null;
+    const answer = await wire.request(["endpoint-docs", address, endpoint]);
+    return answer[0];
+}
 class ProgramProcessHandle {
     address;
     constructor(address, reference) {
@@ -98,6 +125,10 @@ class ProgramProcessHandle {
         const answer = await wire.request(["program-process-create", this.address, launch]);
         return process(answer[0]);
     }
+    async findOrCreate(launch) {
+        const answer = await wire.request(["program-process-find-or-create", this.address, launch]);
+        return process(answer[0]);
+    }
     async exitAll() {
         const answer = await wire.request(["program-process-exit-all", this.address]);
         return answer[0];

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ClientServiceHandler, ServerServiceHandler, ServiceKey, ServiceRegistryEvents, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
+import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ClientServiceHandler, ServerServiceHandler, ServiceKey, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
 import { type Client, type Process, type Program, type Server } from "./domain.js";
 /** Resolved production description for a Program's Server. */
 export type ServerDescription = Readonly<{
@@ -6,6 +6,8 @@ export type ServerDescription = Readonly<{
     location: string;
     /** Whether newly created Processes start this Server by default. */
     start?: boolean;
+    /** Absolute Markdown file documenting the Service this Server may expose. */
+    serviceDocs?: string;
     /** Command used to install the Server's production dependencies. */
     installCommand?: string;
     /** Command used to start the Server from its production directory. */
@@ -17,6 +19,8 @@ export type ClientDescription = Readonly<{
     location: string;
     /** Whether newly created Processes start this Client by default. */
     start?: boolean;
+    /** Absolute Markdown file documenting the Service this Client may expose. */
+    serviceDocs?: string;
     /** Default Window title. */
     title?: string;
     /** Default Window size. */
@@ -99,16 +103,6 @@ export interface HostProcess extends Subscribable<ProcessHostEvents, never> {
     list(): Promise<Process[]>;
     find(identity: string): Promise<Process | null>;
 }
-/** Authoritative public service registry available to a Server endpoint. */
-export interface HostService extends Subscribable<ServiceRegistryEvents, never> {
-    list(): Promise<readonly ServiceKey[]>;
-    prepare<ServiceEvents extends object = {}>(key: ServiceKey & {
-        endpoint: "server";
-    }): ServerServiceHandler<ServiceEvents>;
-    prepare<ServiceEvents extends object = {}>(key: ServiceKey & {
-        endpoint: "client";
-    }): ClientServiceHandler<ServiceEvents>;
-}
 /** Authoritative system capabilities available to a Server endpoint. */
 export interface Host {
     /** Observable system Theme authority. */
@@ -119,7 +113,13 @@ export interface Host {
     readonly desktopWallpaper: DesktopWallpaper;
     readonly program: HostProgram;
     readonly process: HostProcess;
-    readonly service: HostService;
+    /** Returns a stable handle for one exact Service identity. */
+    service<ServiceEvents extends object = {}>(key: ServiceKey & {
+        endpoint: "server";
+    }): ServerServiceHandler<ServiceEvents>;
+    service<ServiceEvents extends object = {}>(key: ServiceKey & {
+        endpoint: "client";
+    }): ClientServiceHandler<ServiceEvents>;
     /** Publishes a value through the host and returns its public file metadata. */
     serve(value: unknown): Promise<ServedFile>;
 }

package/dist/host.js

@@ -11,7 +11,7 @@ class ServerHost {
     desktopWallpaper = new ServerDesktopWallpaper();
     program = new ServerHostProgram();
     process = new ServerHostProcess();
-    service = new ServerHostService();
+    service(key) { return prepareService(key); }
     serve(value) { return serve(value); }
 }
 class ServerHostProgram extends Events {
@@ -50,21 +50,6 @@ class ServerHostProcess extends Events {
         return answer[0] ? process(answer[0]) : null;
     }
 }
-class ServerHostService extends Events {
-    constructor() {
-        super((event, listener) => wire.followServiceRegistry(event, listener), observer => wire.followServiceRegistry(null, (event, key) => {
-            if (typeof event === "string")
-                observer(event, key);
-        }));
-    }
-    async list() {
-        const answer = await wire.request(["host-service-list"]);
-        return Object.freeze(answer[0]);
-    }
-    prepare(key) {
-        return prepareService(key);
-    }
-}
 function hostProcessEvent(event, values) {
     if (event === "endpointStart" || event === "endpointStop")
         return lifecycleEndpoint(values[1], values[2]);

package/dist/main.d.ts

@@ -1,4 +1,4 @@
-export { host, type Host, type HostProcess, type HostProgram, type HostService, type ClientDescription, type ProcessHostEvents, type ProcessHostExit, type ProgramHostEvents, type ProgramHostUninstall, type ProgramDescription, type ServerDescription } from "./host.js";
+export { host, type Host, type HostProcess, type HostProgram, type ClientDescription, type ProcessHostEvents, type ProcessHostExit, type ProgramHostEvents, type ProgramHostUninstall, type ProgramDescription, type ServerDescription } from "./host.js";
 export { current, type Current, type CurrentClient } from "./current.js";
 export { type Answerer, type Channel } from "./channel.js";
 export { type ProgramStartup } from "./startup.js";

package/dist/service.d.ts

@@ -1,4 +1,4 @@
-import { type ClientServiceHandler, type ServerServiceDefinition, type ServerServiceHandler, type ServiceHandler, type ServiceKey } from "@phreshos/core";
+import { type ClientServiceHandler, type ServerServiceHandler, type ServiceHandler, type ServiceKey } from "@phreshos/core";
 import type { HandleAddress } from "./domain.js";
 export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
     endpoint: "server";
@@ -7,7 +7,7 @@ export declare function prepareService<EventsMap extends object = {}>(key: Servi
     endpoint: "client";
 }): ClientServiceHandler<EventsMap>;
 export declare function prepareService(key: ServiceKey): ServiceHandler;
-export declare function enableCurrentService(definition: ServerServiceDefinition): Promise<void>;
+export declare function enableCurrentService(name: string): Promise<void>;
 export declare function disableCurrentService(): Promise<void>;
 export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "server"): Promise<ServerServiceHandler<EventsMap> | null>;
 export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "client"): Promise<ClientServiceHandler<EventsMap> | null>;

package/dist/service.js

@@ -63,10 +63,6 @@ class ServerHandler extends ServerServiceBase {
     async waitReady(timeout) {
         await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
-    async docs() {
-        const answer = await wire.request(["service-docs", this.key]);
-        return answer[0];
-    }
 }
 class ClientHandler extends ClientServiceBase {
     key;
@@ -98,8 +94,8 @@ export function prepareService(key) {
             : new ClientHandler(normalized);
     });
 }
-export async function enableCurrentService(definition) {
-    await wire.request(["enable-service", definition]);
+export async function enableCurrentService(name) {
+    await wire.request(["enable-service", name]);
 }
 export async function disableCurrentService() {
     await wire.request(["disable-service"]);

package/dist/wire.d.ts

@@ -32,8 +32,6 @@ declare class Wire {
     follow(target: HandleAddress | null, half: "server" | "client", event: string | null, handler: Handler, impossible?: Failure): Cleanup;
     /** Follow one exact service lifecycle or application event route. */
     followService(key: ServiceKey, scope: "lifecycle" | "channel", event: string | null, handler: Handler): Cleanup;
-    /** Follow lifecycle changes across the authoritative service registry. */
-    followServiceRegistry(event: string | null, handler: Handler): Cleanup;
     private register;
     private unregister;
     private deliver;

package/dist/wire.js

@@ -176,16 +176,6 @@ class Wire {
             this.send("end-host", "service-unfollow", subscription);
         });
     }
-    /** Follow lifecycle changes across the authoritative service registry. */
-    followServiceRegistry(event, handler) {
-        const subscription = randomUUID();
-        const stop = this.on("service-registry-event", subscription, handler);
-        this.send("end-host", "service-registry-follow", subscription, event);
-        return once(() => {
-            stop();
-            this.send("end-host", "service-registry-unfollow", subscription);
-        });
-    }
     register(kind, route, event, subject, impossible) {
         const subscription = randomUUID();
         if (impossible)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "The SDK used by a Program's server endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -46,13 +46,13 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.9"
+    "@phreshos/core": "^0.1.11"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.9",
+    "@phreshos/core": "^0.1.11",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }