@phreshos/server 0.1.14 → 0.1.16

package/README.md

@@ -110,12 +110,20 @@ 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 `Storage` values 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.
 
+`host.storage` implements that same refined `Storage` contract against the
+native operating-system home directory. The System supplies the authoritative
+root; traversal and symbolic-link escape remain rejected by the SDK before any
+filesystem operation.
+
 Host registries are separated by owner. Reads, commands, and the complete
 subscription contract live on their relevant capability rather than directly
 on `host`:
@@ -190,3 +198,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,18 +1,12 @@
-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 Size, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
 import Events from "./events.js";
+import { type Storage } from "./storage.js";
 import { type ProgramStartup } from "./startup.js";
 import { type ClientServiceHandler, type ServerServiceHandler } from "./service.js";
 export interface HandleAddress {
     identity: string;
     reference: string;
 }
-/** Server-side filesystem storage with access to its resolved host path. */
-export interface ProgramArea extends CoreProgramArea {
-    /** Returns the absolute host path of this storage area. */
-    path(): Promise<string>;
-    /** Resolves path segments within this storage area without permitting escape. */
-    resolve(...path: string[]): Promise<string>;
-}
 /** Client-safe Program data transported by the authoritative host. */
 export interface EndpointDeclarationRecord {
     start: boolean;
@@ -54,17 +48,17 @@ export type WindowRecord = WindowState;
 /** Server-visible Program handle and privileged Program operations. */
 export interface Program<Events extends object = {}> extends Omit<CoreProgram<Events>, "process"> {
     /** Persistent filesystem data shared by every Process of this Program. */
-    readonly data: ProgramArea;
+    readonly data: Storage;
     /** Disposable filesystem data shared by every Process of this Program. */
-    readonly cache: ProgramArea;
+    readonly cache: Storage;
     /** Persistent Process launch used when the system starts. */
     readonly startup: ProgramStartup;
     /** Persistent permission decisions owned by this Program. */
     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/host.d.ts

@@ -1,6 +1,7 @@
 import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ServiceKey, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
 import type { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 import { type Client, type Process, type Program, type Server } from "./domain.js";
+import { type Storage } from "./storage.js";
 /** Resolved production description for a Program's Server. */
 export type ServerDescription = Readonly<{
     /** Absolute directory containing the production Server files. */
@@ -104,6 +105,8 @@ export interface HostProcess extends Subscribable<ProcessHostEvents, never> {
 }
 /** Authoritative system capabilities available to a Server endpoint. */
 export interface Host {
+    /** Native operating-system home storage available to Server endpoints. */
+    readonly storage: Storage;
     /** Observable system Theme authority. */
     readonly theme: WritableTheme<ThemeProperties>;
     /** Authoritative wallpaper visible before authentication. */

package/dist/host.js

@@ -5,7 +5,9 @@ import ServerTheme from "./theme.js";
 import { ServerDesktopWallpaper, ServerSignInWallpaper } from "./wallpaper.js";
 import wire from "./wire.js";
 import { prepareService } from "./service.js";
+import { hostStorage } from "./storage.js";
 class ServerHost {
+    storage = hostStorage();
     theme = new ServerTheme();
     signInWallpaper = new ServerSignInWallpaper();
     desktopWallpaper = new ServerDesktopWallpaper();

package/dist/main.d.ts

@@ -2,7 +2,8 @@ export { host, type Host, type HostProcess, type HostProgram, type ClientDescrip
 export { current, type Current, type CurrentClient } from "./current.js";
 export { type Answerer, type Channel } from "./channel.js";
 export { type ProgramStartup } from "./startup.js";
+export { type Storage } from "./storage.js";
 export { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 export { ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
-export { Client, Endpoint, Process, Program, Server, type Window, type ProgramArea, type ProgramProcess } from "./domain.js";
+export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess } from "./domain.js";
 export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ChannelCapture, ChannelEvents, ChannelMessage, ClientTraffic, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointTraffic, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Position, ProgramEvents, ProgramPermission, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, ServerTraffic, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Theme, ThemeEvents, ThemeProperties, WallpaperLaunch, FileWallpaper, DesktopWallpaper, WritableTheme, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";

package/dist/main.js

@@ -2,6 +2,7 @@ export { host } from "./host.js";
 export { current } from "./current.js";
 export {} from "./channel.js";
 export {} from "./startup.js";
+export {} from "./storage.js";
 export { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 export { ServiceHandler } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/storage.d.ts

@@ -1,11 +1,13 @@
-import type { ProgramArea, ProgramSql, ProgramStore } from "@phreshos/core";
+import type { ProgramSql, ProgramStore, Storage as CoreStorage } from "@phreshos/core";
 import type { HandleAddress } from "./domain.js";
-export interface ServerArea extends ProgramArea {
+export interface Storage extends CoreStorage {
     path(): Promise<string>;
     resolve(...path: string[]): Promise<string>;
 }
 /** Server-local implementation of one Program-owned filesystem area. */
-export declare function area(program: HandleAddress, which: "data" | "cache"): ServerArea;
+export declare function area(program: HandleAddress, which: "data" | "cache"): Storage;
+/** Server-local access to the native home directory supplied by the System. */
+export declare function hostStorage(): Storage;
 export declare function store(program: HandleAddress): ProgramStore;
 export declare function sql(kind: "database" | "logs", program: HandleAddress): ProgramSql;
 export declare function content(value: unknown): {

package/dist/storage.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { createReadStream, createWriteStream, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { createReadStream, createWriteStream, mkdirSync, lstatSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { Readable } from "node:stream";
@@ -7,31 +7,50 @@ import { pipeline } from "node:stream/promises";
 import wire from "./wire.js";
 /** Server-local implementation of one Program-owned filesystem area. */
 export function area(program, which) {
-    async function path() {
+    return createStorage(async function () {
         const answer = await wire.request([which, program, "path"]);
         return answer[0];
+    }, `this Program's ${which}`);
+}
+/** Server-local access to the native home directory supplied by the System. */
+export function hostStorage() {
+    return createStorage(async function () {
+        const answer = await wire.request(["host-storage", "path"]);
+        return answer[0];
+    }, "the native home directory");
+}
+function createStorage(root, label) {
+    let resolvedRoot = null;
+    async function path() {
+        if (!resolvedRoot) {
+            const resolving = root().then(value => {
+                if (!isAbsolute(value))
+                    throw new Error("The host returned an invalid Storage directory");
+                return value;
+            });
+            const retained = resolving.catch(error => {
+                if (resolvedRoot === retained)
+                    resolvedRoot = null;
+                throw error;
+            });
+            resolvedRoot = retained;
+        }
+        return resolvedRoot;
     }
     async function resolve(...parts) {
         const root = await path();
-        const destination = join(root, ...parts);
-        const step = relative(root, destination);
-        if (step === ".." || step.startsWith(`..${sep}`) || isAbsolute(step)) {
-            throw new Error("A storage path may not leave its area");
-        }
-        return destination;
+        return contained(root, parts);
     }
     async function stream(...parts) {
         const destination = await resolve(...parts);
         const found = describe(destination);
         if (!found)
-            throw new Error(`There is no ${parts.join("/")} in this Program's ${which}`);
+            throw new Error(`There is no ${parts.join("/")} in ${label}`);
         if (found.kind !== "file")
             throw new Error(`${parts.join("/")} is not a file`);
         return Readable.toWeb(createReadStream(destination));
     }
     async function write(...args) {
-        if (args.length < 2)
-            throw new Error("Writing takes a file name and what to write");
         const parts = args.slice(0, -1);
         const destination = await resolve(...parts);
         const temporary = join(dirname(destination), `.${randomUUID()}.writing`);
@@ -70,13 +89,38 @@ export function area(program, which) {
                 throw new Error("Emptying a place is clear, not delete");
             rmSync(await resolve(...parts), { recursive: true, force: true });
         },
-        async clear() {
-            const root = await path();
-            rmSync(root, { recursive: true, force: true });
-            mkdirSync(root, { recursive: true });
+        async clear(...parts) {
+            const destination = await resolve(...parts);
+            const found = describe(destination);
+            if (found && found.kind !== "directory")
+                throw new Error("Only a storage directory can be cleared");
+            rmSync(destination, { recursive: true, force: true });
+            mkdirSync(destination, { recursive: true });
         }
     };
 }
+function contained(root, parts) {
+    const destination = join(root, ...parts);
+    const step = relative(root, destination);
+    if (step === ".." || step.startsWith(`..${sep}`) || isAbsolute(step)) {
+        throw new Error("A storage path may not leave its configured directory");
+    }
+    let current = root;
+    for (const part of step.split(sep).filter(Boolean)) {
+        current = join(current, part);
+        try {
+            if (lstatSync(current).isSymbolicLink()) {
+                throw new Error("A storage path may not pass through a symbolic link");
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                break;
+            throw error;
+        }
+    }
+    return destination;
+}
 export function store(program) {
     async function ask(operation, ...values) {
         const answer = await wire.request(["store", program, operation, ...values]);

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.16",
   "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.14",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }