@phreshos/node 0.1.0 → 0.1.1

package/README.md

@@ -3,37 +3,39 @@
 The Node.js interface for a running PhreshOS System and local Program projects.
 
 ```ts
-import { Gateway, Project } from "@phreshos/node"
+import { Project, System } from "@phreshos/node"
 
 const project = await Project.open()
-const gateway = await Gateway.open()
+const system = await System.connect()
 
-for await (const event of gateway.install(project)) {
-  // installation progress
-}
+await project.install(system)
 
-// The complete transport-neutral System contract used by Server Programs.
-const programs = await gateway.system.program.list()
+// This is the same transport-neutral System contract used by Server Programs.
+const programs = await system.program.list()
 
-await gateway.close()
+await system.disconnect()
 ```
 
 `Project.open()` discovers `phresh.config.ts` from the current working
-directory by default. `Gateway.open()` resolves its home from an explicit
+directory by default. `System.connect()` resolves its home from an explicit
 argument, then `PHRESHOS_HOME`, then the current user's `.phreshos` directory.
 
 Project operations remain available without duplicating CLI logic:
 
 ```ts
 const project = await Project.open() // process.cwd()
-const gateway = await Gateway.open()
+const system = await System.connect()
 
 await project.pack()
-for await (const event of gateway.start(project)) { /* production run */ }
-for await (const event of gateway.dev(project)) { /* development run */ }
-for await (const event of gateway.install(project)) { /* installation */ }
+await project.start(system, { signal })
+await project.dev(system, { signal })
+await project.install(system)
+
+await system.disconnect()
 ```
 
-`start`, `dev`, and `install` expose ordered asynchronous event streams. The
-CLI only interprets arguments and presents those events; it does not implement
-a second Project or Gateway lifecycle.
+`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
+`program.process.run(launch, { signal })` when one Process should live exactly
+as long as its asynchronous iterator.

package/dist/client-development.d.ts

@@ -1,6 +1,6 @@
 import type { ClientDevelopment } from "@phreshos/core";
-import type { GatewayEvent } from "./transport.js";
-/** One client development server owned by a Gateway development run. */
+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;
@@ -9,7 +9,7 @@ export declare class DevelopmentClient {
     private outputWaiter;
     private readonly completion;
     constructor(command: string, directory: string);
-    drain(): GatewayEvent[];
+    drain(): TransportEvent[];
     exited(): Promise<CommandExit>;
     exitResult(): CommandExit | null;
     outputAvailable(): Promise<void>;
@@ -20,7 +20,7 @@ export declare class DevelopmentClient {
 /** 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<GatewayEvent, void, unknown>;
+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;

package/dist/client-development.js

@@ -5,7 +5,7 @@ const readinessTimeout = 15_000;
 const pollingInterval = 200;
 const reportingInterval = 2_000;
 const sandboxedClientOrigin = "null";
-/** One client development server owned by a Gateway development run. */
+/** One Client development server owned by a Project development run. */
 export class DevelopmentClient {
     child;
     output = [];

package/dist/home.d.ts

@@ -1,2 +1,2 @@
-/** Resolve the absolute PhreshOS home selected for one Gateway. */
+/** Resolve the absolute PhreshOS home selected for one System connection. */
 export declare function resolveHome(home?: string, environment?: NodeJS.ProcessEnv, userHome?: string): string;

package/dist/home.js

@@ -1,7 +1,7 @@
 import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join, normalize } from "node:path";
-/** Resolve the absolute PhreshOS home selected for one Gateway. */
+/** Resolve the absolute PhreshOS home selected for one System connection. */
 export function resolveHome(home, environment = process.env, userHome = homedir()) {
     const selected = home ?? environment.PHRESHOS_HOME;
     if (selected === undefined)

package/dist/main.d.ts

@@ -1,5 +1,4 @@
 export { gatewayAddress } from "./address.js";
-export { Gateway, type InstallOptions, type RunOptions, type UninstallOptions } from "./gateway.js";
+export { System, type ProgramProcessRunEvent, type ProgramProcessRunOptions } from "./system.js";
 export { resolveHome } from "./home.js";
-export { Project, type Manifest, type PackedProject, type ProjectMode, type ProjectOptions } from "./project.js";
-export { type GatewayEvent } from "./transport.js";
+export { Project, type Manifest, type PackedProject, type ProjectMode, type ProjectOptions, type ProjectRunOptions, type ProjectRunResult } from "./project.js";

package/dist/main.js

@@ -1,5 +1,4 @@
 export { gatewayAddress } from "./address.js";
-export { Gateway } from "./gateway.js";
+export { System } from "./system.js";
 export { resolveHome } from "./home.js";
 export { Project } from "./project.js";
-export {} from "./transport.js";

package/dist/project.d.ts

@@ -1,4 +1,4 @@
-import { type Config, type ProgramDescription } from "@phreshos/core";
+import { type Config, type Exit, type ProgramDescription, type System as SystemContract, type SystemProcessEntity, type SystemProgramEntity } from "@phreshos/core";
 /** One loaded Program authoring project rooted at an absolute directory. */
 export declare class Project {
     readonly directory: string;
@@ -14,13 +14,34 @@ export declare class Project {
     description(mode: ProjectMode): ProgramDescription;
     /** 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 and package this Program into its canonical release shape. */
     pack(): Promise<PackedProject>;
+    private run;
 }
 export type ProjectMode = "production" | "development";
 export interface ProjectOptions {
     directory?: string;
 }
+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

@@ -6,6 +6,7 @@ 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 {
@@ -101,6 +102,31 @@ export class Project {
             });
         });
     }
+    /** Build and run this project's production Program until its Process exits. */
+    async start(system, options = {}) {
+        await this.build();
+        return await this.run(system, "production", options);
+    }
+    /** Run this project's development Program and its optional Client server. */
+    async dev(system, options = {}) {
+        return await this.run(system, "development", options);
+    }
+    /** Build and install this project's production Program. */
+    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);
+        }
+    }
     /** Build and package this Program into its canonical release shape. */
     async pack() {
         await this.build();
@@ -131,6 +157,88 @@ 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;
+    }
 }
 function serverHalf(half, mode) {
     if (!half)

package/dist/system.d.ts

@@ -1,9 +1,70 @@
-import { type System } from "@phreshos/core";
-import type { GatewayEvent } from "./transport.js";
-export interface SystemTransport {
+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 { type TransportEvent } from "./transport.js";
+export type ProgramProcessRunOptions = Readonly<{
+    signal?: AbortSignal;
+}>;
+export type ProgramProcessRunEvent = Readonly<{
+    event: "started";
+    process: SystemProcessEntity;
+}> | (Readonly<{
+    event: "output";
+}> & ProgramCommandChunk) | Readonly<{
+    event: "exited";
+    process: SystemProcessEntity;
+    exit: import("@phreshos/core").Exit;
+}>;
+interface SystemTransport {
     control(request: object, signal?: AbortSignal): Promise<unknown>;
     api(request: object, signal?: AbortSignal): Promise<unknown>;
-    lifecycle(request: object, signal?: AbortSignal): AsyncGenerator<GatewayEvent, void, void>;
+    lifecycle(request: object, signal?: AbortSignal): AsyncGenerator<TransportEvent, void, void>;
 }
-/** Build the exact shared System contract over an owner-local Gateway transport. */
-export declare function gatewaySystem(transport: SystemTransport): System;
+/** One connected owner-local implementation of the shared System contract. */
+export declare class System implements CoreSystem {
+    private readonly connection;
+    readonly home: string;
+    readonly address: string;
+    readonly storage: import("@phreshos/core").Storage;
+    readonly appearance: WritableAppearance;
+    readonly program: SystemProgram;
+    readonly process: SystemProcess;
+    readonly uploads: SystemUploads;
+    readonly transport: SystemTransport;
+    private closed;
+    private readonly lifetime;
+    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>;
+    /** Close this owner connection and abort every attached operation it owns. */
+    disconnect(): Promise<void>;
+    service<EventsMap extends object = {}>(key: ServiceKey & {
+        endpoint: "server";
+    }): ServerService<EventsMap>;
+    service<EventsMap extends object = {}>(key: ServiceKey & {
+        endpoint: "client";
+    }): ClientService<EventsMap>;
+    private signal;
+    private requireConnected;
+}
+declare class ServerService<EventsMap extends object = {}> extends CoreServerServiceHandler<EventsMap> {
+    readonly name: string;
+    readonly channel: ServerServiceChannel<EventsMap>;
+    private readonly base;
+    constructor(system: System, key: ServiceKey & {
+        endpoint: "server";
+    });
+    enabled(): Promise<boolean>;
+    waitReady(timeout?: number): Promise<void>;
+}
+declare class ClientService<EventsMap extends object = {}> extends CoreClientServiceHandler<EventsMap> {
+    readonly name: string;
+    readonly channel: ClientServiceChannel<EventsMap>;
+    private readonly base;
+    constructor(system: System, key: ServiceKey & {
+        endpoint: "client";
+    });
+    enabled(): Promise<boolean>;
+    waitReady(timeout?: number): Promise<void>;
+}
+export {};

package/dist/system.js

@@ -1,33 +1,77 @@
 import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler } from "@phreshos/core";
 import { homedir } from "node:os";
+import { gatewayAddress } from "./address.js";
 import Events from "./events.js";
+import { resolveHome } from "./home.js";
 import { filesystemStorage } from "./storage.js";
+import { openConnection, request, streamProgram } from "./transport.js";
 import Uploads from "./uploads.js";
-/** Build the exact shared System contract over an owner-local Gateway transport. */
-export function gatewaySystem(transport) {
-    return new GatewaySystem(transport);
-}
-class GatewaySystem {
-    transport;
+/** One connected owner-local implementation of the shared System contract. */
+export class System {
+    connection;
+    home;
+    address;
     storage = filesystemStorage(homedir(), "the native home directory");
     appearance;
     program;
     process;
     uploads;
-    constructor(transport) {
-        this.transport = transport;
-        this.appearance = new GatewayAppearance(transport);
+    transport;
+    closed = false;
+    lifetime = new AbortController();
+    constructor(home, address, connection) {
+        this.connection = connection;
+        this.home = home;
+        this.address = address;
+        this.transport = {
+            control: (value, signal) => request(address, "system", value, this.signal(signal)),
+            api: (value, signal) => request(address, "api", value, this.signal(signal)),
+            lifecycle: (value, signal) => streamProgram(address, value, this.signal(signal))
+        };
+        this.appearance = new SystemAppearance(this.transport);
         this.program = new ProgramRegistry(this);
         this.process = new ProcessRegistry(this);
-        this.uploads = new Uploads(request => transport.api(request));
+        this.uploads = new Uploads(value => this.transport.api(value));
+    }
+    /** Connect to the System selected by argument, environment, or owner default. */
+    static async connect(home) {
+        const resolved = resolveHome(home);
+        const address = gatewayAddress(resolved);
+        return new System(resolved, address, await openConnection(address));
+    }
+    /** Atomically replace one runtime Program without touching its installed form. */
+    async forceCreateProgram(source) {
+        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));
+        }
+        throw new Error("The System did not confirm the created Program");
+    }
+    /** Close this owner connection and abort every attached operation it owns. */
+    async disconnect() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.lifetime.abort(new Error("This System connection is closed"));
+        this.connection.destroy();
     }
     service(key) {
+        this.requireConnected();
         return key.endpoint === "server"
             ? new ServerService(this, key)
             : new ClientService(this, key);
     }
+    signal(signal) {
+        this.requireConnected();
+        return signal ? AbortSignal.any([signal, this.lifetime.signal]) : this.lifetime.signal;
+    }
+    requireConnected() {
+        if (this.closed)
+            throw new Error("This System connection is closed");
+    }
 }
-class GatewayAppearance extends Events {
+class SystemAppearance extends Events {
     transport;
     constructor(transport) {
         super(["change"], (_event, signal) => transport.api({ capability: "appearance", operation: "wait" }, signal));
@@ -74,17 +118,11 @@ class ProgramRegistry extends Events {
         }
     }
     async create(source) {
-        let identity = null;
         for await (const event of this.system.transport.lifecycle({ word: "create", program: source })) {
             if (event.event === "created")
-                identity = String(event.identity);
+                return new ProgramHandle(this.system, required(event.program));
         }
-        if (!identity)
-            throw new Error("The System did not confirm the created Program");
-        const program = await this.find(identity);
-        if (!program)
-            throw new Error("The created Program cannot be found");
-        return program;
+        throw new Error("The System did not confirm the created Program");
     }
     async event(value) {
         const waited = value;
@@ -97,6 +135,7 @@ class ProgramRegistry extends Events {
 }
 class ProgramHandle extends Events {
     system;
+    reference;
     identity;
     name;
     version;
@@ -105,11 +144,13 @@ class ProgramHandle extends Events {
     server;
     client;
     process;
+    startup;
     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));
         this.system = system;
+        this.reference = snapshot.reference;
         this.identity = snapshot.identity;
         this.name = snapshot.name;
         this.version = snapshot.version;
@@ -125,6 +166,7 @@ class ProgramHandle extends Events {
             minimize: snapshot.client.minimize
         }) : null;
         this.process = new ProgramProcesses(system, this);
+        this.startup = new ProgramStartup(system, this);
     }
     async agent() {
         if (!this.hasAgent)
@@ -133,15 +175,49 @@ class ProgramHandle extends Events {
         return typeof value.content === "string" ? value.content : null;
     }
     async installed() {
-        const value = await this.system.transport.control({ capability: "program", operation: "inspect", input: { program: this.identity } });
-        if (typeof value.installed !== "boolean")
-            throw new Error("The System returned no Program installation state");
-        return value.installed;
+        for await (const event of this.system.transport.lifecycle({ word: "installed", handle: this.address() })) {
+            if (event.event === "installedState")
+                return event.installed === true;
+        }
+        throw new Error("The System returned no Program installation state");
     }
-    install() { return command(this.system, { word: "install-existing", identity: this.identity }); }
-    uninstall(everything = false) { return command(this.system, { word: "uninstall-existing", identity: this.identity, everything }); }
+    install() { return command(this.system, { word: "install-existing", handle: this.address() }); }
+    uninstall(everything = false) { return command(this.system, { word: "uninstall-existing", handle: this.address(), everything }); }
     async forget() {
-        for await (const _event of this.system.transport.lifecycle({ word: "forget", identity: this.identity })) { /* consume completion */ }
+        for await (const _event of this.system.transport.lifecycle({ word: "forget", handle: this.address() })) { /* consume completion */ }
+    }
+    address() { return Object.freeze({ identity: this.identity, reference: this.reference }); }
+}
+class ProgramStartup {
+    system;
+    program;
+    constructor(system, program) {
+        this.system = system;
+        this.program = program;
+    }
+    async get() {
+        for await (const event of this.system.transport.lifecycle({
+            word: "startup", handle: this.program.address(), operation: "get"
+        })) {
+            if (event.event === "startup")
+                return event.launch;
+        }
+        throw new Error("The System returned no Program startup state");
+    }
+    async enable(launch = {}) {
+        await this.change("enable", launch);
+    }
+    async disable() {
+        await this.change("disable");
+    }
+    async change(operation, launch) {
+        for await (const event of this.system.transport.lifecycle({
+            word: "startup", handle: this.program.address(), operation, launch
+        })) {
+            if (event.event === "startup")
+                return;
+        }
+        throw new Error("The System did not confirm the Program startup change");
     }
 }
 class ProgramProcesses extends Events {
@@ -161,13 +237,62 @@ class ProgramProcesses extends Events {
         const found = (await this.list()).find(process => process.identity === identityOrName || process.name === identityOrName);
         return found ?? null;
     }
-    create(launch = {}) { return createProcess(this.system, "create", this.program.identity, launch); }
-    findOrCreate(launch) { return createProcess(this.system, "findOrCreate", this.program.identity, launch); }
+    create(launch = {}) { return this.createExact("create-process", launch); }
+    async *run(launch = {}, options = {}) {
+        let process = null;
+        for await (const event of this.system.transport.lifecycle({
+            word: "run-process",
+            handle: this.program.address(),
+            launch
+        }, options.signal)) {
+            if (event.event === "started") {
+                process = new ProcessHandle(this.system, required(event.process));
+                yield Object.freeze({ event: "started", process });
+            }
+            else if (event.event === "output") {
+                if ((event.stream !== "stdout" && event.stream !== "stderr") || typeof event.text !== "string") {
+                    throw new Error("The System returned an invalid Process output event");
+                }
+                yield Object.freeze({
+                    event: "output",
+                    stream: event.stream,
+                    text: event.text
+                });
+            }
+            else if (event.event === "exited") {
+                if (!process)
+                    throw new Error("The System ended a Process before confirming its start");
+                const value = event.exit;
+                if (!value
+                    || (value.status !== "exited" && value.status !== "signaled")
+                    || (value.code !== null && typeof value.code !== "number")
+                    || (value.signal !== null && typeof value.signal !== "string")) {
+                    throw new Error("The System returned an invalid Process exit event");
+                }
+                const exit = Object.freeze({
+                    status: value.status,
+                    code: value.code,
+                    signal: value.signal
+                });
+                yield Object.freeze({ event: "exited", process, exit });
+            }
+            else
+                throw new Error("The System returned an unknown Process run event");
+        }
+    }
+    findOrCreate(launch) { return this.createExact("find-or-create-process", launch); }
     async exitAll() {
         const processes = await this.list();
         await Promise.all(processes.map(process => process.exit()));
         return processes.map(process => process.identity);
     }
+    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));
+        }
+        throw new Error("The System did not confirm the created Process");
+    }
 }
 class ProcessRegistry extends Events {
     system;
@@ -280,14 +405,14 @@ class ClientEndpoint extends EndpointHandle {
     window;
     constructor(system, owner) {
         super(system, owner, "client");
-        this.window = new GatewayWindow(system, owner);
+        this.window = new SystemWindow(system, owner);
     }
     async start(overrides) { await this.operation("start", overrides); }
     async service() {
         return await super.service();
     }
 }
-class GatewayWindow extends Events {
+class SystemWindow extends Events {
     system;
     process;
     constructor(system, process) {
@@ -393,10 +518,6 @@ async function listProcesses(system, program) {
             return processes;
     }
 }
-async function createProcess(system, operation, program, launch) {
-    const snapshot = await system.transport.control({ capability: "process", operation, input: { program, launch } });
-    return new ProcessHandle(system, snapshot);
-}
 async function* command(system, request) {
     for await (const event of system.transport.lifecycle(request)) {
         if (event.event === "output")

package/dist/transport.d.ts

@@ -1,11 +1,11 @@
 import { type Socket } from "node:net";
-export interface GatewayEvent {
+export interface TransportEvent {
     event?: string;
     [key: string]: unknown;
 }
-/** Open and retain one owner-local Gateway connection. */
+/** Open and retain one owner-local System connection. */
 export declare function openConnection(path: string): Promise<Socket>;
 /** Execute one short authoritative System-control request. */
 export declare function request(path: string, target: "api" | "system", request: unknown, signal?: AbortSignal): Promise<unknown>;
 /** Stream one Program lifecycle operation until the System completes it. */
-export declare function streamProgram(path: string, request: unknown, signal?: AbortSignal): AsyncGenerator<GatewayEvent, void, unknown>;
+export declare function streamProgram(path: string, request: unknown, signal?: AbortSignal): AsyncGenerator<TransportEvent, void, unknown>;

package/dist/transport.js

@@ -1,5 +1,5 @@
 import { connect } from "node:net";
-/** Open and retain one owner-local Gateway connection. */
+/** Open and retain one owner-local System connection. */
 export function openConnection(path) {
     return new Promise((resolve, reject) => {
         const socket = connect(path);
@@ -39,7 +39,7 @@ export function request(path, target, request, signal) {
                 outcome = JSON.parse(buffer.slice(0, boundary));
             }
             catch {
-                return finish(() => reject(new Error("The System returned an invalid Gateway response")));
+                return finish(() => reject(new Error("The System returned an invalid response")));
             }
             if (outcome.success)
                 finish(() => resolve(outcome.result));
@@ -47,7 +47,7 @@ export function request(path, target, request, signal) {
                 finish(() => reject(new Error(outcome.error)));
         });
         socket.on("error", () => finish(() => reject(unavailable(path))));
-        socket.on("close", () => finish(() => reject(new Error("The System closed the Gateway request without an answer"))));
+        socket.on("close", () => finish(() => reject(new Error("The System closed the request without an answer"))));
         if (signal?.aborted)
             cancel();
     });
@@ -95,19 +95,25 @@ export function streamProgram(path, request, signal) {
         wake = null;
     });
     return (async function* () {
-        while (true) {
-            if (events.length) {
-                yield events.shift();
-                continue;
+        try {
+            while (true) {
+                if (events.length) {
+                    yield events.shift();
+                    continue;
+                }
+                if (failure)
+                    throw failure;
+                if (ended)
+                    return;
+                await new Promise(resolve => { wake = resolve; });
             }
-            if (failure)
-                throw failure;
-            if (ended)
-                return;
-            await new Promise(resolve => { wake = resolve; });
+        }
+        finally {
+            signal?.removeEventListener("abort", cancel);
+            socket.destroy();
         }
     })();
 }
 function unavailable(path) {
-    return new Error(`No System Gateway is listening at ${path} — start PhreshOS first`);
+    return new Error(`No System is listening at ${path} — start PhreshOS first`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/node",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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.21",
+    "@phreshos/core": "^0.1.22",
     "adm-zip": "^0.6.0",
     "jiti": "^2.7.0"
   },

package/dist/gateway.d.ts

@@ -1,49 +0,0 @@
-import type { ProgramDescription, System, SystemControlClient, SystemControlRequest } from "@phreshos/core";
-import { Project, type PackedProject } from "./project.js";
-import { type GatewayEvent } from "./transport.js";
-/** One explicit owner-local connection to a running PhreshOS System. */
-export declare class Gateway implements SystemControlClient {
-    private readonly connection;
-    readonly home: string;
-    readonly address: string;
-    readonly system: System;
-    private closed;
-    private readonly lifetime;
-    private constructor();
-    /** Connect to an already running System selected by argument, environment, or owner default. */
-    static open(home?: string): Promise<Gateway>;
-    /** Execute one operation from the transport-neutral System-control vocabulary. */
-    execute(request: SystemControlRequest, signal?: AbortSignal): Promise<unknown>;
-    /** Build and package one local Program project. */
-    pack(project: Project): Promise<PackedProject>;
-    /** Install one local Program project in this Gateway's System. */
-    install(source: Project | ProgramDescription, options?: InstallOptions): AsyncGenerator<GatewayEvent, void, void>;
-    /** Build and start one local production Program, attached to this Gateway. */
-    start(project: Project, options?: RunOptions): AsyncGenerator<GatewayEvent, void, unknown>;
-    /** Start one local Program in development, including its declared Client development server. */
-    dev(project: Project, options?: RunOptions): AsyncGenerator<GatewayEvent, void, unknown>;
-    /** Uninstall one Program by identity or local Project. */
-    uninstall(program: string | Project, options?: UninstallOptions): AsyncGenerator<GatewayEvent, void, void>;
-    /** Close this Gateway without stopping the System. */
-    close(): Promise<void>;
-    private runProject;
-    private program;
-    private control;
-    private api;
-    private lifecycle;
-    private signal;
-    private requireOpen;
-}
-export interface InstallOptions {
-    run?: boolean;
-    startup?: boolean;
-    signal?: AbortSignal;
-}
-export interface RunOptions {
-    options?: Record<string, string>;
-    signal?: AbortSignal;
-}
-export interface UninstallOptions {
-    everything?: boolean;
-    signal?: AbortSignal;
-}

package/dist/gateway.js

@@ -1,151 +0,0 @@
-import { gatewayAddress } from "./address.js";
-import { resolveHome } from "./home.js";
-import { Project } from "./project.js";
-import { openConnection, request as gatewayRequest, streamProgram } from "./transport.js";
-import { gatewaySystem } from "./system.js";
-import { assertAvailable, commandFailure, DevelopmentClient, waitForDevelopmentClient } from "./client-development.js";
-/** One explicit owner-local connection to a running PhreshOS System. */
-export class Gateway {
-    connection;
-    home;
-    address;
-    system;
-    closed = false;
-    lifetime = new AbortController();
-    constructor(home, address, connection) {
-        this.connection = connection;
-        this.home = home;
-        this.address = address;
-        this.system = gatewaySystem({
-            control: (request, signal) => this.control(request, signal),
-            api: (request, signal) => this.api(request, signal),
-            lifecycle: (request, signal) => this.lifecycle(request, signal)
-        });
-    }
-    /** Connect to an already running System selected by argument, environment, or owner default. */
-    static async open(home) {
-        const resolvedHome = resolveHome(home);
-        const address = gatewayAddress(resolvedHome);
-        const connection = await openConnection(address);
-        return new Gateway(resolvedHome, address, connection);
-    }
-    /** Execute one operation from the transport-neutral System-control vocabulary. */
-    execute(request, signal) {
-        this.requireOpen();
-        return this.control(request, signal);
-    }
-    /** Build and package one local Program project. */
-    pack(project) {
-        this.requireOpen();
-        return project.pack();
-    }
-    /** Install one local Program project in this Gateway's System. */
-    async *install(source, options = {}) {
-        this.requireOpen();
-        if (source instanceof Project)
-            await source.build();
-        const program = source instanceof Project ? source.description("production") : source;
-        yield* this.program({
-            word: "install",
-            program,
-            run: options.run === true,
-            startup: options.startup === true
-        }, options.signal);
-    }
-    /** Build and start one local production Program, attached to this Gateway. */
-    start(project, options = {}) {
-        this.requireOpen();
-        return this.runProject(project, "production", options);
-    }
-    /** Start one local Program in development, including its declared Client development server. */
-    dev(project, options = {}) {
-        this.requireOpen();
-        return this.runProject(project, "development", options);
-    }
-    /** Uninstall one Program by identity or local Project. */
-    uninstall(program, options = {}) {
-        this.requireOpen();
-        const identity = typeof program === "string" ? program : program.config.identity;
-        return this.program({ word: "uninstall", identity, everything: options.everything === true }, options.signal);
-    }
-    /** Close this Gateway without stopping the System. */
-    async close() {
-        if (this.closed)
-            return;
-        this.closed = true;
-        this.lifetime.abort(new Error("This Gateway is closed"));
-        this.connection.destroy();
-    }
-    async *runProject(project, mode, options) {
-        if (mode === "production")
-            await project.build();
-        const program = project.description(mode);
-        const development = mode === "development" && program.client && (program.client.start ?? true)
-            ? project.config.client?.development
-            : undefined;
-        const command = development?.startCommand;
-        if (command)
-            await assertAvailable(development.url);
-        const client = command ? new DevelopmentClient(command, project.directory) : undefined;
-        const controller = new AbortController();
-        const signal = this.signal(options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal);
-        try {
-            if (development)
-                yield* waitForDevelopmentClient(development, client, signal);
-            const lifecycle = this.program({ word: "run", program, options: options.options ?? {} }, signal);
-            const iterator = lifecycle[Symbol.asyncIterator]();
-            let lifecycleNext = iterator.next();
-            let exit = client?.exited();
-            let output = client?.outputAvailable();
-            while (true) {
-                for (const event of client?.drain() ?? [])
-                    yield event;
-                const outcome = await Promise.race([
-                    lifecycleNext.then(result => ({ source: "system", result })),
-                    ...(exit ? [exit.then(result => ({ source: "client", result }))] : []),
-                    ...(output ? [output.then(() => ({ source: "output" }))] : [])
-                ]);
-                if (outcome.source === "output") {
-                    output = client?.outputAvailable();
-                    continue;
-                }
-                if (outcome.source === "client") {
-                    exit = undefined;
-                    if (!client?.endingWasRequested())
-                        throw commandFailure(outcome.result);
-                    continue;
-                }
-                if (outcome.result.done)
-                    return;
-                yield outcome.result.value;
-                lifecycleNext = iterator.next();
-            }
-        }
-        finally {
-            controller.abort(new Error("The local Program run ended"));
-            await client?.stop();
-        }
-    }
-    program(request, signal) {
-        return this.lifecycle(request, signal);
-    }
-    control(request, signal) {
-        this.requireOpen();
-        return gatewayRequest(this.address, "system", request, this.signal(signal));
-    }
-    api(request, signal) {
-        this.requireOpen();
-        return gatewayRequest(this.address, "api", request, this.signal(signal));
-    }
-    lifecycle(request, signal) {
-        this.requireOpen();
-        return streamProgram(this.address, request, this.signal(signal));
-    }
-    signal(signal) {
-        return signal ? AbortSignal.any([signal, this.lifetime.signal]) : this.lifetime.signal;
-    }
-    requireOpen() {
-        if (this.closed)
-            throw new Error("This Gateway is closed");
-    }
-}