@phreshos/node 0.1.13 → 0.1.14

package/README.md

@@ -1,9 +1,22 @@
 # `@phreshos/node`
 
-Node.js access to a running PhreshOS System and local Program projects.
+Node.js access to a PhreshOS System and local Program projects.
 
-The Node SDK exposes the same System model used inside Server Endpoints and adds
-only connection lifecycle and project tooling.
+[Documentation](https://docs.phreshos.com/sdks/node) ·
+[System](https://docs.phreshos.com/system) ·
+[First Program](https://docs.phreshos.com/first-program) ·
+[Source](https://github.com/PhreshOS/node)
+
+## Role
+
+The Node SDK exposes the same complete System contract available inside Server
+Endpoints. It adds only the lifecycle of an externally owned connection and the
+`Project` authoring API for building, running, installing, and packaging local
+Program projects.
+
+The connection transport is not public API. Core owns the domain model, and the
+System remains authoritative whether an operation can execute locally or must
+cross the connection boundary.
 
 ## Installation
 
@@ -14,49 +27,21 @@ only connection lifecycle and project tooling.
 | Bun | `bun add @phreshos/node` |
 | Yarn | `yarn add @phreshos/node` |
 
-## System
-
-```ts
-import { System } from "@phreshos/node"
-
-const system = await System.connect()
-const programs = await system.program.list()
-
-await system.disconnect()
-```
-
-The transport is not public API. Code receives the same System, Program,
-Process, Endpoint, Service, Window, storage, and upload handles used by the
-Server SDK. `disconnect()` exists because external Node code owns the
-connection.
-
-## Project
-
 ```ts
 import { Project, System } from "@phreshos/node"
 
-const project = await Project.open()
 const system = await System.connect()
+const project = await Project.open()
 
-for await (const event of await project.start(system, { signal })) {
+for await (const event of await project.start(system)) {
   console.log(event)
 }
 
 await system.disconnect()
 ```
 
-`Project` owns authoring concerns: builds, development and production
-definitions, installation, execution shortcuts, and packaging. The System
-receives only the resulting Program definition.
-
-`Project.dev()` starts and supervises a declared Client development command. It
-assigns an available port when no URL is declared and provides the port and
-public Program asset base through `PHRESHOS_CLIENT_PORT` and
-`PHRESHOS_CLIENT_BASE`.
-
-`Project.open()` starts from the current working directory by default.
-`System.connect()` resolves an explicit System home, then `PHRESHOS_HOME`,
-then the current owner's default System home.
+See [Node SDK](https://docs.phreshos.com/sdks/node) for System connection and
+Project lifecycle details.
 
 ## Development
 
@@ -65,14 +50,19 @@ bun install --frozen-lockfile
 bun run verify
 ```
 
-See the [Node SDK documentation](https://github.com/PhreshOS/docs/blob/main/content/docs/sdks/node.mdx)
-for the public model.
+`verify` checks the types, builds the package, and runs the connection and
+Project tests.
 
-## Repository boundary
+## Related repositories
 
-This repository owns the external Node connection and local-project API. Core
-owns the domain model, Server owns the Endpoint runtime adapter, and CLI owns
-terminal presentation and native service management.
+- [`@phreshos/core`](https://github.com/PhreshOS/core) owns the shared System
+  and runtime contracts.
+- [`@phreshos/server`](https://github.com/PhreshOS/server) exposes the same
+  System contract inside Server Endpoints.
+- [`@phreshos/cli`](https://github.com/PhreshOS/cli) presents Project and System
+  operations as terminal commands.
+- [PhreshOS System](https://github.com/PhreshOS/system) owns the connected
+  runtime.
 
 ## License
 

package/dist/events.d.ts

@@ -1,12 +1,12 @@
 import type { Cleanup, EventOptions, Subscribable } from "@phreshos/core";
-type Wait = (event: string | null, signal: AbortSignal, timeout?: number) => Promise<unknown>;
 type Failure = (error: Error) => void;
 type Register<Message> = (subscriber: (message: Message) => unknown, impossible?: Failure) => Cleanup;
-/** Adapts authoritative one-event waits into the shared Subscribable contract. */
+type Subscribe = (event: string | null, subscriber: (message: unknown) => unknown, impossible?: Failure) => Cleanup;
+/** Adapts one live representation source into the shared Subscribable contract. */
 export default class Events<Definitions extends object, Fallback = never> {
     private readonly names;
-    private readonly wait;
-    constructor(names: readonly string[], wait: Wait);
+    private readonly register;
+    constructor(names: readonly string[], register: Subscribe);
     readonly subscribe: Subscribable<Definitions, Fallback>["subscribe"];
     readonly waitFor: Subscribable<Definitions, Fallback>["waitFor"];
     readonly events: Subscribable<Definitions, Fallback>["events"];

package/dist/events.js

@@ -1,10 +1,10 @@
-/** Adapts authoritative one-event waits into the shared Subscribable contract. */
+/** Adapts one live representation source into the shared Subscribable contract. */
 export default class Events {
     names;
-    wait;
-    constructor(names, wait) {
+    register;
+    constructor(names, register) {
         this.names = names;
-        this.wait = wait;
+        this.register = register;
     }
     subscribe = ((eventOrSubscriber, subscriber) => {
         if (typeof eventOrSubscriber === "string")
@@ -19,9 +19,19 @@ export default class Events {
                 eventOrSubscriber({ event: capture.event, message: capture.payload });
         });
     });
-    waitFor = ((event, timeout) => {
-        return this.wait(event, new AbortController().signal, timeout);
-    });
+    waitFor = ((event, timeout = 10_000) => new Promise((resolve, reject) => {
+        let stop = () => undefined;
+        const timer = setTimeout(() => {
+            stop();
+            reject(new Error(`The "${event}" event did not occur before the timeout`));
+        }, timeout);
+        const finish = (work) => {
+            clearTimeout(timer);
+            stop();
+            work();
+        };
+        stop = this.listen(event, message => finish(() => resolve(message)), error => finish(() => reject(error)));
+    }));
     events = ((eventOrOptions = {}, namedOptions = {}) => {
         if (typeof eventOrOptions === "string") {
             return stream((subscriber, impossible) => this.listen(eventOrOptions, subscriber, impossible), namedOptions);
@@ -39,22 +49,7 @@ export default class Events {
         }, eventOrOptions);
     });
     listen(event, subscriber, impossible) {
-        const controller = new AbortController();
-        void (async () => {
-            while (!controller.signal.aborted) {
-                try {
-                    subscriber(await this.wait(event, controller.signal, 86_400_000));
-                }
-                catch (error) {
-                    if (!controller.signal.aborted && timeout(error))
-                        continue;
-                    if (!controller.signal.aborted)
-                        impossible?.(failure(error));
-                    controller.abort();
-                }
-            }
-        })();
-        return () => controller.abort();
+        return this.register(event, subscriber, impossible);
     }
 }
 export function stream(register, options = {}) {
@@ -109,9 +104,3 @@ export function stream(register, options = {}) {
         }
     })();
 }
-function timeout(error) {
-    return error instanceof Error && /timeout|timed out/i.test(error.message);
-}
-function failure(error) {
-    return error instanceof Error ? error : new Error(String(error));
-}

package/dist/main.d.ts

@@ -1,5 +1,5 @@
 export { gatewayAddress } from "./address.js";
 export { ClientEndpoint, ClientService, Endpoint, Process, Program, ServerEndpoint, ServerService, System, type ProgramProcessRunEvent, type ProgramProcessRunOptions } from "./system.js";
-export { Service, type ClientLaunch, type Launch, type Permission, type PermissionChange, type PermissionInput, type Permissions, type ProgramPermissions, type ProgramDefinition, type ServerLaunch, type ServiceKey, type ShellEvent, type ShellOptions, type ProgramStartup, type Storage, } from "@phreshos/core";
+export { Service, clientPermissionCatalog, isPermissionName, type ClientLaunch, type Launch, type Permission, type PermissionChange, type PermissionDefinition, type PermissionDefinitions, type PermissionInput, type PermissionName, type PermissionValue, type PermissionValueDomain, type Permissions, type ProgramPermissions, type ProgramDefinition, type ServerLaunch, type ServiceKey, type ShellEvent, type ShellOptions, type ProgramStartup, type Storage, } from "@phreshos/core";
 export { resolveHome } from "./home.js";
 export { Project, type Manifest, type PackedProject, type ProjectMode, type ProjectOptions, type ProjectRunOptions } from "./project.js";

package/dist/main.js

@@ -1,5 +1,5 @@
 export { gatewayAddress } from "./address.js";
 export { ClientEndpoint, ClientService, Endpoint, Process, Program, ServerEndpoint, ServerService, System } from "./system.js";
-export { Service, } from "@phreshos/core";
+export { Service, clientPermissionCatalog, isPermissionName, } from "@phreshos/core";
 export { resolveHome } from "./home.js";
 export { Project } from "./project.js";

package/dist/program-resources.d.ts

@@ -1,13 +1,13 @@
 import { type ProgramPermissions, type ProgramSql, type ProgramStore } from "@phreshos/core";
-type Request = (value: object) => Promise<unknown>;
+type Call = <Result = unknown>(event: string, ...values: unknown[]) => Promise<Result>;
 type ProgramAddress = Readonly<{
     identity: string;
     reference: string;
 }>;
 /** Program-owned key-value storage carried through the owner-local Gateway. */
-export declare function programStore(request: Request, handle: ProgramAddress): ProgramStore;
+export declare function programStore(call: Call, handle: ProgramAddress): ProgramStore;
 /** Program-owned SQL capability carried through the owner-local Gateway. */
-export declare function programSql(request: Request, handle: ProgramAddress, database: "database" | "logs"): ProgramSql;
+export declare function programSql(call: Call, handle: ProgramAddress, database: "database" | "logs"): ProgramSql;
 /** Program permission management carried through the owner-local Gateway. */
-export declare function programPermissions(request: Request, handle: ProgramAddress): ProgramPermissions;
+export declare function programPermissions(call: Call, handle: ProgramAddress): ProgramPermissions;
 export {};

package/dist/program-resources.js

@@ -1,15 +1,7 @@
 import { parsePermission, parsePermissionChange, parsePermissions } from "@phreshos/core";
 /** Program-owned key-value storage carried through the owner-local Gateway. */
-export function programStore(request, handle) {
-    const operate = (storeOperation, key, value, ttl) => request({
-        capability: "program",
-        operation: "store",
-        handle,
-        storeOperation,
-        key,
-        value,
-        ttl
-    });
+export function programStore(call, handle) {
+    const operate = (storeOperation, key, value, ttl) => (call("/program/store", handle, storeOperation, key, value, ttl));
     return {
         get: (key) => operate("get", key),
         set: (key, value, ttl) => operate("set", key, value, ttl),
@@ -19,29 +11,22 @@ export function programStore(request, handle) {
     };
 }
 /** Program-owned SQL capability carried through the owner-local Gateway. */
-export function programSql(request, handle, database) {
+export function programSql(call, handle, database) {
     return {
         query(statement, ...rest) {
             const [text, values] = written(statement, rest);
-            return request({ capability: "program", operation: "query", handle, database, statement: text, values });
+            return call(`/program/${database}`, handle, text, values);
         }
     };
 }
 /** Program permission management carried through the owner-local Gateway. */
-export function programPermissions(request, handle) {
-    const operate = (permissionOperation, name, permission) => request({
-        capability: "program",
-        operation: "permissions",
-        handle,
-        permissionOperation,
-        name,
-        permission
-    });
+export function programPermissions(call, handle) {
+    const operate = (permissionOperation, name, permission) => (call("/program/permissions", handle, permissionOperation, name, permission));
     return {
-        async get(name) { return parsePermission(await operate("get", name)); },
+        async get(name) { return parsePermission(name, await operate("get", name)); },
         async all() { return parsePermissions(await operate("all")); },
-        async set(name, permission) { return parsePermissionChange(await operate("set", name, permission)); },
-        async delete(name) { return parsePermissionChange(await operate("delete", name)); }
+        async set(name, permission) { return parsePermissionChange(name, await operate("set", name, permission)); },
+        async delete(name) { return parsePermissionChange(name, await operate("delete", name)); }
     };
 }
 function written(statement, rest) {

package/dist/representation.d.ts

@@ -0,0 +1,100 @@
+import type { Appearance, ClientDeclaration, EndpointDeclaration, ServiceKey, WindowGeometry, WindowLayer } from "@phreshos/core";
+import type { GatewayConnection } from "./transport.js";
+export interface ProgramState {
+    reference: string;
+    identity: string;
+    assetId: string;
+    installed: boolean;
+    name: string;
+    version: string | null;
+    description: string | null;
+    hasAgent: boolean;
+    server: EndpointDeclaration | null;
+    client: ClientDeclaration | null;
+}
+export interface WindowState {
+    title: string;
+    position: WindowGeometry["position"];
+    size: WindowGeometry["size"];
+    depth: number;
+    minimized: boolean;
+    layer: WindowLayer;
+    location: string;
+}
+export interface ProcessState {
+    reference: string;
+    identity: string;
+    name: string | null;
+    program: string;
+    parent: ProcessAddress | null;
+    options: Record<string, string>;
+    startedAt: Date;
+    server: {
+        ready: boolean;
+        service: boolean;
+    } | null;
+    client: {
+        service: boolean;
+        sameOrigin: boolean;
+        window: WindowState;
+    } | null;
+}
+export interface ProcessAddress {
+    reference: string;
+    identity: string;
+}
+export type Observation = Readonly<{
+    scope: "endpoint";
+    process: string;
+    endpoint: "server" | "client";
+    event: string | null;
+}> | Readonly<{
+    scope: "traffic";
+    process: string;
+    endpoint: "server" | "client";
+    kind: "publish" | "ask" | "answer";
+    event: string | null;
+}> | Readonly<{
+    scope: "service";
+    key: ServiceKey;
+    kind: "events" | "lifecycle";
+    event: string | null;
+}>;
+type Listener = (...values: unknown[]) => unknown;
+interface CommandEvent {
+    event?: string;
+    [key: string]: unknown;
+}
+/** A connection-owned, live representation of the authoritative System model. */
+export default class SystemRepresentation {
+    private readonly connection;
+    readonly authorization: string;
+    readonly programs: Map<string, ProgramState>;
+    readonly processes: Map<string, ProcessState>;
+    appearance: Appearance;
+    private readonly listeners;
+    private readonly release;
+    constructor(connection: GatewayConnection);
+    activate(): void;
+    close(): void;
+    call<Result = unknown>(event: string, ...values: unknown[]): Promise<Result>;
+    on(event: string, listener: Listener): () => void;
+    follow(observation: Observation, listener: (event: string, value: unknown) => unknown, impossible?: (error: Error) => void): () => void;
+    /** Stream one Program command through the live LinkManager connection. */
+    command(operation: "install" | "uninstall" | "run", subject: ProgramAddress, value: unknown, signal?: AbortSignal): AsyncGenerator<CommandEvent, void, unknown>;
+    private followModel;
+    private arriveProgram;
+    private uninstallProgram;
+    private forgetProgram;
+    private createProcess;
+    private serverReady;
+    private changeEndpoint;
+    private exitProcess;
+    private changeWindow;
+    private emit;
+}
+export type ProgramAddress = Readonly<{
+    identity: string;
+    reference: string;
+}>;
+export {};