@phreshos/node 0.1.1 → 0.1.3

package/README.md

@@ -8,7 +8,9 @@ import { Project, System } from "@phreshos/node"
 const project = await Project.open()
 const system = await System.connect()
 
-await project.install(system)
+for await (const chunk of await project.install(system)) {
+  process[chunk.stream].write(chunk.text)
+}
 
 // This is the same transport-neutral System contract used by Server Programs.
 const programs = await system.program.list()
@@ -27,15 +29,38 @@ const project = await Project.open() // process.cwd()
 const system = await System.connect()
 
 await project.pack()
-await project.start(system, { signal })
-await project.dev(system, { signal })
-await project.install(system)
+for await (const event of await project.start(system, { signal })) {
+  // started, output, exited
+}
+
+for await (const event of await project.dev(system, { signal })) {
+  // started, output, exited
+}
+
+for await (const chunk of await project.install(system)) {
+  // stdout or stderr
+}
 
 await system.disconnect()
 ```
 
-`Project` owns authoring concepts such as production builds and development
-Client servers. The lower-level System API stays composable: use
-`system.forceCreateProgram(description)` to replace one runtime Program, and
+These shortcuts return the original `program.install()` or
+`program.process.run()` generator; they do not consume or mirror its events.
+The CLI owns presentation and its additional development Client server.
+
+For custom composition, resolve either Program definition explicitly:
+
+```ts
+const definition = project.productionDefinition()
+// const definition = project.developmentDefinition()
+
+const program = await system.forceCreateProgram(definition)
+const lifecycle = program.process.run({}, { signal })
+```
+
+The lower-level System API stays composable: use
+`system.forceCreateProgram(definition)` to replace one runtime Program, and
 `program.process.run(launch, { signal })` when one Process should live exactly
-as long as its asynchronous iterator.
+as long as its asynchronous iterator. Node also exports the runtime `Program`,
+`Process`, `Endpoint`, `Server`, and `Client` constructors; handles are
+canonical within one connected `System` and support `instanceof`.

package/dist/handle-registry.d.ts

@@ -0,0 +1,6 @@
+/** Canonical domain handles owned for exactly one connected System context. */
+export default class HandleRegistry {
+    private readonly handles;
+    obtain<Value extends object>(key: string, create: () => Value): Value;
+    clear(): void;
+}

package/dist/handle-registry.js

@@ -0,0 +1,13 @@
+/** Canonical domain handles owned for exactly one connected System context. */
+export default class HandleRegistry {
+    handles = new Map();
+    obtain(key, create) {
+        const existing = this.handles.get(key);
+        if (existing)
+            return existing;
+        const value = create();
+        this.handles.set(key, value);
+        return value;
+    }
+    clear() { this.handles.clear(); }
+}

package/dist/main.d.ts

@@ -1,4 +1,5 @@
 export { gatewayAddress } from "./address.js";
-export { System, type ProgramProcessRunEvent, type ProgramProcessRunOptions } from "./system.js";
+export { Client, ClientService, Endpoint, Process, Program, Server, ServerService, System, type ProgramProcessRunEvent, type ProgramProcessRunOptions } from "./system.js";
+export { Service, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
 export { resolveHome } from "./home.js";
-export { Project, type Manifest, type PackedProject, type ProjectMode, type ProjectOptions, type ProjectRunOptions, type ProjectRunResult } from "./project.js";
+export { Project, type Manifest, type PackedProject, type ProjectMode, type ProjectOptions, type ProjectRunOptions } from "./project.js";

package/dist/main.js

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

package/dist/project.d.ts

@@ -1,4 +1,4 @@
-import { type Config, type Exit, type ProgramDescription, type System as SystemContract, type SystemProcessEntity, type SystemProgramEntity } from "@phreshos/core";
+import { type Config, type ProgramDefinition, type System as SystemContract } from "@phreshos/core";
 /** One loaded Program authoring project rooted at an absolute directory. */
 export declare class Project {
     readonly directory: string;
@@ -6,26 +6,26 @@ export declare class Project {
     private constructor();
     /** Discover a project from cwd, a directory, or a phresh.config.ts path. */
     static open(source?: string): Promise<Project>;
-    /** Create a project from an already loaded definition. */
+    /** Create a Project from an already loaded authoring configuration. */
     static define(config: Config, options?: ProjectOptions): Project;
     /** Read this project's package manifest. */
     manifest(): Promise<Manifest>;
-    /** Resolve this authoring definition into one runnable Program description. */
-    description(mode: ProjectMode): ProgramDescription;
+    /** Resolve this authoring configuration into its production Program definition. */
+    productionDefinition(): ProgramDefinition;
+    /** Resolve this authoring configuration into its development Program definition. */
+    developmentDefinition(): ProgramDefinition;
+    private definition;
     /** Run the optional author-owned production build command. */
     build(): Promise<void>;
-    /** Build and run this project's production Program until its Process exits. */
-    start(system: SystemContract, options?: ProjectRunOptions): Promise<Readonly<{
-        process: SystemProcessEntity;
-        exit: Exit;
-    }>>;
-    /** Run this project's development Program and its optional Client server. */
-    dev(system: SystemContract, options?: ProjectRunOptions): Promise<Readonly<{
-        process: SystemProcessEntity;
-        exit: Exit;
-    }>>;
-    /** Build and install this project's production Program. */
-    install(system: SystemContract): Promise<SystemProgramEntity>;
+    /** Build this Project and return its production Process lifecycle generator. */
+    start(system: SystemContract, options?: ProjectRunOptions): Promise<AsyncGenerator<import("@phreshos/core").SystemProcessRunEvent, void, void>>;
+    /** Return this Project's development Process lifecycle generator. */
+    dev(system: SystemContract, options?: ProjectRunOptions): Promise<AsyncGenerator<import("@phreshos/core").SystemProcessRunEvent, void, void>>;
+    /** Build this Project and return its Program installation generator. */
+    install(system: SystemContract): Promise<AsyncGenerator<Readonly<{
+        stream: "stdout" | "stderr";
+        text: string;
+    }>, void, void>>;
     /** Build and package this Program into its canonical release shape. */
     pack(): Promise<PackedProject>;
     private run;
@@ -38,10 +38,6 @@ export interface ProjectRunOptions {
     options?: Record<string, string>;
     signal?: AbortSignal;
 }
-export type ProjectRunResult = Readonly<{
-    process: SystemProcessEntity;
-    exit: Exit;
-}>;
 export type PackedProject = Readonly<{
     archive: string;
     archivePath: string;

package/dist/project.js

@@ -1,4 +1,4 @@
-import { isRelativeValue, layers } from "@phreshos/core";
+import { isRelativeValue, layers, } from "@phreshos/core";
 import AdmZip from "adm-zip";
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
@@ -6,7 +6,6 @@ import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { delimiter, isAbsolute, join, normalize, resolve, sep } from "node:path";
 import { createJiti } from "jiti";
-import { assertAvailable, commandFailure, DevelopmentClient, waitForDevelopmentClient } from "./client-development.js";
 const configFile = "phresh.config.ts";
 /** One loaded Program authoring project rooted at an absolute directory. */
 export class Project {
@@ -30,7 +29,7 @@ export class Project {
             throw new Error(`${configFile} must export its config as the default export`);
         return new Project(config, resolve(path, ".."));
     }
-    /** Create a project from an already loaded definition. */
+    /** Create a Project from an already loaded authoring configuration. */
     static define(config, options = {}) {
         return new Project(config, options.directory ?? process.cwd());
     }
@@ -45,8 +44,15 @@ export class Project {
         }
         return manifest;
     }
-    /** Resolve this authoring definition into one runnable Program description. */
-    description(mode) {
+    /** Resolve this authoring configuration into its production Program definition. */
+    productionDefinition() {
+        return this.definition("production");
+    }
+    /** Resolve this authoring configuration into its development Program definition. */
+    developmentDefinition() {
+        return this.definition("development");
+    }
+    definition(mode) {
         const config = this.config;
         const server = serverHalf(config.server, mode);
         const client = clientHalf(config.client, mode);
@@ -102,30 +108,20 @@ export class Project {
             });
         });
     }
-    /** Build and run this project's production Program until its Process exits. */
+    /** Build this Project and return its production Process lifecycle generator. */
     async start(system, options = {}) {
         await this.build();
-        return await this.run(system, "production", options);
+        return await this.run(system, this.productionDefinition(), options);
     }
-    /** Run this project's development Program and its optional Client server. */
+    /** Return this Project's development Process lifecycle generator. */
     async dev(system, options = {}) {
-        return await this.run(system, "development", options);
+        return await this.run(system, this.developmentDefinition(), options);
     }
-    /** Build and install this project's production Program. */
+    /** Build this Project and return its Program installation generator. */
     async install(system) {
         await this.build();
-        const program = await system.forceCreateProgram(this.description("production"));
-        let installed = false;
-        try {
-            for await (const chunk of program.install())
-                write(chunk.stream, chunk.text);
-            installed = true;
-            return program;
-        }
-        finally {
-            if (!installed)
-                await forgetCurrent(program);
-        }
+        const program = await system.forceCreateProgram(this.productionDefinition());
+        return program.install();
     }
     /** Build and package this Program into its canonical release shape. */
     async pack() {
@@ -144,7 +140,7 @@ export class Project {
             file(zip, this.directory, this.config.icon, "icon.png", "Program icon");
         if (this.config.agent)
             file(zip, this.directory, this.config.agent, "agent.md", "Program agent documentation");
-        const declaration = Buffer.from(JSON.stringify(packageDescription(this.config, version), null, 4) + "\n");
+        const declaration = Buffer.from(JSON.stringify(packageDefinition(this.config, version), null, 4) + "\n");
         zip.addFile("program.json", declaration);
         const archive = `${this.config.identity}@${version}.zip`;
         const bytes = zip.toBuffer();
@@ -157,96 +153,18 @@ export class Project {
         writeFileSync(checksumPath, `${digest}  ${archive}\n`);
         return Object.freeze({ archive, archivePath, checksumPath, declarationPath, digest });
     }
-    async run(system, mode, options) {
-        const description = this.description(mode);
-        const development = mode === "development" && description.client && (description.client.start ?? true)
-            ? this.config.client?.development
-            : undefined;
-        const command = development?.startCommand;
-        if (command)
-            await assertAvailable(development.url);
-        const client = command ? new DevelopmentClient(command, this.directory) : undefined;
-        const controller = new AbortController();
-        const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
-        let program = null;
-        try {
-            if (development) {
-                for await (const event of waitForDevelopmentClient(development, client, signal))
-                    presentDevelopment(event);
-            }
-            program = await system.forceCreateProgram(description);
-            const run = program.process.run({ options: options.options ?? {} }, { signal });
-            const iterator = run[Symbol.asyncIterator]();
-            let lifecycle = iterator.next();
-            let developmentExit = client?.exited();
-            let developmentOutput = client?.outputAvailable();
-            let process = null;
-            let ending = null;
-            while (true) {
-                for (const event of client?.drain() ?? [])
-                    presentDevelopment(event);
-                const outcome = await Promise.race([
-                    lifecycle.then(result => ({ source: "system", result })),
-                    ...(developmentExit ? [developmentExit.then(result => ({ source: "client", result }))] : []),
-                    ...(developmentOutput ? [developmentOutput.then(() => ({ source: "output" }))] : [])
-                ]);
-                if (outcome.source === "output") {
-                    developmentOutput = client?.outputAvailable();
-                    continue;
-                }
-                if (outcome.source === "client") {
-                    developmentExit = undefined;
-                    if (!client?.endingWasRequested())
-                        throw commandFailure(outcome.result);
-                    continue;
-                }
-                if (outcome.result.done)
-                    break;
-                const event = outcome.result.value;
-                if (event.event === "started")
-                    process = event.process;
-                else if (event.event === "output")
-                    write(event.stream, event.text);
-                else
-                    ending = event.exit;
-                lifecycle = iterator.next();
-            }
-            if (!process || !ending)
-                throw new Error("The System ended the Program run without a complete Process lifecycle");
-            return Object.freeze({ process, exit: ending });
-        }
-        finally {
-            controller.abort(new Error("The Project run ended"));
-            await client?.stop();
-            if (program)
-                await forgetCurrent(program);
-        }
-    }
-}
-function presentDevelopment(event) {
-    if (event.event === "output")
-        write(event.stream === "err" ? "stderr" : "stdout", String(event.text ?? ""));
-}
-function write(stream, text) {
-    (stream === "stderr" ? process.stderr : process.stdout).write(text);
-}
-async function forgetCurrent(program) {
-    try {
-        await program.forget();
-    }
-    catch (error) {
-        if (error instanceof Error && error.message === "The Program represented by this handle does not exist")
-            return;
-        throw error;
+    async run(system, definition, options) {
+        const program = await system.forceCreateProgram(definition);
+        return program.process.run({ options: options.options ?? {} }, { signal: options.signal });
     }
 }
 function serverHalf(half, mode) {
     if (!half)
         return null;
-    const { development, startCommand, entryFile, ...description } = half;
+    const { development, startCommand, entryFile, ...declared } = half;
     if (mode === "production" || !development)
-        return { ...description, ...serverExecution({ startCommand, entryFile }) };
-    return { ...description, location: ".", ...serverExecution(development) };
+        return { ...declared, ...serverExecution({ startCommand, entryFile }) };
+    return { ...declared, location: ".", ...serverExecution(development) };
 }
 function serverExecution(server) {
     return server.startCommand !== undefined ? { startCommand: server.startCommand } : { entryFile: server.entryFile };
@@ -337,7 +255,7 @@ function commandEnvironment(directory) {
     const inherited = process.env[key];
     return { ...process.env, [key]: [join(directory, "node_modules", ".bin"), inherited].filter(Boolean).join(delimiter) };
 }
-function packageDescription(config, version) {
+function packageDefinition(config, version) {
     return {
         identity: config.identity,
         name: config.name,

package/dist/system.d.ts

@@ -1,4 +1,5 @@
-import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler, type ClientServiceChannel, type ProgramDescription, type ProgramCommandChunk, type ServerServiceChannel, type ServiceKey, type System as CoreSystem, type SystemProcessEntity, type SystemProcess, type SystemProgram, type SystemProgramEntity, type SystemUploads, type WritableAppearance } from "@phreshos/core";
+import { Client as CoreClient, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerService as CoreServerService, type ClientDeclaration, type EndpointDeclaration, type Launch, type LaunchClient, type Position, type ProgramDefinition, type ProgramCommandChunk, type ServiceKey, type Size, type System as CoreSystem, type SystemClientEntity, type SystemEndpointEntity, type SystemProcessEntity, type SystemProcess, type SystemProgram, type SystemProgramEntity, type SystemProgramProcessEvents, type SystemServerEntity, type SystemUploads, type WritableAppearance, type Window, type WindowEvents, type WindowGeometry } from "@phreshos/core";
+import Events from "./events.js";
 import { type TransportEvent } from "./transport.js";
 export type ProgramProcessRunOptions = Readonly<{
     signal?: AbortSignal;
@@ -18,6 +19,10 @@ interface SystemTransport {
     api(request: object, signal?: AbortSignal): Promise<unknown>;
     lifecycle(request: object, signal?: AbortSignal): AsyncGenerator<TransportEvent, void, void>;
 }
+declare const ProgramBase: new () => object;
+declare const ProcessBase: new () => object;
+declare const ServerBase: new () => object;
+declare const ClientBase: new () => object;
 /** One connected owner-local implementation of the shared System contract. */
 export declare class System implements CoreSystem {
     private readonly connection;
@@ -31,11 +36,12 @@ export declare class System implements CoreSystem {
     readonly transport: SystemTransport;
     private closed;
     private readonly lifetime;
+    private readonly handles;
     private constructor();
     /** Connect to the System selected by argument, environment, or owner default. */
     static connect(home?: string): Promise<System>;
     /** Atomically replace one runtime Program without touching its installed form. */
-    forceCreateProgram(source: ProgramDescription | string): Promise<SystemProgramEntity>;
+    forceCreateProgram(source: ProgramDefinition | string): Promise<SystemProgramEntity>;
     /** Close this owner connection and abort every attached operation it owns. */
     disconnect(): Promise<void>;
     service<EventsMap extends object = {}>(key: ServiceKey & {
@@ -44,27 +50,194 @@ export declare class System implements CoreSystem {
     service<EventsMap extends object = {}>(key: ServiceKey & {
         endpoint: "client";
     }): ClientService<EventsMap>;
+    programHandle(snapshot: ProgramSnapshot): ProgramHandle;
+    processHandle(snapshot: ProcessSnapshot): ProcessHandle;
     private signal;
     private requireConnected;
 }
-declare class ServerService<EventsMap extends object = {}> extends CoreServerServiceHandler<EventsMap> {
-    readonly name: string;
-    readonly channel: ServerServiceChannel<EventsMap>;
+interface ProgramHandle extends SystemProgramEntity {
+}
+declare class ProgramHandle extends ProgramBase {
+    private readonly system;
+    private readonly reference;
+    readonly identity: string;
+    readonly process: ProgramProcesses;
+    readonly startup: ProgramStartup;
+    private snapshot;
+    constructor(system: System, snapshot: ProgramSnapshot);
+    get name(): string;
+    get version(): string | null;
+    get description(): string | null;
+    get hasAgent(): boolean;
+    get server(): EndpointDeclaration | null;
+    get client(): ClientDeclaration | null;
+    update(snapshot: ProgramSnapshot): void;
+    agent(): Promise<string | null>;
+    installed(): Promise<boolean>;
+    install(): AsyncGenerator<Readonly<{
+        stream: "stdout" | "stderr";
+        text: string;
+    }>, void, void>;
+    uninstall(everything?: boolean): AsyncGenerator<Readonly<{
+        stream: "stdout" | "stderr";
+        text: string;
+    }>, void, void>;
+    forget(): Promise<void>;
+    address(): Readonly<{
+        identity: string;
+        reference: string;
+    }>;
+}
+declare class ProgramStartup {
+    private readonly system;
+    private readonly program;
+    constructor(system: System, program: ProgramHandle);
+    get(): Promise<Readonly<{
+        name?: string;
+        server?: boolean;
+        client?: boolean | LaunchClient;
+        options?: Readonly<Record<string, string>>;
+    }> | null>;
+    enable(launch?: Launch): Promise<void>;
+    disable(): Promise<void>;
+    private change;
+}
+declare class ProgramProcesses extends Events<SystemProgramProcessEvents> {
+    private readonly system;
+    private readonly program;
+    constructor(system: System, program: ProgramHandle);
+    list(): Promise<ProcessHandle[]>;
+    first(): Promise<ProcessHandle | null>;
+    last(): Promise<ProcessHandle | null>;
+    find(identityOrName: string): Promise<ProcessHandle | null>;
+    create(launch?: Launch): Promise<ProcessHandle>;
+    run(launch?: Launch, options?: ProgramProcessRunOptions): AsyncGenerator<ProgramProcessRunEvent, void, void>;
+    findOrCreate(launch: Launch & {
+        name: string;
+    }): Promise<ProcessHandle>;
+    exitAll(): Promise<string[]>;
+    private createExact;
+}
+interface ProcessHandle extends SystemProcessEntity {
+}
+declare class ProcessHandle extends ProcessBase {
+    private readonly system;
+    private readonly snapshot;
+    readonly identity: string;
+    readonly name: string | null;
+    readonly startedAt: Date;
+    readonly server: ServerEndpoint;
+    readonly client: ClientEndpoint;
+    constructor(system: System, snapshot: ProcessSnapshot);
+    program(): ProgramHandle;
+    exit(): Promise<void>;
+    exited(): Promise<boolean>;
+}
+interface ServerEndpoint extends SystemServerEntity {
+}
+declare class ServerEndpoint extends ServerBase {
+    private readonly system;
+    private readonly owner;
+    readonly endpoint: "server";
     private readonly base;
-    constructor(system: System, key: ServiceKey & {
-        endpoint: "server";
-    });
-    enabled(): Promise<boolean>;
+    constructor(system: System, owner: ProcessHandle);
+    process(): Promise<ProcessHandle>;
+    exists(): Promise<boolean>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    publish(event: string, payload?: unknown): void;
+    ask<Answer = unknown>(event: string, payload?: unknown): Promise<Answer>;
+    timeout(milliseconds: number): {
+        ask: <Answer = unknown>(event: string, payload?: unknown) => Promise<Answer>;
+    };
     waitReady(timeout?: number): Promise<void>;
+    service<EventsMap extends object = {}>(): Promise<ServerService<EventsMap> | null>;
 }
-declare class ClientService<EventsMap extends object = {}> extends CoreClientServiceHandler<EventsMap> {
-    readonly name: string;
-    readonly channel: ClientServiceChannel<EventsMap>;
+interface ClientEndpoint extends SystemClientEntity {
+}
+declare class ClientEndpoint extends ClientBase {
+    readonly endpoint: "client";
+    readonly window: SystemWindow;
     private readonly base;
-    constructor(system: System, key: ServiceKey & {
-        endpoint: "client";
-    });
-    enabled(): Promise<boolean>;
-    waitReady(timeout?: number): Promise<void>;
+    constructor(system: System, owner: ProcessHandle);
+    process(): Promise<ProcessHandle>;
+    exists(): Promise<boolean>;
+    start(overrides?: LaunchClient): Promise<void>;
+    stop(): Promise<void>;
+    publish(event: string, payload?: unknown): void;
+    service<EventsMap extends object = {}>(): Promise<ClientService<EventsMap> | null>;
+}
+declare class SystemWindow extends Events<WindowEvents> implements Window {
+    private readonly system;
+    private readonly process;
+    constructor(system: System, process: ProcessHandle);
+    title(): Promise<string>;
+    position(): Promise<Readonly<{
+        x: import("@phreshos/core").Value;
+        y: import("@phreshos/core").Value;
+    }>>;
+    size(): Promise<Readonly<{
+        width: import("@phreshos/core").Value;
+        height: import("@phreshos/core").Value;
+    }>>;
+    minimized(): Promise<boolean>;
+    front(): Promise<boolean>;
+    layer(): Promise<import("@phreshos/core").Layer>;
+    location(): Promise<string>;
+    move(position: Position): Promise<void>;
+    resize(size: Size): Promise<void>;
+    setGeometry(geometry: WindowGeometry): Promise<void>;
+    minimize(minimized?: boolean): Promise<void>;
+    changeTitle(title: string): Promise<void>;
+    raise(): Promise<void>;
+    private snapshot;
+    private change;
+}
+/** Node-SDK handle for a Service provided by a Server Endpoint. */
+export declare class ServerService<EventsMap extends object = {}> extends CoreServerService<EventsMap> {
+    protected constructor();
+}
+/** Node-SDK handle for a Service provided by a Client Endpoint. */
+export declare class ClientService<EventsMap extends object = {}> extends CoreClientService<EventsMap> {
+    protected constructor();
+}
+interface ProgramSnapshot {
+    reference: string;
+    identity: string;
+    name: string;
+    version: string | null;
+    description: string | null;
+    installed?: boolean;
+    hasAgent: boolean;
+    server: {
+        start: boolean;
+    } | null;
+    client: ClientDeclaration | null;
+}
+interface ProcessSnapshot {
+    reference: string;
+    identity: string;
+    name: string | null;
+    program: string;
+    programSnapshot?: ProgramSnapshot;
+    startedAt: string;
+    server: {
+        declared: boolean;
+        running: boolean;
+    };
+    client: {
+        declared: boolean;
+        running: boolean;
+    };
 }
+export type Program = SystemProgramEntity;
+export declare const Program: typeof CoreProgram;
+export type Process = SystemProcessEntity;
+export declare const Process: typeof CoreProcess;
+export type Endpoint<EventsMap extends object = {}> = SystemEndpointEntity<EventsMap>;
+export declare const Endpoint: typeof CoreEndpoint;
+export type Server<EventsMap extends object = {}> = SystemServerEntity<EventsMap>;
+export declare const Server: typeof CoreServer;
+export type Client<EventsMap extends object = {}> = SystemClientEntity<EventsMap>;
+export declare const Client: typeof CoreClient;
 export {};

package/dist/system.js

@@ -1,11 +1,16 @@
-import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler } from "@phreshos/core";
+import { Client as CoreClient, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerService as CoreServerService, isServiceKey } from "@phreshos/core";
 import { homedir } from "node:os";
 import { gatewayAddress } from "./address.js";
 import Events from "./events.js";
+import HandleRegistry from "./handle-registry.js";
 import { resolveHome } from "./home.js";
 import { filesystemStorage } from "./storage.js";
 import { openConnection, request, streamProgram } from "./transport.js";
 import Uploads from "./uploads.js";
+const ProgramBase = CoreProgram;
+const ProcessBase = CoreProcess;
+const ServerBase = CoreServer;
+const ClientBase = CoreClient;
 /** One connected owner-local implementation of the shared System contract. */
 export class System {
     connection;
@@ -19,6 +24,7 @@ export class System {
     transport;
     closed = false;
     lifetime = new AbortController();
+    handles = new HandleRegistry();
     constructor(home, address, connection) {
         this.connection = connection;
         this.home = home;
@@ -44,7 +50,7 @@ export class System {
         this.requireConnected();
         for await (const event of this.transport.lifecycle({ word: "force-create", program: source })) {
             if (event.event === "created")
-                return new ProgramHandle(this, required(event.program));
+                return this.programHandle(required(event.program));
         }
         throw new Error("The System did not confirm the created Program");
     }
@@ -55,12 +61,25 @@ export class System {
         this.closed = true;
         this.lifetime.abort(new Error("This System connection is closed"));
         this.connection.destroy();
+        this.handles.clear();
     }
     service(key) {
         this.requireConnected();
-        return key.endpoint === "server"
-            ? new ServerService(this, key)
-            : new ClientService(this, key);
+        if (!isServiceKey(key))
+            throw new Error("A complete service key is required");
+        const normalized = Object.freeze({ program: key.program, endpoint: key.endpoint, name: key.name });
+        const identity = JSON.stringify([normalized.program, normalized.endpoint, normalized.name]);
+        return this.handles.obtain(`service:${identity}`, () => normalized.endpoint === "server"
+            ? new ServerServiceHandle(this, normalized)
+            : new ClientServiceHandle(this, normalized));
+    }
+    programHandle(snapshot) {
+        const handle = this.handles.obtain(`program:${snapshot.reference}`, () => new ProgramHandle(this, snapshot));
+        handle.update(snapshot);
+        return handle;
+    }
+    processHandle(snapshot) {
+        return this.handles.obtain(`process:${snapshot.reference}`, () => new ProcessHandle(this, snapshot));
     }
     signal(signal) {
         this.requireConnected();
@@ -100,7 +119,7 @@ class ProgramRegistry extends Events {
                 operation: "list",
                 input: { installedOnly: onlyInstalled, limit: 100, offset }
             });
-            programs.push(...page.data.map(snapshot => new ProgramHandle(this.system, snapshot)));
+            programs.push(...page.data.map(snapshot => this.system.programHandle(snapshot)));
             offset += page.data.length;
             if (!page.truncated || !page.data.length)
                 return programs;
@@ -109,7 +128,7 @@ class ProgramRegistry extends Events {
     async find(identity) {
         try {
             const snapshot = await this.system.transport.control({ capability: "program", operation: "inspect", input: { program: identity } });
-            return new ProgramHandle(this.system, snapshot);
+            return this.system.programHandle(snapshot);
         }
         catch (error) {
             if (unknown(error, "Program"))
@@ -120,7 +139,7 @@ class ProgramRegistry extends Events {
     async create(source) {
         for await (const event of this.system.transport.lifecycle({ word: "create", program: source })) {
             if (event.event === "created")
-                return new ProgramHandle(this.system, required(event.program));
+                return this.system.programHandle(required(event.program));
         }
         throw new Error("The System did not confirm the created Program");
     }
@@ -128,46 +147,52 @@ class ProgramRegistry extends Events {
         const waited = value;
         if (waited.event === "uninstall") {
             const payload = waited.payload;
-            return { program: new ProgramHandle(this.system, required(payload.program)), everythingRemoved: payload.everythingRemoved === true };
+            return { program: this.system.programHandle(required(payload.program)), everythingRemoved: payload.everythingRemoved === true };
         }
-        return new ProgramHandle(this.system, required(waited.payload));
+        return this.system.programHandle(required(waited.payload));
     }
 }
-class ProgramHandle extends Events {
+class ProgramHandle extends ProgramBase {
     system;
     reference;
     identity;
-    name;
-    version;
-    description;
-    hasAgent;
-    server;
-    client;
     process;
     startup;
+    snapshot;
     constructor(system, snapshot) {
-        super(["forget", "uninstall"], (event, signal, timeout) => system.transport.control({
-            capability: "program", operation: "wait", input: { program: snapshot.identity, event, timeout }
-        }, signal).then(value => value.payload));
+        super();
         this.system = system;
+        this.snapshot = snapshot;
+        bindEvents(this, new Events(["forget", "uninstall"], (event, signal, timeout) => system.transport.control({
+            capability: "program", operation: "wait", input: { program: snapshot.identity, event, timeout }
+        }, signal).then(value => value.payload)));
         this.reference = snapshot.reference;
         this.identity = snapshot.identity;
-        this.name = snapshot.name;
-        this.version = snapshot.version;
-        this.description = snapshot.description;
-        this.hasAgent = snapshot.hasAgent;
-        this.server = snapshot.server ? Object.freeze({ start: snapshot.server.start }) : null;
-        this.client = snapshot.client ? Object.freeze({
-            start: snapshot.client.start,
-            title: snapshot.client.title,
-            size: snapshot.client.size,
-            position: snapshot.client.position,
-            layer: snapshot.client.layer,
-            minimize: snapshot.client.minimize
-        }) : null;
         this.process = new ProgramProcesses(system, this);
         this.startup = new ProgramStartup(system, this);
     }
+    get name() { return this.snapshot.name; }
+    get version() { return this.snapshot.version; }
+    get description() { return this.snapshot.description; }
+    get hasAgent() { return this.snapshot.hasAgent; }
+    get server() {
+        return this.snapshot.server ? Object.freeze({ start: this.snapshot.server.start }) : null;
+    }
+    get client() {
+        return this.snapshot.client ? Object.freeze({
+            start: this.snapshot.client.start,
+            title: this.snapshot.client.title,
+            size: this.snapshot.client.size,
+            position: this.snapshot.client.position,
+            layer: this.snapshot.client.layer,
+            minimize: this.snapshot.client.minimize
+        }) : null;
+    }
+    update(snapshot) {
+        if (snapshot.reference !== this.reference)
+            throw new Error("A Program handle cannot become another Program");
+        this.snapshot = snapshot;
+    }
     async agent() {
         if (!this.hasAgent)
             return null;
@@ -246,7 +271,7 @@ class ProgramProcesses extends Events {
             launch
         }, options.signal)) {
             if (event.event === "started") {
-                process = new ProcessHandle(this.system, required(event.process));
+                process = this.system.processHandle(required(event.process));
                 yield Object.freeze({ event: "started", process });
             }
             else if (event.event === "output") {
@@ -289,7 +314,7 @@ class ProgramProcesses extends Events {
     async createExact(word, launch) {
         for await (const event of this.system.transport.lifecycle({ word, handle: this.program.address(), launch })) {
             if (event.event === "createdProcess")
-                return new ProcessHandle(this.system, required(event.process));
+                return this.system.processHandle(required(event.process));
         }
         throw new Error("The System did not confirm the created Process");
     }
@@ -306,7 +331,7 @@ class ProcessRegistry extends Events {
     async find(identity) {
         try {
             const snapshot = await this.system.transport.control({ capability: "process", operation: "inspect", input: { process: identity } });
-            return new ProcessHandle(this.system, snapshot);
+            return this.system.processHandle(snapshot);
         }
         catch (error) {
             if (unknown(error, "Process"))
@@ -315,7 +340,7 @@ class ProcessRegistry extends Events {
         }
     }
 }
-class ProcessHandle extends Events {
+class ProcessHandle extends ProcessBase {
     system;
     snapshot;
     identity;
@@ -324,26 +349,28 @@ class ProcessHandle extends Events {
     server;
     client;
     constructor(system, snapshot) {
-        super(["endpointStart", "endpointStop", "exit"], (event, signal, timeout) => system.transport.control({
-            capability: "process", operation: "wait", input: { process: snapshot.identity, event, timeout }
-        }, signal).then(value => processEvent(system, value)));
+        super();
         this.system = system;
         this.snapshot = snapshot;
+        bindEvents(this, new Events(["endpointStart", "endpointStop", "exit"], (event, signal, timeout) => system.transport.control({
+            capability: "process", operation: "wait", input: { process: snapshot.identity, event, timeout }
+        }, signal).then(value => processEvent(system, value))));
         this.identity = snapshot.identity;
         this.name = snapshot.name;
         this.startedAt = new Date(snapshot.startedAt);
         this.server = new ServerEndpoint(system, this);
         this.client = new ClientEndpoint(system, this);
     }
-    program() { return new ProgramHandle(this.system, required(this.snapshot.programSnapshot, this.snapshot.program)); }
+    program() { return this.system.programHandle(required(this.snapshot.programSnapshot, this.snapshot.program)); }
     async exit() {
         await this.system.transport.control({ capability: "process", operation: "exit", input: { process: this.identity } });
     }
     async exited() { return await this.system.process.find(this.identity) === null; }
 }
-class EndpointHandle extends Events {
+class EndpointOperations extends Events {
     system;
     owner;
+    endpoint;
     constructor(system, owner, endpoint) {
         super([], (event, signal, timeout) => event === null
             ? system.transport.api({ capability: "endpoint", operation: "wait", process: owner.identity, endpoint, event, timeout }, signal)
@@ -352,13 +379,14 @@ class EndpointHandle extends Events {
             }, signal).then(value => value.payload));
         this.system = system;
         this.owner = owner;
+        this.endpoint = endpoint;
     }
     process() { return Promise.resolve(this.owner); }
     async exists() {
         const value = await this.inspect();
         return value.running;
     }
-    async start() { await this.operation("start"); }
+    async start(client) { await this.operation("start", client); }
     async stop() { await this.operation("stop"); }
     async service() {
         const key = await this.system.transport.api({ capability: "endpoint", operation: "service", process: this.owner.identity, endpoint: this.endpoint });
@@ -380,9 +408,23 @@ class EndpointHandle extends Events {
             } });
     }
 }
-class ServerEndpoint extends EndpointHandle {
+class ServerEndpoint extends ServerBase {
+    system;
+    owner;
     endpoint = "server";
-    constructor(system, owner) { super(system, owner, "server"); }
+    base;
+    constructor(system, owner) {
+        super();
+        this.system = system;
+        this.owner = owner;
+        this.base = new EndpointOperations(system, owner, "server");
+        bindEvents(this, this.base);
+    }
+    process() { return this.base.process(); }
+    exists() { return this.base.exists(); }
+    start() { return this.base.start(); }
+    stop() { return this.base.stop(); }
+    publish(event, payload) { return this.base.publish(event, payload); }
     async ask(event, payload) {
         return await this.system.transport.control({ capability: "endpoint", operation: "ask", input: {
                 process: this.owner.identity, endpoint: "server", event, payload
@@ -397,19 +439,26 @@ class ServerEndpoint extends EndpointHandle {
         await this.system.transport.control({ capability: "endpoint", operation: "waitReady", input: { process: this.owner.identity, endpoint: "server", timeout } });
     }
     async service() {
-        return await super.service();
+        return await this.base.service();
     }
 }
-class ClientEndpoint extends EndpointHandle {
+class ClientEndpoint extends ClientBase {
     endpoint = "client";
     window;
+    base;
     constructor(system, owner) {
-        super(system, owner, "client");
+        super();
+        this.base = new EndpointOperations(system, owner, "client");
+        bindEvents(this, this.base);
         this.window = new SystemWindow(system, owner);
     }
-    async start(overrides) { await this.operation("start", overrides); }
+    process() { return this.base.process(); }
+    exists() { return this.base.exists(); }
+    start(overrides) { return this.base.start(overrides); }
+    stop() { return this.base.stop(); }
+    publish(event, payload) { return this.base.publish(event, payload); }
     async service() {
-        return await super.service();
+        return await this.base.service();
     }
 }
 class SystemWindow extends Events {
@@ -457,7 +506,11 @@ class ServiceBase extends Events {
     async enabled() { return await this.system.transport.api({ capability: "service", operation: "enabled", key: this.key }); }
     async waitReady(timeout) { await this.system.transport.api({ capability: "service", operation: "waitReady", key: this.key, timeout }); }
 }
-class ServerService extends CoreServerServiceHandler {
+/** Node-SDK handle for a Service provided by a Server Endpoint. */
+export class ServerService extends CoreServerService {
+    constructor() { super(); }
+}
+class ServerServiceHandle extends ServerService {
     name;
     channel;
     base;
@@ -471,7 +524,11 @@ class ServerService extends CoreServerServiceHandler {
     enabled() { return this.base.enabled(); }
     waitReady(timeout) { return this.base.waitReady(timeout); }
 }
-class ClientService extends CoreClientServiceHandler {
+/** Node-SDK handle for a Service provided by a Client Endpoint. */
+export class ClientService extends CoreClientService {
+    constructor() { super(); }
+}
+class ClientServiceHandle extends ClientService {
     name;
     channel;
     base;
@@ -512,7 +569,7 @@ async function listProcesses(system, program) {
     let offset = 0;
     while (true) {
         const page = await system.transport.control({ capability: "process", operation: "list", input: { program, limit: 100, offset } });
-        processes.push(...page.data.map(snapshot => new ProcessHandle(system, snapshot)));
+        processes.push(...page.data.map(snapshot => system.processHandle(snapshot)));
         offset += page.data.length;
         if (!page.truncated || !page.data.length)
             return processes;
@@ -532,19 +589,22 @@ function processEvent(system, value) {
     const payload = waited.payload;
     if (waited.event === "exit" && payload)
         return {
-            process: new ProcessHandle(system, required(payload.processSnapshot, String(payload.process ?? ""))),
+            process: system.processHandle(required(payload.processSnapshot, String(payload.process ?? ""))),
             status: payload.status,
             code: payload.code,
             signal: payload.signal
         };
     if ((waited.event === "endpointStart" || waited.event === "endpointStop") && payload?.processSnapshot) {
-        const process = new ProcessHandle(system, payload.processSnapshot);
+        const process = system.processHandle(payload.processSnapshot);
         return payload.endpoint === "client" ? process.client : process.server;
     }
     if (payload && typeof payload.identity === "string")
-        return new ProcessHandle(system, payload);
+        return system.processHandle(payload);
     return payload;
 }
+function bindEvents(target, events) {
+    Object.assign(target, eventsOf(events));
+}
 function eventsOf(events) {
     return {
         subscribe: events.subscribe,
@@ -560,3 +620,8 @@ function required(value, identity = "") {
         return value;
     throw new Error(`The System returned no ${identity ? `${identity} ` : ""}snapshot`);
 }
+export const Program = CoreProgram;
+export const Process = CoreProcess;
+export const Endpoint = CoreEndpoint;
+export const Server = CoreServer;
+export const Client = CoreClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/node",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Node.js access to PhreshOS and Program projects.",
   "type": "module",
   "main": "dist/main.js",
@@ -32,7 +32,7 @@
     "prepack": "node --run build"
   },
   "dependencies": {
-    "@phreshos/core": "^0.1.22",
+    "@phreshos/core": "^0.1.24",
     "adm-zip": "^0.6.0",
     "jiti": "^2.7.0"
   },

package/dist/client-development.d.ts

@@ -1,29 +0,0 @@
-import type { ClientDevelopment } from "@phreshos/core";
-import type { TransportEvent } from "./transport.js";
-/** One Client development server owned by a Project development run. */
-export declare class DevelopmentClient {
-    private readonly child;
-    private readonly output;
-    private stopped;
-    private result;
-    private outputWaiter;
-    private readonly completion;
-    constructor(command: string, directory: string);
-    drain(): TransportEvent[];
-    exited(): Promise<CommandExit>;
-    exitResult(): CommandExit | null;
-    outputAvailable(): Promise<void>;
-    stop(): Promise<void>;
-    endingWasRequested(): boolean;
-    private push;
-}
-/** Refuse to claim a URL already served by an unrelated process. */
-export declare function assertAvailable(url: string): Promise<void>;
-/** Wait until a development Client can be loaded by a sandboxed Program iframe. */
-export declare function waitForDevelopmentClient(config: ClientDevelopment, client?: DevelopmentClient, signal?: AbortSignal): AsyncGenerator<TransportEvent, void, unknown>;
-export declare function commandFailure(exit: CommandExit): Error;
-export interface CommandExit {
-    code: number | null;
-    signal: NodeJS.Signals | null;
-    error: Error | null;
-}

package/dist/client-development.js

@@ -1,199 +0,0 @@
-import { spawn } from "node:child_process";
-import { connect } from "node:net";
-import { delimiter, join } from "node:path";
-const readinessTimeout = 15_000;
-const pollingInterval = 200;
-const reportingInterval = 2_000;
-const sandboxedClientOrigin = "null";
-/** One Client development server owned by a Project development run. */
-export class DevelopmentClient {
-    child;
-    output = [];
-    stopped = false;
-    result = null;
-    outputWaiter = null;
-    completion;
-    constructor(command, directory) {
-        this.child = spawn(command, {
-            cwd: directory,
-            env: commandEnvironment(directory),
-            shell: true,
-            stdio: ["ignore", "pipe", "pipe"],
-            detached: true
-        });
-        this.child.stdout?.on("data", chunk => this.push(outputEvent("out", chunk)));
-        this.child.stderr?.on("data", chunk => this.push(outputEvent("err", chunk)));
-        this.completion = new Promise(resolve => {
-            let settled = false;
-            const finish = (exit) => {
-                if (settled)
-                    return;
-                settled = true;
-                this.result = exit;
-                this.outputWaiter?.();
-                this.outputWaiter = null;
-                resolve(exit);
-            };
-            this.child.once("error", error => finish({ code: null, signal: null, error }));
-            this.child.once("exit", (code, signal) => finish({ code, signal, error: null }));
-        });
-    }
-    drain() { return this.output.splice(0); }
-    exited() { return this.completion; }
-    exitResult() { return this.result; }
-    outputAvailable() {
-        if (this.output.length || this.result)
-            return Promise.resolve();
-        return new Promise(resolve => { this.outputWaiter = resolve; });
-    }
-    async stop() {
-        if (this.stopped)
-            return;
-        this.stopped = true;
-        if (!running(this.child))
-            return;
-        terminate(this.child, "SIGTERM");
-        await waitUntilStopped(this.child, 1_000);
-        if (running(this.child))
-            terminate(this.child, "SIGKILL");
-        await waitUntilStopped(this.child, 1_000);
-    }
-    endingWasRequested() { return this.stopped; }
-    push(event) {
-        this.output.push(event);
-        this.outputWaiter?.();
-        this.outputWaiter = null;
-    }
-}
-/** Refuse to claim a URL already served by an unrelated process. */
-export async function assertAvailable(url) {
-    if (!await occupied(url))
-        return;
-    throw new Error(`Client development URL is already in use: ${url}`);
-}
-/** Wait until a development Client can be loaded by a sandboxed Program iframe. */
-export async function* waitForDevelopmentClient(config, client, signal) {
-    const began = Date.now();
-    let nextReport = began + reportingInterval;
-    while (Date.now() - began < readinessTimeout) {
-        throwIfAborted(signal);
-        for (const event of client?.drain() ?? [])
-            yield event;
-        const exit = client?.exitResult();
-        if (exit && !client?.endingWasRequested())
-            throw commandFailure(exit);
-        const availability = await inspect(config.url, readinessTimeout - (Date.now() - began));
-        if (availability === "ready")
-            return;
-        if (availability === "cors-blocked") {
-            throw new Error([
-                `Client development URL responded, but does not allow the sandboxed Client origin: ${config.url}`,
-                "Enable CORS so the response includes Access-Control-Allow-Origin: *."
-            ].join("\n"));
-        }
-        const now = Date.now();
-        if (now >= nextReport) {
-            yield { event: "waiting", subject: "client", url: config.url };
-            while (nextReport <= now)
-                nextReport += reportingInterval;
-        }
-        await pause(Math.min(pollingInterval, readinessTimeout - (now - began)), signal);
-    }
-    throw new Error(`Client development URL did not respond within 15 seconds: ${config.url}`);
-}
-export function commandFailure(exit) {
-    if (exit.error)
-        return new Error(`Client development command failed: ${exit.error.message}`);
-    if (exit.signal)
-        return new Error(`Client development command ended on ${exit.signal}`);
-    return new Error(`Client development command exited with ${exit.code ?? 0}`);
-}
-function outputEvent(stream, chunk) {
-    return { event: "output", source: "client-development", stream, text: String(chunk) };
-}
-function commandEnvironment(directory) {
-    const key = Object.keys(process.env).find(name => name.toLowerCase() === "path") ?? "PATH";
-    const inherited = process.env[key];
-    return { ...process.env, [key]: [join(directory, "node_modules", ".bin"), inherited].filter(Boolean).join(delimiter) };
-}
-async function occupied(url) {
-    const location = new URL(url);
-    const port = Number(location.port || (location.protocol === "https:" ? 443 : 80));
-    return await new Promise(resolve => {
-        const socket = connect({ host: location.hostname, port });
-        let done = false;
-        const finish = (value) => {
-            if (done)
-                return;
-            done = true;
-            socket.destroy();
-            resolve(value);
-        };
-        socket.setTimeout(500);
-        socket.once("connect", () => finish(true));
-        socket.once("error", () => finish(false));
-        socket.once("timeout", () => finish(false));
-    });
-}
-async function inspect(url, remaining) {
-    try {
-        const response = await fetch(url, {
-            headers: { origin: sandboxedClientOrigin },
-            signal: AbortSignal.timeout(Math.max(1, Math.min(500, remaining)))
-        });
-        const allowedOrigin = response.headers.get("access-control-allow-origin")?.trim();
-        await response.body?.cancel();
-        return allowedOrigin === "*" || allowedOrigin === sandboxedClientOrigin ? "ready" : "cors-blocked";
-    }
-    catch {
-        return "unavailable";
-    }
-}
-function terminate(child, signal) {
-    if (!child.pid)
-        return;
-    try {
-        process.kill(-child.pid, signal);
-    }
-    catch {
-        child.kill(signal);
-    }
-}
-function running(child) {
-    if (!child.pid)
-        return false;
-    try {
-        process.kill(-child.pid, 0);
-        return true;
-    }
-    catch {
-        return child.exitCode === null && child.signalCode === null;
-    }
-}
-async function waitUntilStopped(child, milliseconds) {
-    const deadline = Date.now() + milliseconds;
-    while (running(child) && Date.now() < deadline)
-        await new Promise(resolve => setTimeout(resolve, 20));
-}
-function pause(milliseconds, signal) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(finish, Math.max(0, milliseconds));
-        const cancel = () => {
-            cleanup();
-            reject(signal?.reason instanceof Error ? signal.reason : new Error("The operation was cancelled"));
-        };
-        const cleanup = () => {
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", cancel);
-        };
-        function finish() { cleanup(); resolve(); }
-        if (signal?.aborted)
-            cancel();
-        else
-            signal?.addEventListener("abort", cancel, { once: true });
-    });
-}
-function throwIfAborted(signal) {
-    if (signal?.aborted)
-        throw signal.reason instanceof Error ? signal.reason : new Error("The operation was cancelled");
-}