@phreshos/node 0.1.0 → 0.1.2

package/README.md

@@ -3,37 +3,64 @@
 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
+for await (const chunk of await project.install(system)) {
+  process[chunk.stream].write(chunk.text)
 }
 
-// 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 */ }
+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()
+```
+
+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 })
 ```
 
-`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.
+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. 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/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 { Client, Endpoint, Process, Program, Server, 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 } from "./project.js";

package/dist/main.js

@@ -1,5 +1,4 @@
 export { gatewayAddress } from "./address.js";
-export { Gateway } from "./gateway.js";
+export { Client, Endpoint, Process, Program, Server, 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 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,21 +6,38 @@ 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 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;
 }
 export type ProjectMode = "production" | "development";
 export interface ProjectOptions {
     directory?: string;
 }
+export interface ProjectRunOptions {
+    options?: Record<string, string>;
+    signal?: AbortSignal;
+}
 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";
@@ -29,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());
     }
@@ -44,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);
@@ -101,6 +108,21 @@ export class Project {
             });
         });
     }
+    /** Build this Project and return its production Process lifecycle generator. */
+    async start(system, options = {}) {
+        await this.build();
+        return await this.run(system, this.productionDefinition(), options);
+    }
+    /** Return this Project's development Process lifecycle generator. */
+    async dev(system, options = {}) {
+        return await this.run(system, this.developmentDefinition(), options);
+    }
+    /** Build this Project and return its Program installation generator. */
+    async install(system) {
+        await this.build();
+        const program = await system.forceCreateProgram(this.productionDefinition());
+        return program.install();
+    }
     /** Build and package this Program into its canonical release shape. */
     async pack() {
         await this.build();
@@ -118,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();
@@ -131,14 +153,18 @@ export class Project {
         writeFileSync(checksumPath, `${digest}  ${archive}\n`);
         return Object.freeze({ archive, archivePath, checksumPath, declarationPath, digest });
     }
+    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 };
@@ -229,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,9 +1,255 @@
-import { type System } from "@phreshos/core";
-import type { GatewayEvent } from "./transport.js";
-export interface SystemTransport {
+import { Client as CoreClient, ClientServiceHandler as CoreClientServiceHandler, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerServiceHandler as CoreServerServiceHandler, type ClientDeclaration, type ClientServiceChannel, type EndpointDeclaration, type Launch, type LaunchClient, type Position, type ProgramDefinition, type ProgramCommandChunk, type ServerServiceChannel, 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;
+}>;
+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;
+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;
+    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 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: ProgramDefinition | 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>;
+    programHandle(snapshot: ProgramSnapshot): ProgramHandle;
+    processHandle(snapshot: ProcessSnapshot): ProcessHandle;
+    private signal;
+    private requireConnected;
+}
+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, 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>;
+}
+interface ClientEndpoint extends SystemClientEntity {
+}
+declare class ClientEndpoint extends ClientBase {
+    readonly endpoint: "client";
+    readonly window: SystemWindow;
+    private readonly base;
+    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;
+}
+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>;
+}
+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 {};