@phreshos/server 0.1.14 → 0.1.15

package/README.md

@@ -110,9 +110,12 @@ incarnation is ready. The Server SDK owns one deadline across readiness and the
 answer; absence or incarnation loss rejects without turning a boundary into a
 waiter.
 
-Server Program handles add `install()` and `fork()`. Their filesystem areas
-also expose `path()` and traversal-safe `resolve()`, because filesystem work is
-performed locally in the Server SDK after the Host supplies only the area root.
+Server Program handles add `install()` and `fork()`. `install()` is an async
+generator that opens immediately, yields ordered `stdout` and `stderr` command
+chunks, completes only after installation succeeds, and throws the owning
+System error when installation fails. Their filesystem areas also expose
+`path()` and traversal-safe `resolve()`, because filesystem work is performed
+locally in the Server SDK after the Host supplies only the area root.
 Object descriptions passed to `host.program.create()` therefore require an
 explicit absolute storage root as well as at least one declared Endpoint.
 
@@ -190,3 +193,17 @@ The system validates this through the same launch contract as
 `program.process.create()`. Setting startup does not create a Process immediately.
 `uninstall(false)` preserves the configuration but makes it inactive until the
 Program is installed again; removing everything deletes it.
+
+Installation and uninstallation expose any declared Server command output as
+ordered streams. Consuming the generator waits for the authoritative operation
+to finish:
+
+```ts
+for await (const chunk of program.install()) {
+  (chunk.stream === "stderr" ? process.stderr : process.stdout).write(chunk.text)
+}
+
+for await (const chunk of program.uninstall(true)) {
+  (chunk.stream === "stderr" ? process.stderr : process.stdout).write(chunk.text)
+}
+```

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 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 { 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 ProgramCommandChunk, 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";
 import { type ClientServiceHandler, type ServerServiceHandler } from "./service.js";
@@ -63,8 +63,8 @@ export interface Program<Events extends object = {}> extends Omit<CoreProgram<Ev
     readonly permission: ProgramPermission;
     /** Operations and lifecycle observation for this Program's Processes. */
     readonly process: ProgramProcess;
-    /** Installs this Program and returns the same handle. */
-    install(): Promise<this>;
+    /** Installs this Program while yielding its command output in order. */
+    install(): AsyncGenerator<ProgramCommandChunk, void, void>;
     /** Creates a new runtime Program with the supplied stable identity. */
     fork(identity: string): Promise<Program>;
 }

package/dist/domain.js

@@ -70,21 +70,31 @@ class ProgramHandle extends ProgramBase {
         const answer = await wire.request(["installed", this.address]);
         return answer[0];
     }
-    async install() {
-        await wire.request(["install", this.address]);
-        return this;
+    async *install() {
+        for await (const value of wire.stream(["install", this.address])) {
+            yield programCommandChunk(value);
+        }
     }
     async fork(identity) {
         const answer = await wire.request(["fork", this.address, identity]);
         return program(answer[0]);
     }
-    async uninstall(everything = false) {
-        await wire.request(["uninstall", this.address, everything]);
+    async *uninstall(everything = false) {
+        for await (const value of wire.stream(["uninstall", this.address, everything])) {
+            yield programCommandChunk(value);
+        }
     }
     async forget() {
         await wire.request(["forget", this.address]);
     }
 }
+function programCommandChunk(value) {
+    const chunk = value;
+    if (!chunk || (chunk.stream !== "stdout" && chunk.stream !== "stderr") || typeof chunk.text !== "string") {
+        throw new Error("The host returned an invalid Program command chunk");
+    }
+    return Object.freeze({ stream: chunk.stream, text: chunk.text });
+}
 function declaration(record) {
     return Object.freeze({
         start: record.start

package/dist/wire.d.ts

@@ -7,6 +7,7 @@ type TrafficKind = "publish" | "ask" | "answer";
 /** The server endpoint's sole IPC adapter. */
 declare class Wire {
     private readonly pending;
+    private readonly streams;
     private readonly subscribers;
     private readonly every;
     private readonly answerers;
@@ -17,6 +18,8 @@ declare class Wire {
     send(route: string, ...values: unknown[]): void;
     request(values: unknown[], timeout?: number): Promise<unknown>;
     requestWithin(values: unknown[], deadline: Deadline): Promise<unknown>;
+    /** Opens one long-running host operation and yields its ordered values. */
+    stream(values: unknown[], timeout?: number): AsyncIterableIterator<unknown>;
     /** Resolves this endpoint's Process address only for operations that need it. */
     identity(): Promise<{
         process: string;
@@ -40,6 +43,7 @@ declare class Wire {
     private releaseWaiting;
     private forgetIncoming;
     private settle;
+    private receiveStream;
 }
 declare const _default: Wire;
 export default _default;

package/dist/wire.js

@@ -5,6 +5,7 @@ import { deserialize, serialize } from "./messagepack.js";
 /** The server endpoint's sole IPC adapter. */
 class Wire {
     pending = new Map();
+    streams = new Map();
     subscribers = new Map();
     every = new Map();
     answerers = new Map();
@@ -35,6 +36,10 @@ class Wire {
                 }
                 return;
             }
+            if (values[0] === "stream" && typeof values[1] === "string" && typeof values[2] === "string") {
+                this.receiveStream(values[1], values[2], values[3]);
+                return;
+            }
             if (values[0] === "answer" && typeof values[1] === "string") {
                 this.settle(values[1], values.at(-1));
                 return;
@@ -66,6 +71,46 @@ class Wire {
             this.send("end-host", "wait", question, ...values);
         });
     }
+    /** Opens one long-running host operation and yields its ordered values. */
+    stream(values, timeout = defaultTimeout) {
+        const wire = this;
+        return (async function* () {
+            const question = randomUUID();
+            const state = {
+                queue: [],
+                opened: false,
+                ended: false,
+                failure: null,
+                wake: null,
+                timer: setTimeout(() => {
+                    state.failure = new Error(`Answer timeout ${timeout}ms`);
+                    state.wake?.();
+                    state.wake = null;
+                }, timeout)
+            };
+            wire.send("boundary", "expect", question);
+            wire.streams.set(question, state);
+            wire.send("end-host", "stream", question, ...values);
+            try {
+                while (true) {
+                    if (state.queue.length) {
+                        yield state.queue.shift();
+                        continue;
+                    }
+                    if (state.failure)
+                        throw state.failure;
+                    if (state.ended)
+                        return;
+                    await new Promise(resolve => { state.wake = resolve; });
+                }
+            }
+            finally {
+                clearTimeout(state.timer);
+                wire.streams.delete(question);
+                wire.send("boundary", "forget", question);
+            }
+        })();
+    }
     /** Resolves this endpoint's Process address only for operations that need it. */
     identity() {
         if (!this.identityPromise) {
@@ -255,7 +300,44 @@ class Wire {
         else
             pending.reject(new Error("The boundary returned an invalid outcome"));
     }
+    receiveStream(question, operation, value) {
+        const stream = this.streams.get(question);
+        if (!stream || stream.ended || stream.failure)
+            return;
+        if (operation === "open") {
+            if (stream.opened)
+                return;
+            stream.opened = true;
+            clearTimeout(stream.timer);
+        }
+        else if (!stream.opened) {
+            stream.failure = new Error("The boundary produced a stream value before opening the stream");
+        }
+        else if (operation === "data") {
+            if (stream.queue.length >= maximumStreamQueue) {
+                stream.failure = new Error(`Host stream queue exceeded its capacity of ${maximumStreamQueue}`);
+            }
+            else {
+                stream.queue.push(value);
+            }
+        }
+        else if (operation === "answer") {
+            const outcome = value;
+            if (outcome?.success === true)
+                stream.ended = true;
+            else if (outcome?.success === false && typeof outcome.error === "string")
+                stream.failure = new Error(outcome.error);
+            else
+                stream.failure = new Error("The boundary returned an invalid stream outcome");
+        }
+        else {
+            stream.failure = new Error(`The boundary returned an invalid stream operation "${operation}"`);
+        }
+        stream.wake?.();
+        stream.wake = null;
+    }
 }
+const maximumStreamQueue = 256;
 function failed(error) {
     return {
         success: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "The SDK used by a Program's server endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -52,7 +52,7 @@
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.12",
+    "@phreshos/core": "^0.1.13",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }