@phreshos/server 0.1.0 → 0.1.1

package/dist/host.js

@@ -1,10 +1,15 @@
 import Events from "./events.js";
-import { exit, process, program } from "./domain.js";
+import { exit, lifecycleEndpoint, process, program } from "./domain.js";
 import serve from "./served.js";
+import ServerTheme from "./theme.js";
+import { ServerDesktopWallpaper, ServerSignInWallpaper } from "./wallpaper.js";
 import wire from "./wire.js";
 class ServerHost extends Events {
+    theme = new ServerTheme();
+    signInWallpaper = new ServerSignInWallpaper();
+    desktopWallpaper = new ServerDesktopWallpaper();
     constructor() {
-        super((event, listener, impossible) => wire.on("host-end", event, (...values) => listener(hostEvent(event, values)), null, impossible), observer => wire.onAll("host-end", (event, ...values) => {
+        super((event, listener, impossible) => wire.on("host-events", event, (...values) => listener(hostEvent(event, values)), null, impossible), observer => wire.onAll("host-events", (event, ...values) => {
             if (typeof event === "string")
                 observer(event, hostEvent(event, values));
         }));
@@ -24,7 +29,7 @@ class ServerHost extends Events {
     }
     async processes() {
         const answer = await wire.request(["processes"]);
-        return answer[0].map(process);
+        return answer[0].map(record => process(record));
     }
     async getProcess(identity) {
         const answer = await wire.request(["process", identity]);
@@ -32,12 +37,11 @@ class ServerHost extends Events {
     }
 }
 function hostEvent(event, values) {
-    if (event === "serverStart" || event === "clientStart" || event === "clientStop" || event === "processCreate") {
+    if (event === "endpointStart" || event === "endpointStop")
+        return lifecycleEndpoint(values[1], values[2]);
+    if (event === "processCreate") {
         return process(values[1]);
     }
-    if (event === "serverStop") {
-        return { process: process(values[1]), code: numberOrNull(values[2]), signal: stringOrNull(values[3]) };
-    }
     if (event === "processExit") {
         return { process: process(values[1]), ...exit(values[2], values[3]) };
     }
@@ -49,6 +53,5 @@ function hostEvent(event, values) {
     }
     return values[0];
 }
-function numberOrNull(value) { return typeof value === "number" ? value : null; }
-function stringOrNull(value) { return typeof value === "string" ? value : null; }
+/** Authoritative system capabilities for the currently executing Server. */
 export const host = new ServerHost();

package/dist/main.d.ts

@@ -1,5 +1,6 @@
-export { host, type Host, type ClientDescription, type HostEvents, type HostProcessExit, type HostProgramUninstall, type HostServerStop, type ProgramDescription, type ServerDescription } from "./host.js";
+export { host, type Host, type ClientDescription, type HostEvents, type HostProcessExit, type HostProgramUninstall, 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 { Client, Endpoint, Process, Program, Server, Window, type ProgramArea } 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, ProgramProcessExit, ProgramServerStop, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, ServerTraffic, Size, Subscribable, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, WindowEvents, WindowState } from "@phreshos/core";
+export { type ProgramStartup } from "./startup.js";
+export { Client, Endpoint, Process, Program, Server, type Window, type ProgramArea } 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, ProgramPermissions, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, ServerTraffic, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Theme, ThemeEvents, ThemeProperties, WallpaperLaunch, FileWallpaper, DesktopWallpaper, WritableTheme, WindowEvents, WindowLayer, WindowState, WindowSurface, WindowSurfaceEasing, WindowSurfaceEvents, WindowSurfaceSettings, WindowSurfaceTransaction } from "@phreshos/core";

package/dist/main.js

@@ -1,4 +1,5 @@
 export { host } from "./host.js";
 export { current } from "./current.js";
 export {} from "./channel.js";
-export { Client, Endpoint, Process, Program, Server, Window } from "./domain.js";
+export {} from "./startup.js";
+export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/permissions.d.ts

@@ -0,0 +1,3 @@
+import type { ProgramPermissions } from "@phreshos/core";
+/** Creates the persistent permission manager for one Program handle. */
+export default function permissions(program: unknown): ProgramPermissions;

package/dist/permissions.js

@@ -0,0 +1,20 @@
+import wire from "./wire.js";
+/** Creates the persistent permission manager for one Program handle. */
+export default function permissions(program) {
+    return {
+        async get(name) {
+            const answer = await wire.request(["permissions", program, "get", name]);
+            return answer[0];
+        },
+        async getAll() {
+            const answer = await wire.request(["permissions", program, "getAll"]);
+            return answer[0];
+        },
+        async set(name, value) {
+            await wire.request(["permissions", program, "set", name, value]);
+        },
+        async delete(name) {
+            await wire.request(["permissions", program, "delete", name]);
+        }
+    };
+}

package/dist/startup.d.ts

@@ -0,0 +1,13 @@
+import type { Launch } from "@phreshos/core";
+import type { HandleAddress } from "./domain.js";
+/** Persistent Process creation settings used when the system starts. */
+export interface ProgramStartup {
+    /** Returns the configured startup launch, or `null` when disabled. */
+    get(): Promise<Launch | null>;
+    /** Enables startup with one validated Process launch. */
+    enable(launch?: Launch): Promise<void>;
+    /** Disables startup by removing the persisted Process launch. */
+    disable(): Promise<void>;
+}
+/** Bind startup operations to one canonical Program handle. */
+export default function startup(program: HandleAddress): ProgramStartup;

package/dist/startup.js

@@ -0,0 +1,16 @@
+import wire from "./wire.js";
+/** Bind startup operations to one canonical Program handle. */
+export default function startup(program) {
+    return {
+        async get() {
+            const answer = await wire.request(["startup", program, "get"]);
+            return answer[0];
+        },
+        async enable(launch = {}) {
+            await wire.request(["startup", program, "enable", launch]);
+        },
+        async disable() {
+            await wire.request(["startup", program, "disable"]);
+        }
+    };
+}

package/dist/storage.d.ts

@@ -1,12 +1,13 @@
 import type { ProgramArea, ProgramSql, ProgramStore } from "@phreshos/core";
+import type { HandleAddress } from "./domain.js";
 export interface ServerArea extends ProgramArea {
     path(): Promise<string>;
     resolve(...path: string[]): Promise<string>;
 }
 /** Server-local implementation of one Program-owned filesystem area. */
-export declare function area(program: string, which: "data" | "cache"): ServerArea;
-export declare function store(program: string): ProgramStore;
-export declare function sql(kind: "database" | "logs", program: string): ProgramSql;
+export declare function area(program: HandleAddress, which: "data" | "cache"): ServerArea;
+export declare function store(program: HandleAddress): ProgramStore;
+export declare function sql(kind: "database" | "logs", program: HandleAddress): ProgramSql;
 export declare function content(value: unknown): {
     stream: ReadableStream<Uint8Array>;
     extension: string;

package/dist/theme.d.ts

@@ -0,0 +1,15 @@
+import { type ThemeProperties } from "@phreshos/core";
+import Events from "./events.js";
+/** System Theme authority reached explicitly through the server boundary. */
+export default class ServerTheme extends Events {
+    constructor();
+    snapshot(): Promise<Readonly<{
+        background: string;
+        foreground: string;
+        accent: string;
+        spacing: number;
+        radius: number;
+        glass: import("@phreshos/core").ThemeGlass;
+    }>>;
+    readonly update: (theme: ThemeProperties) => Promise<void>;
+}

package/dist/theme.js

@@ -0,0 +1,32 @@
+import { createThemeSnapshot } from "@phreshos/core";
+import Events from "./events.js";
+import wire from "./wire.js";
+/** System Theme authority reached explicitly through the server boundary. */
+export default class ServerTheme extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("host-theme", event, value => {
+            if (isObject(value))
+                listener(createThemeSnapshot(value));
+        }, null, impossible), observer => wire.onAll("host-theme", (event, value) => {
+            if (typeof event === "string" && isObject(value))
+                observer(event, createThemeSnapshot(value));
+        }));
+    }
+    async snapshot() {
+        const answer = await wire.request(["theme"]);
+        if (!isObject(answer[0]))
+            throw new Error("The host returned an invalid Theme snapshot");
+        return createThemeSnapshot(answer[0]);
+    }
+    update = async (theme) => {
+        await wire.request(["update-theme", theme]);
+    };
+}
+function isObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const theme = value;
+    return typeof theme.background === "string" && typeof theme.foreground === "string" && typeof theme.accent === "string"
+        && typeof theme.spacing === "number" && typeof theme.radius === "number"
+        && typeof theme.glass === "object" && theme.glass !== null;
+}

package/dist/wallpaper.d.ts

@@ -0,0 +1,18 @@
+import type { DesktopWallpaper, FileWallpaper, WallpaperLaunch } from "@phreshos/core";
+import { type Program } from "./domain.js";
+declare class ServerFileWallpaper implements FileWallpaper {
+    private readonly surface;
+    constructor(surface: "sign-in" | "desktop");
+    set(file: string): Promise<void>;
+    remove(): Promise<void>;
+}
+/** Authoritative sign-in wallpaper control available to Server endpoints. */
+export declare class ServerSignInWallpaper extends ServerFileWallpaper {
+    constructor();
+}
+/** Authoritative desktop wallpaper control available to Server endpoints. */
+export declare class ServerDesktopWallpaper extends ServerFileWallpaper implements DesktopWallpaper {
+    constructor();
+    setProgram(program: Program, launch?: WallpaperLaunch): Promise<void>;
+}
+export {};

package/dist/wallpaper.js

@@ -0,0 +1,25 @@
+import { programAddress } from "./domain.js";
+import wire from "./wire.js";
+class ServerFileWallpaper {
+    surface;
+    constructor(surface) {
+        this.surface = surface;
+    }
+    async set(file) {
+        await wire.request(["wallpaper", this.surface, "set", file]);
+    }
+    async remove() {
+        await wire.request(["wallpaper", this.surface, "remove"]);
+    }
+}
+/** Authoritative sign-in wallpaper control available to Server endpoints. */
+export class ServerSignInWallpaper extends ServerFileWallpaper {
+    constructor() { super("sign-in"); }
+}
+/** Authoritative desktop wallpaper control available to Server endpoints. */
+export class ServerDesktopWallpaper extends ServerFileWallpaper {
+    constructor() { super("desktop"); }
+    async setProgram(program, launch = {}) {
+        await wire.request(["wallpaper", "desktop", "set-program", programAddress(program), launch]);
+    }
+}

package/dist/wire.d.ts

@@ -1,5 +1,6 @@
 import type { Cleanup } from "@phreshos/core";
 import Deadline from "./deadline.js";
+import type { HandleAddress } from "./domain.js";
 type Handler = (...values: unknown[]) => unknown;
 type Failure = (error: Error) => void;
 type TrafficKind = "publish" | "ask" | "answer";
@@ -11,20 +12,24 @@ declare class Wire {
     private readonly answerers;
     private readonly waiting;
     private readonly impossible;
-    readonly identity: Promise<{
-        process: string;
-        program: string;
-    }>;
+    private identityPromise;
     constructor();
     send(route: string, ...values: unknown[]): void;
     request(values: unknown[], timeout?: number): Promise<unknown>;
     requestWithin(values: unknown[], deadline: Deadline): Promise<unknown>;
+    /** Resolves this endpoint's Process address only for operations that need it. */
+    identity(): Promise<{
+        process: string;
+        reference: string;
+    }>;
     expectWithin(question: string, deadline: Deadline): Promise<unknown>;
     forget(question: string): void;
     on(route: string, event: string, handler: Handler, subject?: string | null, impossible?: Failure): Cleanup;
     onAll(route: string, handler: Handler, subject?: string | null): Cleanup;
     answer(route: string, event: string, handler: Handler): Cleanup;
-    observe(target: string, half: "server" | "client", kind: TrafficKind, event: string | null, handler: Handler, impossible?: Failure): Cleanup;
+    observe(target: HandleAddress | null, half: "server" | "client", kind: TrafficKind, event: string | null, handler: Handler, impossible?: Failure): Cleanup;
+    /** Follow destinationless events emitted by one Endpoint. */
+    follow(target: HandleAddress | null, half: "server" | "client", event: string | null, handler: Handler, impossible?: Failure): Cleanup;
     private register;
     private unregister;
     private deliver;

package/dist/wire.js

@@ -9,10 +9,8 @@ class Wire {
     answerers = new Map();
     waiting = new Map();
     impossible = new Map();
-    identity;
+    identityPromise = null;
     constructor() {
-        let identify = () => undefined;
-        this.identity = new Promise(resolve => { identify = resolve; });
         process.on("message", message => {
             if (!Array.isArray(message))
                 return;
@@ -27,10 +25,6 @@ class Wire {
                 }
                 return;
             }
-            if (route === "host-end" && values[0] === "identity" && typeof values[1] === "string" && typeof values[2] === "string") {
-                identify({ process: values[1], program: values[2] });
-                return;
-            }
             if (values[0] === "answer" && typeof values[1] === "string") {
                 this.settle(values[1], values.at(-1));
                 return;
@@ -41,7 +35,6 @@ class Wire {
             }
             this.deliver(route, values);
         });
-        process.send?.(["boundary", "identity"]);
         process.send?.(["boundary", "ready"]);
     }
     send(route, ...values) {
@@ -63,6 +56,25 @@ class Wire {
             this.send("end-host", "wait", question, ...values);
         });
     }
+    /** Resolves this endpoint's Process address only for operations that need it. */
+    identity() {
+        if (!this.identityPromise) {
+            const resolving = this.request(["process"]).then(value => {
+                const [record] = value;
+                if (typeof record?.identity !== "string" || typeof record.reference !== "string") {
+                    throw new Error("The host returned an invalid Process identity");
+                }
+                return { process: record.identity, reference: record.reference };
+            });
+            const retained = resolving.catch(error => {
+                if (this.identityPromise === retained)
+                    this.identityPromise = null;
+                throw error;
+            });
+            this.identityPromise = retained;
+        }
+        return this.identityPromise;
+    }
     expectWithin(question, deadline) {
         return new Promise((resolve, reject) => {
             this.send("boundary", "expect", question);
@@ -131,6 +143,19 @@ class Wire {
             this.send("end-host", "unobserve", subscription);
         });
     }
+    /** Follow destinationless events emitted by one Endpoint. */
+    follow(target, half, event, handler, impossible) {
+        const subscription = randomUUID();
+        const stop = this.on("emitted", subscription, handler);
+        if (impossible)
+            this.impossible.set(subscription, impossible);
+        this.send("end-host", "follow", subscription, target, half, event, impossible !== undefined);
+        return once(() => {
+            stop();
+            this.impossible.delete(subscription);
+            this.send("end-host", "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.0",
+  "version": "0.1.1",
   "description": "The SDK used by a Program's server endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -13,18 +13,43 @@
   },
   "files": [
     "dist",
+    "LICENSE",
     "README.md"
   ],
+  "author": "Zohayr SLILEH",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PhreshOS/server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PhreshOS/server/issues"
+  },
+  "homepage": "https://github.com/PhreshOS/server#readme",
+  "keywords": [
+    "phreshos",
+    "server",
+    "sdk",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.3.14",
   "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "check": "tsc --noEmit",
-    "build": "tsc --noEmit false --outDir dist --rootDir source",
+    "build": "node --run clean && tsc --noEmit false --outDir dist --rootDir source",
+    "verify:package": "node scripts/verify-package.mjs",
+    "verify": "node --run check && node --run build && node --run verify:package",
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.0"
+    "@phreshos/core": "^0.1.1"
   },
   "devDependencies": {
-    "@phreshos/core": "0.1.0",
+    "@phreshos/core": "^0.1.1",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }